KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > ofbiz > workflow > client > WorkflowClient


1 /*
2  * $Id: WorkflowClient.java 5462 2005-08-05 18:35:48Z jonesde $
3  *
4  * Copyright (c) 2001, 2002 The Open For Business Project - www.ofbiz.org
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the "Software"),
8  * to deal in the Software without restriction, including without limitation
9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  * and/or sell copies of the Software, and to permit persons to whom the
11  * Software is furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included
14  * in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
21  * OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
22  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  *
24  */
25 package org.ofbiz.workflow.client;
26
27 import java.sql.Timestamp JavaDoc;
28 import java.util.Iterator JavaDoc;
29 import java.util.Map JavaDoc;
30
31 import org.ofbiz.base.util.Debug;
32 import org.ofbiz.entity.GenericDelegator;
33 import org.ofbiz.service.DispatchContext;
34 import org.ofbiz.service.LocalDispatcher;
35 import org.ofbiz.service.job.Job;
36 import org.ofbiz.service.job.JobManagerException;
37 import org.ofbiz.workflow.CannotStop;
38 import org.ofbiz.workflow.NotRunning;
39 import org.ofbiz.workflow.WfActivity;
40 import org.ofbiz.workflow.WfAssignment;
41 import org.ofbiz.workflow.WfException;
42 import org.ofbiz.workflow.WfExecutionObject;
43 import org.ofbiz.workflow.WfFactory;
44 import org.ofbiz.workflow.WfProcess;
45 import org.ofbiz.workflow.WfResource;
46
47 /**
48  * Workflow Client - Client API to the Workflow Engine.
49  *
50  * @author <a HREF="mailto:jaz@ofbiz.org">Andy Zeneski</a>
51  * @version $Rev: 5462 $
52  * @since 2.0
53  */
54 public class WorkflowClient {
55
56     public static final String JavaDoc module = WorkflowClient.class.getName();
57     
58     protected GenericDelegator delegator = null;
59     protected LocalDispatcher dispatcher = null;
60   
61     protected WorkflowClient() {}
62     
63     /**
64      * Get a new instance of the Workflow Client
65      * @param delegator the GenericDelegator object which matchs the delegator used by the workflow engine.
66      * @param dispatcher a LocalDispatcher object to invoke the workflow services.
67      */
68     public WorkflowClient(GenericDelegator delegator, LocalDispatcher dispatcher) {
69         if (delegator == null)
70             throw new IllegalArgumentException JavaDoc("GenericDelegator cannot be null");
71         if (dispatcher == null)
72             throw new IllegalArgumentException JavaDoc("LocalDispatcher cannot be null");
73         this.delegator = delegator;
74         this.dispatcher = dispatcher;
75     }
76
77     /**
78      * Get a new instance of the Workflow Client
79      * @param dctx A DispatchContext object.
80      * *** Note the delegator from this object must match the delegator used by the workflow engine.
81      */
82     public WorkflowClient(DispatchContext context) {
83         this(context.getDelegator(), context.getDispatcher());
84     }
85
86     /**
87      * Create an activity assignment.
88      * @param workEffortId The WorkEffort entity ID for the activitiy.
89      * @param partyId The assigned / to be assigned users party ID.
90      * @param roleTypeId The assigned / to be assigned role type ID.
91      * @param append Append this assignment to the list, if others exist.
92      * @return The new assignment object.
93      * @throws WfException
94      */
95     public WfAssignment assign(String JavaDoc workEffortId, String JavaDoc partyId, String JavaDoc roleTypeId, Timestamp JavaDoc fromDate, boolean append) throws WfException {
96         WfActivity activity = WfFactory.getWfActivity(delegator, workEffortId);
97         WfResource resource = WfFactory.getWfResource(delegator, null, null, partyId, roleTypeId);
98
99         if (!append) {
100             Iterator JavaDoc i = activity.getIteratorAssignment();
101
102             while (i.hasNext()) {
103                 WfAssignment a = (WfAssignment) i.next();
104                 a.remove();
105             }
106         }
107         return WfFactory.getWfAssignment(activity, resource, fromDate, true);
108     }
109
110     /**
111      * Accept an activity assignment.
112      * @param workEffortId The WorkEffort entity ID for the activitiy.
113      * @param partyId The assigned / to be assigned users party ID.
114      * @param roleTypeId The assigned / to be assigned role type ID.
115      * @param fromDate The assignment's from date.
116      * @throws WfException
117      */
118     public void accept(String JavaDoc workEffortId, String JavaDoc partyId, String JavaDoc roleTypeId, Timestamp JavaDoc fromDate) throws WfException {
119         WfAssignment assign = WfFactory.getWfAssignment(delegator, workEffortId, partyId, roleTypeId, fromDate);
120         assign.accept();
121     }
122
123     /**
124      * Accept an activity assignment and begin processing.
125      * @param workEffortId The WorkEffort entity ID for the activitiy.
126      * @param partyId The assigned / to be assigned users party ID.
127      * @param roleTypeId The assigned / to be assigned role type ID.
128      * @param fromDate The assignment's from date.
129      * @return GenericResultWaiter of the start job.
130      * @throws WfException
131      */
132     public void acceptAndStart(String JavaDoc workEffortId, String JavaDoc partyId, String JavaDoc roleTypeId, Timestamp JavaDoc fromDate) throws WfException {
133         accept(workEffortId, partyId, roleTypeId, fromDate);
134         start(workEffortId);
135     }
136
137     /**
138      * Delegate an activity assignment.
139      * @param workEffortId The WorkEffort entity ID for the activitiy.
140      * @param fromPartyId The current assignment partyId.
141      * @param fromRoleTypeId The current assignment roleTypeId.
142      * @param fromFromDate The current assignment fromDate.
143      * @param toPartyId The new delegated assignment partyId.
144      * @param toRoleTypeId The new delegated assignment roleTypeId.
145      * @param toFromDate The new delegated assignment fromDate.
146      * @return The new assignment object.
147      * @throws WfException
148      */
149     public WfAssignment delegate(String JavaDoc workEffortId, String JavaDoc fromPartyId, String JavaDoc fromRoleTypeId, Timestamp JavaDoc fromFromDate, String JavaDoc toPartyId, String JavaDoc toRoleTypeId, Timestamp JavaDoc toFromDate) throws WfException {
150         WfActivity activity = WfFactory.getWfActivity(delegator, workEffortId);
151         WfAssignment fromAssign = null;
152         
153         // check status and delegateAfterStart attribute
154 if (activity.state().equals("open.running") && !activity.getDefinitionObject().getBoolean("delegateAfterStart").booleanValue())
155             throw new WfException("This activity cannot be delegated once it has been started");
156                       
157         if (fromPartyId == null && fromRoleTypeId == null && fromFromDate == null) {
158             Iterator JavaDoc i = activity.getIteratorAssignment();
159             fromAssign = (WfAssignment) i.next();
160             if (i.hasNext()) {
161                 throw new WfException("Cannot locate the assignment to delegate from, there is more then one " +
162                         "assignment for this activity.");
163             }
164         }
165
166         if (fromAssign == null) {
167             fromAssign = WfFactory.getWfAssignment(delegator, workEffortId, fromPartyId, fromRoleTypeId, fromFromDate);
168         }
169         fromAssign.delegate();
170         
171         // check for a restartOnDelegate
172 WfActivity newActivity = null;
173         if (activity.getDefinitionObject().getBoolean("restartOnDelegate").booleanValue()) {
174             // this only applies to running single assignment activities
175 if (activity.state().equals("open.running") && activity.howManyAssignment() == 0) {
176                 try {
177                     activity.abort();
178                 } catch (CannotStop cs) {
179                     throw new WfException("Cannot stop the current activity");
180                 } catch (NotRunning nr) {
181                     throw new WfException("Current activity is not running; cannot abort");
182                 }
183                 String JavaDoc parentProcessId = activity.container().runtimeKey();
184                 newActivity = WfFactory.getWfActivity(activity.getDefinitionObject(), parentProcessId);
185             }
186         }
187         
188         WfAssignment assign = null;
189         if (newActivity != null) {
190             assign = assign(newActivity.runtimeKey(), toPartyId, toRoleTypeId, toFromDate, true);
191         } else {
192             assign = assign(workEffortId, toPartyId, toRoleTypeId, toFromDate, true);
193         }
194         
195         return assign;
196     }
197
198     /**
199      * Delegate and accept an activity assignment.
200      * @param workEffortId The WorkEffort entity ID for the activitiy.
201      * @param partyId The assigned / to be assigned users party ID.
202      * @param roleTypeId The assigned / to be assigned role type ID.
203      * @param fromDate The assignment's from date.
204      * @param start True to attempt to start the activity.
205      * @return GenericResultWaiter of the start job.
206      * @throws WfException
207      */
208     public void delegateAndAccept(String JavaDoc workEffortId, String JavaDoc fromPartyId, String JavaDoc fromRoleTypeId, Timestamp JavaDoc fromFromDate, String JavaDoc toPartyId, String JavaDoc toRoleTypeId, Timestamp JavaDoc toFromDate, boolean start) throws WfException {
209         WfAssignment assign = delegate(workEffortId, fromPartyId, fromRoleTypeId, fromFromDate, toPartyId, toRoleTypeId, toFromDate);
210         assign.accept();
211         Debug.logVerbose("Delegated assignment.", module);
212         
213         if (start) {
214             Debug.logVerbose("Starting activity.", module);
215             if (!activityRunning(assign.activity())) {
216                 start(assign.activity().runtimeKey());
217             } else {
218                 Debug.logWarning("Activity already running; not starting.", module);
219             }
220         } else {
221             Debug.logVerbose("Not starting assignment.", module);
222         }
223     }
224
225     /**
226      * Start the activity.
227      * @param workEffortId The WorkEffort entity ID for the activitiy.
228      * @return GenericResultWaiter of the start job.
229      * @throws WfException
230      */
231     public void start(String JavaDoc workEffortId) throws WfException {
232         if (dispatcher == null) {
233             throw new WfException("LocalDispatcher is null; cannot create job for activity startup");
234         }
235         
236         WfActivity activity = WfFactory.getWfActivity(delegator, workEffortId);
237
238         if (Debug.verboseOn()) Debug.logVerbose("Starting activity: " + activity.name(), module);
239         if (activityRunning(activity))
240             throw new WfException("Activity is already running");
241             
242         Job job = new StartActivityJob(activity);
243
244         if (Debug.verboseOn()) Debug.logVerbose("Job: " + job, module);
245         try {
246             dispatcher.getJobManager().runJob(job);
247         } catch (JobManagerException e) {
248             throw new WfException(e.getMessage(), e);
249         }
250                
251     }
252
253     /**
254      * Complete an activity assignment and follow the next transition(s).
255      * @param workEffortId The WorkEffort entity ID for the activity.
256      * @param partyId The assigned / to be assigned users party ID.
257      * @param roleTypeId The assigned / to be assigned role type ID.
258      * @param fromDate The assignment's from date.
259      * @return GenericResultWaiter for the complete job.
260      * @throws WfException
261      */
262     public void complete(String JavaDoc workEffortId, String JavaDoc partyId, String JavaDoc roleTypeId, Timestamp JavaDoc fromDate, Map JavaDoc result) throws WfException {
263         WfAssignment assign = WfFactory.getWfAssignment(delegator, workEffortId, partyId, roleTypeId, fromDate);
264         if (result != null && result.size() > 0)
265             assign.setResult(result);
266         assign.complete();
267     }
268     
269     /**
270      * Suspend an activity
271      * @param workEffortId The WorkEffort entity key for the activity object
272      * @throws WfException
273      */
274     public void suspend(String JavaDoc workEffortId) throws WfException {
275         WfActivity activity = WfFactory.getWfActivity(delegator, workEffortId);
276         
277         if (Debug.verboseOn()) Debug.logVerbose("Suspending activity: " + activity.name(), module);
278         if (!activityRunning(activity))
279             throw new WfException("Activity is not running");
280             
281         activity.suspend();
282     }
283        
284     /**
285      * Resume an activity
286      * @param workEffortId The WorkEffort entity key for the activity object
287      * @throws WfException
288      */
289     public void resume(String JavaDoc workEffortId) throws WfException {
290         WfActivity activity = WfFactory.getWfActivity(delegator, workEffortId);
291
292         if (Debug.verboseOn()) Debug.logVerbose("Resuming activity: " + activity.name(), module);
293         if (activityRunning(activity))
294             throw new WfException("Activity is already running");
295
296         activity.resume();
297     }
298     
299     /**
300      * Abort a process
301      * @param workEffortId The workeffort entity key for the process to abort
302      * @throws WfException
303      */
304     public void abortProcess(String JavaDoc workEffortId) throws WfException {
305         WfProcess process = WfFactory.getWfProcess(delegator, workEffortId);
306         process.abort();
307     }
308                 
309     /**
310      * Append data to the execution object's process context.
311      * @param workEffortId The WorkEffort entity key for the execution object.
312      * @param append The data to append.
313      * @throws WfException
314      */
315     public void appendContext(String JavaDoc workEffortId, Map JavaDoc append) throws WfException {
316         WfExecutionObject obj = getExecutionObject(workEffortId);
317
318         if (obj != null) {
319             Map JavaDoc oCtx = obj.processContext();
320
321             oCtx.putAll(append);
322             obj.setProcessContext(oCtx);
323             if (Debug.verboseOn()) Debug.logVerbose("ProcessContext (" + workEffortId + ") => " + obj.processContext(), module);
324         }
325     }
326
327     /**
328      * Returns the process context of the execution object.
329      * @param workEffortId The WorkEffort entity key for the execution object.
330      * @throws WfException
331      */
332     public Map JavaDoc getContext(String JavaDoc workEffortId) throws WfException {
333         WfExecutionObject obj = getExecutionObject(workEffortId);
334
335         if (obj == null) throw new WfException("Invalid Execution Object (null value)");
336         if (Debug.verboseOn()) Debug.logVerbose("ProcessContext (" + workEffortId + ") => " + obj.processContext(), module);
337         return obj.processContext();
338     }
339
340     /**
341      * Gets the state of the execution object defined by the work effort key.
342      * @param workEffortId The WorkEffort entity key for the execution object.
343      * @throws WfException
344      */
345     public String JavaDoc getState(String JavaDoc workEffortId) throws WfException {
346         WfExecutionObject obj = getExecutionObject(workEffortId);
347
348         if (obj == null) throw new WfException("Invalid Execution Object (null value)");
349         if (Debug.verboseOn()) Debug.logVerbose("Current State (" + workEffortId + ") => " + obj.state(), module);
350         return obj.state();
351     }
352
353     /**
354      * Set the state of the execution object defined by the work effort key.
355      * @param workEffortId The WorkEffort entity key for the execution object.
356      * @param state The new state of the execution object.
357      * @return Current state of the execution object as a string.
358      * @throws WfException If state change is not allowed.
359      */
360     public void setState(String JavaDoc workEffortId, String JavaDoc state) throws WfException {
361         WfExecutionObject obj = getExecutionObject(workEffortId);
362
363         if (obj == null) throw new WfException("Invalid Execution Object (null value)");
364         obj.changeState(state);
365         if (Debug.verboseOn()) Debug.logVerbose("Current State (" + workEffortId + ") => " + obj.state(), module);
366     }
367
368     /**
369      * Gets the priority of the execution object defined by the work effort key.
370      * @param workEffortId The WorkEffort entity key for the execution object.
371      * @return Priority of the execution object as a long.
372      * @throws WfException
373      */
374     public long getPriority(String JavaDoc workEffortId) throws WfException {
375         WfExecutionObject obj = getExecutionObject(workEffortId);
376
377         if (obj == null) throw new WfException("Invalid Execution Object (null value)");
378         if (Debug.verboseOn()) Debug.logVerbose("Current Priority (" + workEffortId + ") => " + obj.priority(), module);
379         return obj.priority();
380     }
381
382     /**
383      * Set the priority of the execution object defined by the work effort key.
384      * @param workEffortId The WorkEffort entity key for the execution object.
385      * @param priority The new priority of the execution object.
386      * @throws WfException If state change is not allowed.
387      */
388     public void setPriority(String JavaDoc workEffortId, long priority) throws WfException {
389         WfExecutionObject obj = getExecutionObject(workEffortId);
390
391         if (obj == null) throw new WfException("Invalid Execution Object (null value)");
392         obj.setPriority(priority);
393         if (Debug.verboseOn()) Debug.logVerbose("Current Priority (" + workEffortId + ") => " + obj.priority(), module);
394     }
395
396     // Get the execution object for the workeffort
397 private WfExecutionObject getExecutionObject(String JavaDoc workEffortId) {
398         WfExecutionObject obj = null;
399
400         try {
401             obj = (WfExecutionObject) WfFactory.getWfActivity(delegator, workEffortId);
402         } catch (WfException e) {// ingore
403 }
404         if (obj == null) {
405             try {
406                 obj = (WfExecutionObject) WfFactory.getWfProcess(delegator, workEffortId);
407             } catch (WfException e) {// ignore
408 }
409         }
410         return obj;
411     }
412
413     // Test an activity for running state.
414 private boolean activityRunning(String JavaDoc workEffortId) throws WfException {
415         return activityRunning(WfFactory.getWfActivity(delegator, workEffortId));
416     }
417
418     // Test an activity for running state.
419 private boolean activityRunning(WfActivity activity) throws WfException {
420         if (activity.state().equals("open.running"))
421             return true;
422         return false;
423     }
424
425 }
426
Popular Tags