Source code: org/jbpm/workflow/execution/ExecutionComponent.java
1 package org.jbpm.workflow.execution;
2
3 import java.util.*;
4 import org.jbpm.util.client.*;
5
6 /**
7 * is the session facade that exposes the interface for the execution of processes.
8 * <h3>WfMC</h3>
9 * <p>In <a href="http://www.wfmc.org/standards/docs.htm">WfMC-terminology</a> this is interface 2 : Workflow Client API.
10 * </p>
11 *
12 * <h3 id="authentication">Authentication</h3>
13 * <p>Authentication is letting the ExecutionSession-bean know which user is calling a method.
14 * There are 2 ways of authenticating the User that executes a method upon an ExecutionSession-bean.
15 * <ol>
16 * <li>using J2EE-security and the stateless session bean. See {@link ExecutionSecuredSessionLocalHome}</li>
17 * <li>using the statefull non-secure session bean. See {@link ExecutionSessionLocalHome}. In this
18 * case, the client can freely specify the user-name.</li>
19 * </p>
20 *
21 * <h3>Component interface</h3>
22 * <p>The two most important interactions with the ExecutionSession-bean are
23 * <ol>
24 * <li><b>Start a process instance</b> : first you need to know the id of the process definition
25 * you want to start. This can be done by e.g. {@link #getProcessDefinitions()}. Then start a process
26 * instance with {@link #startProcessInstance(Long processDefinitionId)}.
27 * </li>
28 * <li><b>Perform an activity for a flow</b> : first a user can get the list of
29 * flows for which he/she is supposed to act through {@link #getTaskList()}.
30 * Then the user can perform the activity with {@link #performActivity(Long,Map)}
31 * </li>
32 * </ol>
33 * </p>
34 *
35 * @see org.jbpm.workflow.organisation.OrganisationSessionLocal
36 * @see org.jbpm.workflow.definition.DefinitionSessionLocal
37 * @author Tom Baeyens
38 */
39 public interface ExecutionComponent {
40
41
42 /**
43 * collects all {@link org.jbpm.workflow.execution.Flow}s for which the authenticated
44 * user has to perform an activity.
45 * @return a Collection of {@link org.jbpm.workflow.execution.Flow}s which are
46 * assigned to the <a href="#authentication">user calling this method</a>.
47 */
48 Collection getTaskList();
49
50 /**
51 * collects all {@link org.jbpm.workflow.execution.Flow}s for which the authenticated
52 * user has to perform an activity.
53 * @param relations specifies which {@link Relations} should be resolved in the
54 * returned {@link org.jbpm.workflow.execution.Flow}s
55 * @return a Collection of {@link org.jbpm.workflow.execution.Flow}s which are
56 * assigned to the <a href="#authentication">authenticated user</a>.
57 */
58 Collection getTaskList( Relations relations );
59
60 /**
61 * collects all {@link org.jbpm.workflow.execution.Flow}s for which the given
62 * actor has to perform an activity.
63 * @return a Collection of {@link org.jbpm.workflow.execution.Flow}s which are
64 * assigned to the <a href="#authentication">user calling this method</a>.
65 */
66 Collection getTaskList( String actorId );
67
68 /**
69 * collects all {@link org.jbpm.workflow.execution.Flow}s for which the given
70 * actor has to perform an activity.
71 * @param relations specifies which {@link Relations} should be resolved in the
72 * returned {@link org.jbpm.workflow.execution.Flow}s
73 * @return a Collection of {@link org.jbpm.workflow.execution.Flow}s which are
74 * assigned to the <a href="#authentication">authenticated user</a>.
75 */
76 Collection getTaskList( String actorId, Relations relations );
77
78 /**
79 * provides default values (=null) for the optional parameters of
80 * {@link #startProcessInstance(Long,Map,String,Relations)}
81 */
82 ProcessInstance startProcessInstance( Long processDefinitionId );
83
84 /**
85 * provides default values (=null) for the optional parameters of
86 * {@link #startProcessInstance(Long,Map,String,Relations)}
87 */
88 ProcessInstance startProcessInstance( Long processDefinitionId, Map attributeValues );
89
90 /**
91 * provides default values (=null) for the optional parameters of
92 * {@link #startProcessInstance(Long,Map,String,Relations)}
93 */
94 ProcessInstance startProcessInstance( Long processDefinitionId, Map attributeValues, String transitionName );
95
96 /**
97 * creates a new process instance for the given process definition.
98 * Starting a process instance means that the start-activity is performed.
99 * @param processDefinitionId the id of a ProcessDefinition
100 * @param attributeValues maps attribute-names to java-objects. The java-objects will be stored
101 * in the corresponding attribute-instances.
102 * @param transitionName specifies which transition should be taken from the start-state in case
103 * there are more then one.
104 * @param relations specifies which {@link Relations} should be resolved in the
105 * returned {@link org.jbpm.workflow.execution.ProcessInstance}s
106 * @return the created {@link org.jbpm.workflow.execution.ProcessInstance}
107 * @throws IllegalArgumentException if processDefinitionId is null or does not correspond with an existing process definition
108 * @see #getProcessDefinitions() use getProcessDefinitions() to get valid processDefinitionId's
109 */
110 ProcessInstance startProcessInstance( Long processDefinitionId, Map attributeValues, String transitionName, Relations relations );
111
112 /**
113 * fetches all web-interface information for the start of a process instance.
114 * @throws AttributeSerializationException if the attributes that are stored in the database as
115 * text can't be parsed to a java-object with the {@link org.jbpm.workflow.delegation.Serializer}
116 * @throws ExecutionRuntimeException for all other troubles
117 */
118 ActivityForm getStartForm( Long processDefinitionId );
119
120 /**
121 * fetches all web-interface information for the activity of a flow.
122 * @throws AttributeSerializationException if the attributes that are stored in the database as
123 * text can't be parsed to a java-object with the {@link org.jbpm.workflow.delegation.Serializer}
124 * @throws ExecutionRuntimeException for all other troubles
125 */
126 ActivityForm getActivityForm( Long flowId );
127
128 /**
129 * provides default values (=null) for the optional parameters of
130 * {@link #startProcessInstance(Long,Map,String,Relations)}
131 */
132 Collection performActivity( Long flowId );
133
134 /**
135 * provides default values (=null) for the optional parameters of
136 * {@link #startProcessInstance(Long,Map,String,Relations)}
137 */
138 Collection performActivity( Long flowId, Map attributeValues );
139
140 /**
141 * provides default values (=null) for the optional parameters of
142 * {@link #startProcessInstance(Long,Map,String,Relations)}
143 */
144 Collection performActivity( Long flowId, Map attributeValues, String transitionName );
145
146 /**
147 * performs an {@link ActivityState}.
148 * @return a collection of {@link Flow}'s that are the {@link Flow}s, resulting
149 * from the {@link Flow} on which the {@link Activity} was done, after processing
150 * the {@link Activity} input.
151 * @param flowId is the id of the flow upon which the client wants to act.
152 * Flows can be obtained by {@link #getTaskList()}
153 * @param attributeValues maps attribute-names to java-objects. The java-objects will be stored
154 * in the corresponding attribute-instances.
155 * @param transitionName specifies which transition should be taken from the start-state in case
156 * there are more then one.
157 * @param relations specifies which {@link Relations} should be resolved in the
158 * returned {@link org.jbpm.workflow.execution.Flow}s
159 * @throws RequiredFieldException if not all required fields are
160 * present in the form-values.
161 * @throws AttributeSerializationException if one of the fieldValues
162 * is not serializable by the {@link org.jbpm.workflow.delegation.Serializer}
163 * specified in the corresponding field.
164 * @throws IllegalArgumentException if the {@link Flow} of the form cannot be found.
165 * @throws IllegalStateException if the {@link Flow} is not in an activity-state.
166 */
167 Collection performActivity( Long flowId, Map attributeValues, String transitionName, Relations relations );
168
169 /**
170 * reassigns the {@link Flow} to the specified {@link Actor}.
171 * @param flowId is the flow which the authenticated user wants to delegate
172 * @param actor is the user or group of the user to which the the flow is assigned.
173 * @throws IllegalArgumentException if the flow or the user do not exist.
174 */
175 void delegateActivity( Long flowId, String actorId );
176
177 /**
178 * cancels a complete process instance including all flows that are part of this process instance.
179 * @throws IllegalArgumentException if the flow does not exist.
180 */
181 void cancelProcessInstance( Long processInstanceId );
182
183 /**
184 * cancels one flow without cancelling the complete process instance.
185 * @throws IllegalArgumentException if the flow does not exist.
186 */
187 void cancelFlow( Long flowId );
188
189 /**
190 * collects a flow.
191 * @throws IllegalArgumentException if the flow does not exist.
192 */
193 Flow getFlow( Long flowId );
194
195 /**
196 * collects a flow.
197 * @param relations specifies which {@link Relations} should be resolved in the
198 * returned {@link org.jbpm.workflow.execution.Flow}
199 * @throws IllegalArgumentException if the flow does not exist.
200 */
201 Flow getFlow( Long flowId, Relations relations );
202 }