com.day.cq.workflow.WorkflowSession Maven / Gradle / Ivy

/*
 * 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.
     * 
     * @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 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} 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's recommended to use {@link #startWorkflow(WorkflowModel, WorkflowData, Map 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}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.
     * 
     * @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;
}