KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > enhydra > shark > api > client > wfmodel > 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 JavaDoc;
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 JavaDoc[] 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 JavaDoc[] valid_states (SharkTransaction t) throws BaseException;
74
75    /** Gets the current state of the object. */
76    String JavaDoc state () throws BaseException;
77    /** Gets the current state of the object. */
78    String JavaDoc 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 JavaDoc 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 JavaDoc new_state) throws BaseException, InvalidState, TransitionNotAllowed;
96
97    /** Returns human readable, descriptive identifier of the execution object. */
98    String JavaDoc name () throws BaseException;
99    /** Returns human readable, descriptive identifier of the execution object. */
100    String JavaDoc name (SharkTransaction t) throws BaseException;
101
102    /** Sets the human readable, descriptive identifier of the execution object. */
103    void set_name (String JavaDoc new_value) throws BaseException;
104    /** Sets the human readable, descriptive identifier of the execution object. */
105    void set_name (SharkTransaction t,String JavaDoc 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 JavaDoc 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 JavaDoc key (SharkTransaction t) throws BaseException;
127
128    /** Returns description of the execution object. */
129    String JavaDoc description () throws BaseException;
130    /** Returns description of the execution object. */
131    String JavaDoc description (SharkTransaction t) throws BaseException;
132
133    /** Sets description of the execution object. */
134    void set_description (String JavaDoc new_value) throws BaseException;
135    /** Sets description of the execution object. */
136    void set_description (SharkTransaction t,String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc query, Map JavaDoc 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 JavaDoc query, Map JavaDoc 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
Popular Tags