com.adobe.granite.workflow.WorkflowSession Maven / Gradle / Ivy
/*************************************************************************
*
* ADOBE CONFIDENTIAL
* __________________
*
* Copyright 2012 Adobe Systems Incorporated
* All Rights Reserved.
*
* NOTICE: All information contained herein is, and remains
* the property of Adobe Systems Incorporated and its suppliers,
* if any. The intellectual and technical concepts contained
* herein are proprietary to Adobe Systems Incorporated and its
* suppliers and are protected by trade secret or copyright law.
* Dissemination of this information or reproduction of this material
* is strictly forbidden unless prior written permission is obtained
* from Adobe Systems Incorporated.
**************************************************************************/
package com.adobe.granite.workflow;
import com.adobe.granite.workflow.collection.util.ResultSet;
import com.adobe.granite.workflow.exec.HistoryItem;
import com.adobe.granite.workflow.exec.InboxItem;
import com.adobe.granite.workflow.exec.Participant;
import com.adobe.granite.workflow.exec.Route;
import com.adobe.granite.workflow.exec.WorkItem;
import com.adobe.granite.workflow.exec.Workflow;
import com.adobe.granite.workflow.exec.WorkflowData;
import com.adobe.granite.workflow.exec.filter.InboxItemFilter;
import com.adobe.granite.workflow.exec.filter.WorkItemFilter;
import com.adobe.granite.workflow.model.VersionException;
import com.adobe.granite.workflow.model.WorkflowModel;
import com.adobe.granite.workflow.model.WorkflowModelFilter;
import com.adobe.granite.workflow.model.WorkflowNode;
import org.apache.sling.api.adapter.Adaptable;
import java.security.AccessControlException;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
/**
*
* 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 extends Adaptable {
/**
* 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 for 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.
*/
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 filter for workflow models
* @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, 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}, {@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. e
* @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;
/**
* Retrieves all the active {@link InboxItem}s assigned to user for this {@link WorkflowSession} instance.
*
* Use this method instead of {@link com.adobe.granite.workflow.WorkflowSession#getActiveWorkItems(long, long, com.adobe.granite.workflow.exec.filter.WorkItemFilter)} ()}
* if you wish to retrieve both WorkItems (which is an InboxItem) and InboxItems from other InboxItem providers
* @param start Start index of the result set. zero based, pass 0 to start at beginning
* @param limit Limit of the result set. pass -1 for no limit.
* @param filter filter for inbox items
* @return a ResultSet of Inbox Items
* @throws WorkflowException Thrown in case an exception occurs while fetching all {@link InboxItem}s.
*/
ResultSet getActiveInboxItems(long start, long limit, InboxItemFilter filter) throws WorkflowException;
/**
* Retrieves all the active {@link InboxItem}s assigned to user for this {@link WorkflowSession} instance.
*
* Use this method instead of {@link com.adobe.granite.workflow.WorkflowSession#getActiveWorkItems(long, long, com.adobe.granite.workflow.exec.filter.WorkItemFilter)} ()}
* if you wish to retrieve both WorkItems (which is an InboxItem) and InboxItems from other InboxItem providers
* @param start Start index of the result set. zero based, pass 0 to start at beginning
* @param limit Limit of the result set. pass -1 for no limit.
* @param itemSubType The sub-type of the inbox item.
* @param filter filter for inbox items
* @return a ResultSet of Inbox Items
* @throws WorkflowException Thrown in case an exception occurs while fetching all {@link InboxItem}s.
*/
ResultSet getActiveInboxItems(long start, long limit, String itemSubType, InboxItemFilter 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
* {@link 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.
* @param expand Expands the group members if the destination points to a
* group. Means that not only the group is returned 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.
* @param expand Expands the group members if the destination points to a
* group. Means that not only the group is returned 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 delegates as Participant who are
* allowed to take over the WorkItem
*
* @param item The workitem
* @return The list of Participants who are allowed to act as delegates.
* @throws WorkflowException in case the delegates could not be retrieved for some reason
*/
Iterator getDelegates(WorkItem item) throws WorkflowException;
/**
* Delegates the WorkItem to the specified Principal.
*
* @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, Participant participant) throws WorkflowException, AccessControlException;
/**
* The complete ordered list of {@link com.adobe.granite.workflow.exec.HistoryItem}
* s is returned for the given {@link Workflow} instance.
*
* @param instance {@link Workflow} instance
* @return List of {@link com.adobe.granite.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 {@code 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;
}