com.day.cq.workflow.WorkflowSession Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of aem-sdk-api Show documentation
Show all versions of aem-sdk-api Show documentation
The Adobe Experience Manager SDK
/*
* Copyright 1997-2008 Day Management AG
* Barfuesserplatz 6, 4001 Basel, Switzerland
* All Rights Reserved.
*
* This software is the confidential and proprietary information of
* Day Management AG, ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Day.
*/
package com.day.cq.workflow;
import java.security.AccessControlException;
import java.util.Dictionary;
import java.util.List;
import java.util.Map;
import javax.jcr.Session;
import javax.jcr.version.VersionException;
import org.apache.jackrabbit.api.security.user.Authorizable;
import com.day.cq.workflow.collection.util.ResultSet;
import com.day.cq.workflow.exec.HistoryItem;
import com.day.cq.workflow.exec.Route;
import com.day.cq.workflow.exec.WorkItem;
import com.day.cq.workflow.exec.Workflow;
import com.day.cq.workflow.exec.WorkflowData;
import com.day.cq.workflow.exec.filter.WorkItemFilter;
import com.day.cq.workflow.model.WorkflowModel;
import com.day.cq.workflow.model.WorkflowModelFilter;
import com.day.cq.workflow.model.WorkflowNode;
/**
* The WorkflowSession class provides all functionality (depending
* on the users rights) for managing {@link WorkflowModel}s, {@link Workflow}
* instances and their execution.
*
*
* It provides methods to:
*
*
* - deploy/create a workflow models
* - start, stop, suspend, resume and complete a workflow instance
* - retrieve and complete {@link WorkItem}s assigned to a user/group
*
*
*/
public interface WorkflowSession {
/**
* Returns the {@link WorkflowService} that was used to create
* the WorkflowSession instance.
*
* @return The {@link WorkflowService} that was used to create
* the WorkflowSession instance.
*/
WorkflowService getWorkflowService();
/**
* Returns the JCR {@link Session} assigned to the
* WorkflowSession instance.
*
* @return The JCR {@link Session} assigned to the
* WorkflowSession instance.
*/
Session getSession();
/**
* Returns the user that owns the WorkflowSession.
*
* @return The user that owns the WorkflowSession.
*/
Authorizable getUser();
/**
* Evaluate the passed rule by choosing the right rule engine.
*
* @param data
* workflow data to apply the rule
* @param rule
* rule to execute
* @return true if rule evaluation is true or the rule is
* null
*/
boolean evaluate(WorkflowData data, String rule);
/**
* Deploys a new or modified {@link WorkflowModel}.
*
* @param model
* The {@link WorkflowModel} to be deployed.
* @throws WorkflowException
* Thrown in case an error prevents deployment of the
* {@link WorkflowModel}.
*/
void deployModel(WorkflowModel model) throws WorkflowException;
/**
* Creates a new blank {@link WorkflowModel}.
*
* @param title
* The title of the newly created
* {@link WorkflowModel}.
*
* @return The newly created {@link WorkflowModel}.
*
* @throws WorkflowException
* Thrown in case an error prevents creation of the
* {@link WorkflowModel}.
*/
WorkflowModel createNewModel(String title) throws WorkflowException;
/**
* Creates a new blank {@link WorkflowModel} under the given path.
*
* @param title
* The title of the newly created
* {@link WorkflowModel}.
* @param id
* The ID of the new {@link WorkflowModel}.
*
* @return The newly created {@link WorkflowModel}.
*
* @throws WorkflowException
* Thrown in case an error prevents creation of the
* {@link WorkflowModel}.
*/
WorkflowModel createNewModel(String title, String id) throws WorkflowException;
/**
* Deletes the given {@link WorkflowModel}.
*
* @param id
* The ID of the {@link WorkflowModel} to be
* deleted.
* @throws WorkflowException
* Thrown in case an error prevents deployment of the
* {@link WorkflowModel}.
*/
void deleteModel(String id) throws WorkflowException;
/**
* Returns newest versions of all deployed
* {@link WorkflowModel}s.
*
* @return All deployed {@link WorkflowModel} at their newest
* versions.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}s.
*/
WorkflowModel[] getModels() throws WorkflowException;
/**
* Returns newest versions of all deployed
* {@link WorkflowModel}s.
*
* @param filter The {@link WorkflowModelFilter} used for getting workflow models
*
* @return All deployed {@link WorkflowModel} at their newest
* versions.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}.
*/
WorkflowModel[] getModels(WorkflowModelFilter filter) throws WorkflowException;
/**
* Returns newest versions of all deployed
* {@link WorkflowModel}s.
*
*
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
*
*
* @return All deployed {@link WorkflowModel} at their newest
* versions.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}s.
*/
ResultSet getModels(long start, long limit) throws WorkflowException;
/**
* Returns newest versions of all deployed
* {@link WorkflowModel}s.
*
*
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
*
* @param filter The {@link WorkflowModelFilter} used for getting workflow models
*
* @return All deployed {@link WorkflowModel} at their newest
* versions.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}s.
*/
ResultSet getModels(long start, long limit, WorkflowModelFilter filter) throws WorkflowException;
/**
* Returns newest version of the {@link WorkflowModel} with the
* given ID.
*
* @param id
* The ID of the {@link WorkflowModel}.
*
* @return The newest version of the {@link WorkflowModel} with
* the given ID or null, if no {@link WorkflowModel}
* with the given ID exists.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}.
*/
WorkflowModel getModel(String id) throws WorkflowException;
/**
* Returns the {@link WorkflowModel} with the given ID and
* version.
*
* @param id
* The ID of the {@link WorkflowModel}.
* @param version
* The version of the {@link WorkflowModel}.
*
* @return The {@link WorkflowModel} with the given ID and
* version or null, if no {@link WorkflowModel} matches
* the given ID and/or version.
*
* @throws WorkflowException
* Thrown in case an error occurs while fetching the
* {@link WorkflowModel}.
* @throws VersionException
* Thrown in case the version does not exist or can not be
* accessed.
*/
WorkflowModel getModel(String id, String version) throws WorkflowException,
VersionException;
/**
* Start a new {@link Workflow} instance with the given
* {@link WorkflowModel} and {@link WorkflowData}.
*
* @param model
* {@link WorkflowModel} to be used for the new
* {@link Workflow} instance.
* @param data
* {@link WorkflowData} to be attached to the new
* workflow instance.
* @return The {@link Workflow} of the newly started
* {@link Workflow} instance.
*
* @throws WorkflowException
* Thrown in case the workflow process cannot be started.
*/
Workflow startWorkflow(WorkflowModel model, WorkflowData data)
throws WorkflowException;
/**
* Start a new {@link Workflow} instance with the given
* {@link WorkflowModel} and {@link WorkflowData}.
*
* @param model
* {@link WorkflowModel} to be used for the new
* {@link Workflow} instance.
* @param data
* {@link WorkflowData} to be attached to the new
* workflow instance.
* @param metaData
* Meta data assigned to the new {@link Workflow}.
* @return The {@link Workflow} of the newly started
* {@link Workflow} instance.
*
* @throws WorkflowException
* Thrown in case the workflow process cannot be started.
*
* @deprecated It is recommended to use startWorkflow(WorkflowModel, WorkflowData, Map) instead.
*/
Workflow startWorkflow(WorkflowModel model, WorkflowData data,
Dictionary metaData) throws WorkflowException;
/**
* Start a new {@link Workflow} instance with the given
* {@link WorkflowModel}, {@link WorkflowData} and meta data.
*
* @param model
* {@link WorkflowModel} to be used for the new
* {@link Workflow} instance.
* @param data
* {@link WorkflowData} to be attached to the new
* workflow instance.
* @param metaData
* Meta data assigned to the new {@link Workflow}.
* @return The {@link Workflow} of the newly started
* {@link Workflow} instance.
*
* @throws WorkflowException
* Thrown in case the workflow process cannot be started.
*/
Workflow startWorkflow(WorkflowModel model, WorkflowData data,
Map metaData) throws WorkflowException;
/**
* Terminates the given {@link Workflow} instance.
*
* @param instance
* The {@link Workflow} instance that shall be
* terminated.
*
* @throws WorkflowException
* Thrown in case the workflow instance cannot be terminated.
*/
void terminateWorkflow(Workflow instance) throws WorkflowException;
/**
* Resumes the given {@link Workflow} instance.
*
* @param instance
* The {@link Workflow} instance that shall be
* resumed.
*
* @throws WorkflowException
* Thrown in case the workflow instance cannot be resumed.
*/
void resumeWorkflow(Workflow instance) throws WorkflowException;
/**
* Suspends the given {@link Workflow} instance.
*
* @param instance
* The {@link Workflow} of the workflow instance
* that shall be suspended.
*
* @throws WorkflowException
* Thrown in case the workflow instance cannot be suspended.
*/
void suspendWorkflow(Workflow instance) throws WorkflowException;
/**
* All {@link WorkItem}s assigned to an active {@link Workflow}
* instance and the respective user of the WorkflowSession will
* be returned.
*
* @return All {@link WorkItem}s assigned to an active workflow
* and the respective users WorkflowSession.
*
* @throws WorkflowException
* Thrown in case an exception occurs while fetching the active
* {@link WorkItem}s.
*/
WorkItem[] getActiveWorkItems() throws WorkflowException;
/**
* All {@link WorkItem}s assigned to an active {@link Workflow}
* instance and the respective user of the WorkflowSession will
* be returned.
*
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
*
* @return All {@link WorkItem}s assigned to an active workflow
* and the respective users WorkflowSession.
*
* @throws WorkflowException
* Thrown in case an exception occurs while fetching the active
* {@link WorkItem}s.
*/
ResultSet getActiveWorkItems(long start, long limit)
throws WorkflowException;
/**
* All {@link WorkItem}s assigned to an active {@link Workflow}
* instance and the respective user of the WorkflowSession will
* be returned.
*
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
* @param filter
* filter for work items
*
* @return All {@link WorkItem}s assigned to an active workflow
* and the respective users WorkflowSession.
*
* @throws WorkflowException
* Thrown in case an exception occurs while fetching the active
* {@link WorkItem}s.
*/
ResultSet getActiveWorkItems(long start, long limit, WorkItemFilter filter)
throws WorkflowException;
/**
* All {@link WorkItem}s assigned to a {@link Workflow}
* instance and assigned to the respective user of the
* WorkflowSession will be returned.
*
* @return All {@link WorkItem}s assigned to a {@link Workflow}
* instance and the respective users WorkflowSession.
*
* @throws WorkflowException
* Thrown in case an exception occurs while fetching all
* {@link WorkItem}s.
*/
WorkItem[] getAllWorkItems() throws WorkflowException;
/**
* All {@link WorkItem}s assigned to a {@link Workflow}
* instance and assigned to the respective user of the
* WorkflowSession will be returned.
*
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
*
* @return All {@link WorkItem}s assigned to a {@link Workflow}
* instance and the respective users WorkflowSession.
*
* @throws WorkflowException
* Thrown in case an exception occurs while fetching all
* {@link WorkItem}s.
*/
ResultSet getAllWorkItems(long start, long limit)
throws WorkflowException;
/**
* Returns the {@link WorkItem} with the given ID assigned to a
* {@link Workflow} instance, but only if the respective users
* WorkflowSession} has access to it.
*
* @param id
* The ID of the {@link WorkItem}.
* @return The {@link WorkItem} with the given ID.
* @throws WorkflowException
* Thrown in case an exception is occurs while fetching the
* {@link WorkItem}.
*/
WorkItem getWorkItem(String id) throws WorkflowException;
/**
* Returns all {@link Workflow} instances that are in one of
* the given states and to which the
* {@link WorkflowSession} has access to.
*
* @param states
* The list of states used to select the
* {@link Workflow} instances.
*
* @return All {@link Workflow}s that are in one of the given
* states and to which the {@link WorkflowSession} has
* access to.
*
* @throws WorkflowException
* Thrown in case an error occurred while retrieving the
* {@link Workflow}s.
*/
Workflow[] getWorkflows(String[] states) throws WorkflowException;
/**
* Returns all {@link Workflow}s instances that are in one of
* the given states and to which the
* {@link WorkflowSession} has access to.
*
* @param states
* The list of states used to select the
* {@link Workflow} instances.
* @param start
* Start index of the result set.
* @param limit
* Limit of the result set.
*
* @return All {@link Workflow}s that are in one of the given
* states and to which the {@link WorkflowSession} has
* access to.
*
* @throws WorkflowException
* Thrown in case an error occurred while retrieving the
* {@link Workflow}s.
*/
ResultSet getWorkflows(String[] states, long start, long limit)
throws WorkflowException;
/**
* Returns all {@link Workflow}s which the
* {@link WorkflowSession} has access to.
*
* @return All {@link Workflow}s the
* {@link WorkflowSession} has access to.
*
* @throws WorkflowException
* Thrown in case an error occurred while retrieving the
* {@link Workflow}s.
*/
Workflow[] getAllWorkflows() throws WorkflowException;
/**
* Retrieve the {@link Workflow} instance with the given ID.
*
* @param id
* The ID of the {@link Workflow} instance that
* should be returned.
*
* @return The {@link Workflow} instance with the given ID or
* null, if no {@link Workflow} instance ID matches the
* given ID.
*
* @throws WorkflowException
* Thrown in case an unexpected error occurs while retrieving
* the {@link Workflow}.
*/
Workflow getWorkflow(String id) throws WorkflowException;
/**
* Completes the {@link WorkItem} for the assigned
* {@link Workflow} instance and assign to the next
* {@link WorkflowNode} according to the given
* {@link Route}.
*
* @param item
* The {@link WorkItem} to be completed.
* @param route
* The {@link Route} to the destination to be
* advanced.
*
* @throws WorkflowException
* Thrown in case an error is occurs while completing the
* {@link WorkItem}.
*/
void complete(WorkItem item, Route route) throws WorkflowException;
/**
* All {@link Route} to all possible destinations will be
* returned. Rules will be already executed, thus all routes that are active
* can be selected.
*
* @param item
* The {@link WorkItem} to retrieve routes from.
*
* @return All {@link Route}s to advance.
*
* @throws WorkflowException
* Thrown in case an error is occurs while evaluating the
* {@link Route}s.
*/
List getRoutes(WorkItem item) throws WorkflowException;
/**
* All {@link Route} to all possible destinations will be
* returned. Rules will be already executed, thus all routes that are active
* can be selected.
*
* @param item
* The {@link WorkItem} to retrieve routes from.
*
* @param expand
* Expands the group members if the destination points to a
* group. Means that not only the group is retourned as route but
* as well all group members.
*
* @return All {@link Route}s to advance.
*
* @throws WorkflowException
* Thrown in case an error is occurs while evaluating the
* {@link Route}s.
*/
List getRoutes(WorkItem item, boolean expand)
throws WorkflowException;
/**
* All {@link Route} to all possible already passed
* destinations will be returned. Rules will be already executed, thus all
* routes that are active can be selected.
*
* @param item
* The {@link WorkItem} to retrieve back routes
* from.
*
* @return All {@link Route}s to advance (back).
*
* @throws WorkflowException
* Thrown in case an error is occurs while evaluating the
* {@link Route}s.
*/
List getBackRoutes(WorkItem item) throws WorkflowException;
/**
* All {@link Route} to all possible already passed
* destinations will be returned. Rules will be already executed, thus all
* routes that are active can be selected.
*
* @param item
* The {@link WorkItem} to retrieve back routes
* from.
*
* @param expand
* Expands the group members if the destination points to a
* group. Means that not only the group is retourned as route but
* as well all group members.
*
* @return All {@link Route}s to advance (back).
*
* @throws WorkflowException
* Thrown in case an error is occurs while evaluating the
* {@link Route}s.
*/
List getBackRoutes(WorkItem item, boolean expand)
throws WorkflowException;
/**
* Creates a new {@link WorkflowData} instance based on the
* given data.
*
* @param payloadType
* The type of payload for the new
* {@link WorkflowData} instance.
* @param payload
* The payload object used for creating the new
* {@link WorkflowData} instance.
* {@link WorkflowData} instance.
*
* @return The new {@link WorkflowData} instance.
*/
WorkflowData newWorkflowData(String payloadType, Object payload);
/**
* Returns all delegatees as Authorizable who are
* allowed to take over the WorkItem
*
* @param item
* The workitem
*
* @return The list of Authorizables who are allowed to act as
* delegatees.
*
* @throws WorkflowException
* in case the delegatees could not be retrieved for some reason
*/
List getDelegatees(WorkItem item) throws WorkflowException;
/**
* Delegates the WorkItem to the specified
* Authorizable.
*
* @param item
* the corresponding workitem
* @param participant
* the participant to delegate
* @throws java.security.AccessControlException
* if the given participant is not allowed to take over the
* workitem.
* @throws WorkflowException
* in case the delegation fails in regards of persisting the
* "new" state.
*/
void delegateWorkItem(WorkItem item, Authorizable participant)
throws WorkflowException, AccessControlException;
/**
* The complete ordered list of {@link com.day.cq.workflow.exec.HistoryItem}
* s is returned for the given {@link Workflow} instance.
*
* @param instance
* {@link Workflow} instance
*
* @return List of {@link com.day.cq.workflow.exec.HistoryItem}
* s
*
* @throws WorkflowException
* in case the history item retrieval fails
*/
List getHistory(Workflow instance) throws WorkflowException;
/**
* Updates the workflow data of a running workflow instance to the given
* WorkflowData.
*
* @param instance
* The {@link Workflow} instance for which to update the data.
* @param data
* The {@link WorkflowData} for the update.
*/
void updateWorkflowData(Workflow instance, WorkflowData data);
/**
* The logout method has to be called in order to clean up all jcr session
* references.
*/
void logout();
/**
* Checks for the workflow superuser
*
* @return true if the user is a workflow superuser
*/
boolean isSuperuser();
/**
* This method restarts a workflow instance that is in a "stale" state.
* means there is no workitem around. this could happen in case the eventing
* which controls the the script/java processes purges an event/job (there
* is the depending (serialized) workitem stored). The restart tries to
* start the workflow at the position right before the workitem got lost.
* Note: This is an administrative method and can only be used by a
* workflow superuser!
*
* @param workflow
* workflow
* @throws WorkflowException
* in case an error occurs
*/
void restartWorkflow(Workflow workflow) throws WorkflowException;
}