WfExecutionObject


1   package org.enhydra.shark.api.client.wfmodel;
2   
3   
4   import org.enhydra.shark.api.client.wfbase.*;
5   
6   import org.enhydra.shark.api.client.timebase.*;
7   
8   import org.enhydra.shark.api.SharkTransaction;
9   
10  import java.util.Map  ;
11  
12  /**
13   OMG definition: WfExecutionObject is an abstract base interface that defines common attributes,
14   states, and operations for WfProcess and WfActivity.
15   It provides the capability to get and set and internal states. Operations are provided to
16   get the current state and to make a transition from the current state into another state.
17   Operations are also provided for specific state transitions. These operations are
18   suspend, resume, terminate, and abort. States returned by these operations should not
19   be confused with the state of the process which is calculated by the top level
20   WfProcess. States returned by these operations pertain only to the object they are
21   returned from. For example, regardless of what activity is currently enabled, a process
22   as a whole can be paused and resumed. The propagation of state change of a
23   WfProcess object down to WfActivity objects or subprocesses is implementation and
24   process definition dependent.
25   <p>The interface includes name, description, priority, and key attributes. It also provides
26   an operation for monitoring WfExecutionObject executions by returning, based on filter
27   specified, event audit records that represent the history of the execution. Other
28   operations include methods for getting and setting context.
29   <p>We extended OMG's interface by duplicating methods, and adding additional
30   parameter that represents transaction. If you use methods without SharkTransaction
31   parameter, the transaction will be implicitly created, and if you use it with
32   SharkTransaction parameter you must obey to some rules explained in HowTo documentation.
33   */
34  public interface WfExecutionObject extends BaseBusinessObject {//, PersistenceInterface
35     /** Returns the basic state of execution object: open or closed. */
36     workflow_stateType workflow_state () throws BaseException;
37     /** Returns the basic state of execution object: open or closed. */
38     workflow_stateType workflow_state (SharkTransaction t) throws BaseException;
39  
40     /** Returns the sub-state of execution object that is in open state: running or not running. */
41     while_openType while_open () throws BaseException;
42     /** Returns the sub-state of execution object that is in open state: running or not running. */
43     while_openType while_open (SharkTransaction t) throws BaseException;
44  
45     /** Returns the sub-state of execution object that is in open.not_running state: not started or suspended. */
46     why_not_runningType why_not_running () throws BaseException;
47     /** Returns the sub-state of execution object that is in open.not_running state: not started or suspended. */
48     why_not_runningType why_not_running (SharkTransaction t) throws BaseException;
49  
50     /** Returns the sub-state of execution object that is in closed state: completed, aborted or terminated. */
51     how_closedType how_closed () throws BaseException;
52     /** Returns the sub-state of execution object that is in closed state: completed, aborted or terminated. */
53     how_closedType how_closed (SharkTransaction t) throws BaseException;
54  
55     /**
56      The following operations support access to a potentially extended set of states; a state
57      is represented by a dot-notation representing hierarchical states (e.g., open.running).
58      <p>Returns a list of all the valid states that can be reached from the current state. For
59      example, open.running and closed.terminated would be in the list of
60      valid states if the current state was open.not_running.not_started - open.not_running.suspended
61      probably would not be in that list.
62      */
63     String  [] valid_states () throws BaseException;
64  
65     /**
66      The following operations support access to a potentially extended set of states; a state
67      is represented by a dot-notation representing hierarchical states (e.g., open.running).
68      <p>Returns a list of all the valid states that can be reached from the current state. For
69      example, open.running and closed.terminated would be in the list of
70      valid states if the current state was open.not_running.not_started - open.not_running.suspended
71      probably would not be in that list.
72      */
73     String  [] valid_states (SharkTransaction t) throws BaseException;
74  
75     /** Gets the current state of the object. */
76     String   state () throws BaseException;
77     /** Gets the current state of the object. */
78     String   state (SharkTransaction t) throws BaseException;
79  
80     /**
81      Updates the current state of the execution object. As a result the state of execution
82      objects associated with this execution object might be updated, too.
83      * @throws   InvalidState raised when the new_state is not a valid state for the execution object
84      * @throws   TransitionNotAllowed raised when the transition from the current state to new_state is not allowed.
85      * @throws   BaseException
86      */
87     void change_state (String   new_state) throws BaseException, InvalidState, TransitionNotAllowed;
88     /**
89      Updates the current state of the execution object. As a result the state of execution
90      objects associated with this execution object might be updated, too.
91      * @throws   InvalidState raised when the new_state is not a valid state for the execution object
92      * @throws   TransitionNotAllowed raised when the transition from the current state to new_state is not allowed.
93      * @throws   BaseException
94      */
95     void change_state (SharkTransaction t,String   new_state) throws BaseException, InvalidState, TransitionNotAllowed;
96  
97     /** Returns human readable, descriptive identifier of the execution object. */
98     String   name () throws BaseException;
99     /** Returns human readable, descriptive identifier of the execution object. */
100    String   name (SharkTransaction t) throws BaseException;
101 
102    /** Sets the human readable, descriptive identifier of the execution object. */
103    void set_name (String   new_value) throws BaseException;
104    /** Sets the human readable, descriptive identifier of the execution object. */
105    void set_name (SharkTransaction t,String   new_value) throws BaseException;
106 
107    /**
108     Gets the identifier of the execution object. The key of a WfProcess is unique among the set of
109     all WfProcesses created by a particular WfProcessMgr; the key of a WfActivity is
110     unique within the set of all WfActivities contained in a particular WfProcess. A key is
111     assigned to the execution object by its WfProcessMgr when it is created.
112     <p>The key of a workflow object should not be confused with an object identifier. It is
113     used for reference to the process or activity independently of the lifetime of the
114     execution object.
115     */
116    String   key () throws BaseException;
117    /**
118     Gets the identifier of the execution object. The key of a WfProcess is unique among the set of
119     all WfProcesses created by a particular WfProcessMgr; the key of a WfActivity is
120     unique within the set of all WfActivities contained in a particular WfProcess. A key is
121     assigned to the execution object by its WfProcessMgr when it is created.
122     <p>The key of a workflow object should not be confused with an object identifier. It is
123     used for reference to the process or activity independently of the lifetime of the
124     execution object.
125     */
126    String   key (SharkTransaction t) throws BaseException;
127 
128    /** Returns description of the execution object. */
129    String   description () throws BaseException;
130    /** Returns description of the execution object. */
131    String   description (SharkTransaction t) throws BaseException;
132 
133    /** Sets description of the execution object. */
134    void set_description (String   new_value) throws BaseException;
135    /** Sets description of the execution object. */
136    void set_description (SharkTransaction t,String   new_value) throws BaseException;
137 
138    /**
139     The process context is described by a set of named properties; the following
140     operation support access to the context of an execution object. The Map structure
141     identifies a set of property names and values matching the signature of the execution
142     object. The signature of a WfProcess can be obtained using the get_context_signature
143     operation provided by the WfProcessMgr of the process.
144     */
145    Map   process_context () throws BaseException;
146 
147    /**
148     The process context is described by a set of named properties; the following
149     operation support access to the context of an execution object. The Map structure
150     identifies a set of property names and values matching the signature of the execution
151     object. The signature of a WfProcess can be obtained using the get_context_signature
152     operation provided by the WfProcessMgr of the process.
153     */
154    Map   process_context (SharkTransaction t) throws BaseException;
155 
156    /**
157     Sets the process relevant data that define the context of the execution object.
158     The process context is described by a set of named properties. The Map structure
159     identifies a set of property names and values matching the signature of the execution
160     object. The signature of a WfProcess can be obtained using the get_context_signature
161     operation provided by the WfProcessMgr of the process.
162     <p>When this method has been called, only those name-value pairs in the parameter
163     will be set. Several set_process_context() calls could be used to set the entire context.
164     *
165     * @param    new_value           a  Map
166     *
167     * @throws   BaseException
168     * @throws   InvalidData raised when an update request does not match this
169     signature.
170     * @throws   UpdateNotAllowed raised when the implementation of the WfM
171     Facility or the specific workflow process does not allow an update of the context.
172     */
173    void set_process_context (Map   new_value) throws BaseException, InvalidData, UpdateNotAllowed;
174 
175    /**
176     Sets the process relevant data that define the context of the execution object.
177     The process context is described by a set of named properties. The Map structure
178     identifies a set of property names and values matching the signature of the execution
179     object. The signature of a WfProcess can be obtained using the get_context_signature
180     operation provided by the WfProcessMgr of the process.
181     <p>When this method has been called, only those name-value pairs in the parameter
182     will be set. Several set_process_context() calls could be used to set the entire context.
183     *
184     * @param    new_value           a  Map
185     *
186     * @throws   BaseException
187     * @throws   InvalidData raised when an update request does not match this
188     signature.
189     * @throws   UpdateNotAllowed raised when the implementation of the WfM
190     Facility or the specific workflow process does not allow an update of the context.
191     */
192    void set_process_context (SharkTransaction t,Map   new_value) throws BaseException, InvalidData, UpdateNotAllowed;
193 
194    /**
195     Returns relative priority of the execution element in the set of all execution
196     objects of a given type.
197     <p>Valid values are numbers between one and five, with three being 'normal' and
198     one as the 'highest' priority.
199     */
200    short priority () throws BaseException;
201 
202    /**
203     Returns relative priority of the execution element in the set of all execution
204     objects of a given type.
205     <p>Valid values are numbers between one and five, with three being 'normal' and
206     one as the 'highest' priority.
207     */
208    short priority (SharkTransaction t) throws BaseException;
209 
210    /**
211     Sets the relative priority of the execution element in the set of all execution
212     objects of a given type.
213     <p>Valid values are numbers between one and five, with three being 'normal' and
214     one as the 'highest' priority.
215     <p>A request for update of the priority will raise an exception when the
216     specified priority is out of range, or when the priority cannot be updated.
217     */
218    void set_priority (short new_value) throws BaseException;
219 
220    /**
221     Sets the relative priority of the execution element in the set of all execution
222     objects of a given type.
223     <p>Valid values are numbers between one and five, with three being 'normal' and
224     one as the 'highest' priority.
225     <p>A request for update of the priority will raise an exception when the
226     specified priority is out of range, or when the priority cannot be updated.
227     */
228    void set_priority (SharkTransaction t,short new_value) throws BaseException;
229 
230    /**
231     Requests enactment of a suspended execution object to be resumed. The state is set to
232     open.running (or a substate) from open.not_running.suspended.
233     * @throws   CannotResume raised when the execution object cannot be resumed.
234     For example, resuming a WfActivity might not be allowed when the containing
235     WfProcess is suspended.
236     * @throws   NotSuspended raised when the object is not suspended.
237     * @throws   BaseException
238     */
239    void resume () throws BaseException, CannotResume, NotSuspended;
240 
241    /**
242     Requests enactment of a suspended execution object to be resumed. The state is set to
243     open.running (or a substate) from open.not_running.suspended.
244     * @throws   CannotResume raised when the execution object cannot be resumed.
245     For example, resuming a WfActivity might not be allowed when the containing
246     WfProcess is suspended.
247     * @throws   NotSuspended raised when the object is not suspended.
248     * @throws   BaseException
249     */
250    void resume (SharkTransaction t) throws BaseException, CannotResume, NotSuspended;
251 
252    /**
253     Requests enactment of an execution object to be suspended. The state is set to
254     open.not_running.suspended (or one of its substates).
255     *
256     * @throws   CannotSuspend exception is raised when the execution object cannot be
257     suspended. For example, an implementation of the WfM Facility might not support
258     suspension of a WfActivity.
259     * @throws   NotRunning raised when the object is not running.
260     * @throws   AlreadySuspended raised when the object is already suspended.
261     * @throws   BaseException
262     */
263    void suspend () throws BaseException, CannotSuspend, NotRunning, AlreadySuspended;
264 
265    /**
266     Requests enactment of an execution object to be suspended. The state is set to
267     open.not_running.suspended (or one of its substates).
268     *
269     * @throws   CannotSuspend exception is raised when the execution object cannot be
270     suspended. For example, an implementation of the WfM Facility might not support
271     suspension of a WfActivity.
272     * @throws   NotRunning raised when the object is not running.
273     * @throws   AlreadySuspended raised when the object is already suspended.
274     * @throws   BaseException
275     */
276    void suspend (SharkTransaction t) throws BaseException, CannotSuspend, NotRunning, AlreadySuspended;
277 
278    /**
279     Requests enactment of an execution object to be terminated before its normal
280     completion. A terminate request is different from an abort request in its effect of
281     execution object associated with the current execution object.
282     The state is set to closed.terminated (or one of its substates) from open.running (or
283     one of its substates).
284     * @throws   CannotStop raised when the execution object cannot be terminated;
285     for example, termination of a WfActivity might not be allowed when its implementation
286     is still active and cannot be terminated.
287     * @throws   NotRunning raised when the object is not running.
288     * @throws   BaseException
289     */
290    void terminate () throws BaseException, CannotStop, NotRunning;
291 
292    /**
293     Requests enactment of an execution object to be terminated before its normal
294     completion. A terminate request is different from an abort request in its effect of
295     execution object associated with the current execution object.
296     The state is set to closed.terminated (or one of its substates) from open.running (or
297     one of its substates).
298     * @throws   CannotStop raised when the execution object cannot be terminated;
299     for example, termination of a WfActivity might not be allowed when its implementation
300     is still active and cannot be terminated.
301     * @throws   NotRunning raised when the object is not running.
302     * @throws   BaseException
303     */
304    void terminate (SharkTransaction t) throws BaseException, CannotStop, NotRunning;
305 
306    /**
307     Requests enactment of a suspended execution object to be aborted before its normal
308     completion. The state is set to closed.aborted.
309     * @throws   CannotStop raised when the execution object cannot be aborted.
310     * @throws   NotRunning raised when the object is not running.
311     * @throws   BaseException
312     *
313     */
314    void abort () throws BaseException, CannotStop, NotRunning;
315 
316    /**
317     Requests enactment of a suspended execution object to be aborted before its normal
318     completion. The state is set to closed.aborted.
319     * @throws   CannotStop raised when the execution object cannot be aborted.
320     * @throws   NotRunning raised when the object is not running.
321     * @throws   BaseException
322     *
323     */
324    void abort (SharkTransaction t) throws BaseException, CannotStop, NotRunning;
325 
326    /**
327     Zero or more WfEventAudit items can be associated with an execution object. An event
328     audit item is generated (and associated with the source object) for each workflow
329     relevant status change (change of state, context or result and change of resource
330     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
331     operations that request a change of the objects status or implicitly by the workflow
332     process logic. We will indicate which operations trigger generation of WfEventAudit
333     items.
334     <p>The following operation provide the information about the number of
335     WfEventAudit items currently associated with a WfExecutionObject.
336     */
337    int how_many_history () throws BaseException, HistoryNotAvailable;
338 
339    /**
340     Zero or more WfEventAudit items can be associated with an execution object. An event
341     audit item is generated (and associated with the source object) for each workflow
342     relevant status change (change of state, context or result and change of resource
343     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
344     operations that request a change of the objects status or implicitly by the workflow
345     process logic. We will indicate which operations trigger generation of WfEventAudit
346     items.
347     <p>The following operation provide the information about the number of
348     WfEventAudit items currently associated with a WfExecutionObject.
349     */
350    int how_many_history (SharkTransaction t) throws BaseException, HistoryNotAvailable;
351 
352    /**
353     Zero or more WfEventAudit items can be associated with an execution object. An event
354     audit item is generated (and associated with the source object) for each workflow
355     relevant status change (change of state, context or result and change of resource
356     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
357     operations that request a change of the objects status or implicitly by the workflow
358     process logic. We will indicate which operations trigger generation of WfEventAudit
359     items.
360     <p>The following operation returns iterator for qurying associated event audits
361     based on some criteria.
362     */
363    WfEventAuditIterator get_iterator_history (String   query, Map   names_in_query) throws BaseException, HistoryNotAvailable;
364 
365    /**
366     Zero or more WfEventAudit items can be associated with an execution object. An event
367     audit item is generated (and associated with the source object) for each workflow
368     relevant status change (change of state, context or result and change of resource
369     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
370     operations that request a change of the objects status or implicitly by the workflow
371     process logic. We will indicate which operations trigger generation of WfEventAudit
372     items.
373     <p>The following operation returns iterator for qurying associated event audits
374     based on some criteria.
375     */
376    WfEventAuditIterator get_iterator_history (SharkTransaction t,String   query, Map   names_in_query) throws BaseException, HistoryNotAvailable;
377 
378    /**
379     Zero or more WfEventAudit items can be associated with an execution object. An event
380     audit item is generated (and associated with the source object) for each workflow
381     relevant status change (change of state, context or result and change of resource
382     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
383     operations that request a change of the objects status or implicitly by the workflow
384     process logic. We will indicate which operations trigger generation of WfEventAudit
385     items.
386     <p>The following operation returns max_number of WfEventAudit objects
387     associated with an WfExecutionObject. If max_number is less or eaqual to zero, or it is
388     greater than the number of existing event audits, all associated WfEventAudit
389     objects will be returned.
390     */
391    WfEventAudit[] get_sequence_history (int max_number) throws BaseException, HistoryNotAvailable;
392 
393    /**
394     Zero or more WfEventAudit items can be associated with an execution object. An event
395     audit item is generated (and associated with the source object) for each workflow
396     relevant status change (change of state, context or result and change of resource
397     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
398     operations that request a change of the objects status or implicitly by the workflow
399     process logic. We will indicate which operations trigger generation of WfEventAudit
400     items.
401     <p>The following operation returns max_number of WfEventAudit objects
402     associated with an WfExecutionObject. If max_number is less or eaqual to zero, or it is
403     greater than the number of existing event audits, all associated WfEventAudit
404     objects will be returned.
405     */
406    WfEventAudit[] get_sequence_history (SharkTransaction t,int max_number) throws BaseException, HistoryNotAvailable;
407 
408    /**
409     Zero or more WfEventAudit items can be associated with an execution object. An event
410     audit item is generated (and associated with the source object) for each workflow
411     relevant status change (change of state, context or result and change of resource
412     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
413     operations that request a change of the objects status or implicitly by the workflow
414     process logic. We will indicate which operations trigger generation of WfEventAudit
415     items.
416     <p>The following operation returns true if given event audit is associated with
417     WfExecutionObject.
418     */
419    boolean is_member_of_history (WfExecutionObject member) throws BaseException;
420 
421    /**
422     Zero or more WfEventAudit items can be associated with an execution object. An event
423     audit item is generated (and associated with the source object) for each workflow
424     relevant status change (change of state, context or result and change of resource
425     assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
426     operations that request a change of the objects status or implicitly by the workflow
427     process logic. We will indicate which operations trigger generation of WfEventAudit
428     items.
429     <p>The following operation returns true if given event audit is associated with
430     WfExecutionObject.
431     */
432    boolean is_member_of_history (SharkTransaction t,WfExecutionObject member) throws BaseException;
433 
434    /** Returns the time when WfExecutionObject changed its state to the current one. */
435    UtcT last_state_time () throws BaseException;
436    /** Returns the time when WfExecutionObject changed its state to the current one. */
437    UtcT last_state_time (SharkTransaction t) throws BaseException;
438 
439 }
440
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags