001: package org.enhydra.shark.api.client.wfmodel;
002:
003: import java.util.Map;
004:
005: import org.enhydra.shark.api.client.timebase.UtcT;
006: import org.enhydra.shark.api.client.wfbase.BaseBusinessObject;
007:
008: /**
009: * OMG definition: WfExecutionObject is an abstract base interface that defines common
010: * attributes, states, and operations for WfProcess and WfActivity. It provides the
011: * capability to get and set and internal states. Operations are provided to get the
012: * current state and to make a transition from the current state into another state.
013: * Operations are also provided for specific state transitions. These operations are
014: * suspend, resume, terminate, and abort. States returned by these operations should not
015: * be confused with the state of the process which is calculated by the top level
016: * WfProcess. States returned by these operations pertain only to the object they are
017: * returned from. For example, regardless of what activity is currently enabled, a process
018: * as a whole can be paused and resumed. The propagation of state change of a WfProcess
019: * object down to WfActivity objects or subprocesses is implementation and process
020: * definition dependent.
021: * <p>
022: * The interface includes name, description, priority, and key attributes. It also
023: * provides an operation for monitoring WfExecutionObject executions by returning, based
024: * on filter specified, event audit records that represent the history of the execution.
025: * Other operations include methods for getting and setting context.
026: * <p>
027: * We extended OMG's interface by duplicating methods, and adding additional parameter
028: * that represents transaction. If you use methods without SharkTransaction parameter, the
029: * transaction will be implicitly created, and if you use it with SharkTransaction
030: * parameter you must obey to some rules explained in HowTo documentation.
031: */
032: public interface WfExecutionObject extends BaseBusinessObject {// , PersistenceInterface
033: /** Returns the basic state of execution object: open or closed. */
034: workflow_stateType workflow_state() throws Exception;
035:
036: /**
037: * Returns the sub-state of execution object that is in open state: running or not
038: * running.
039: */
040: while_openType while_open() throws Exception;
041:
042: /**
043: * Returns the sub-state of execution object that is in open.not_running state: not
044: * started or suspended.
045: */
046: why_not_runningType why_not_running() throws Exception;
047:
048: /**
049: * Returns the sub-state of execution object that is in closed state: completed,
050: * aborted or terminated.
051: */
052: how_closedType how_closed() throws Exception;
053:
054: /**
055: * The following operations support access to a potentially extended set of states; a
056: * state is represented by a dot-notation representing hierarchical states (e.g.,
057: * open.running).
058: * <p>
059: * Returns a list of all the valid states that can be reached from the current state.
060: * For example, open.running and closed.terminated would be in the list of valid states
061: * if the current state was open.not_running.not_started - open.not_running.suspended
062: * probably would not be in that list.
063: */
064: String[] valid_states() throws Exception;
065:
066: /** Gets the current state of the object. */
067: String state() throws Exception;
068:
069: /**
070: * Updates the current state of the execution object. As a result the state of
071: * execution objects associated with this execution object might be updated, too.
072: *
073: * @throws InvalidState raised when the new_state is not a valid state for the
074: * execution object
075: * @throws TransitionNotAllowed raised when the transition from the current state to
076: * new_state is not allowed.
077: * @throws Exception
078: */
079: void change_state(String new_state) throws Exception, InvalidState,
080: TransitionNotAllowed;
081:
082: /** Returns human readable, descriptive identifier of the execution object. */
083: String name() throws Exception;
084:
085: /** Sets the human readable, descriptive identifier of the execution object. */
086: void set_name(String new_value) throws Exception;
087:
088: /**
089: * Gets the identifier of the execution object. The key of a WfProcess is unique among
090: * the set of all WfProcesses created by a particular WfProcessMgr; the key of a
091: * WfActivity is unique within the set of all WfActivities contained in a particular
092: * WfProcess. A key is assigned to the execution object by its WfProcessMgr when it is
093: * created.
094: * <p>
095: * The key of a workflow object should not be confused with an object identifier. It is
096: * used for reference to the process or activity independently of the lifetime of the
097: * execution object.
098: */
099: String key() throws Exception;
100:
101: /** Returns description of the execution object. */
102: String description() throws Exception;
103:
104: /** Sets description of the execution object. */
105: void set_description(String new_value) throws Exception;
106:
107: /**
108: * The process context is described by a set of named properties; the following
109: * operation support access to the context of an execution object. The Map structure
110: * identifies a set of property names and values matching the signature of the
111: * execution object. The signature of a WfProcess can be obtained using the
112: * get_context_signature operation provided by the WfProcessMgr of the process.
113: */
114: Map process_context() throws Exception;
115:
116: /**
117: * Sets the process relevant data that define the context of the execution object. The
118: * process context is described by a set of named properties. The Map structure
119: * identifies a set of property names and values matching the signature of the
120: * execution object. The signature of a WfProcess can be obtained using the
121: * get_context_signature operation provided by the WfProcessMgr of the process.
122: * <p>
123: * When this method has been called, only those name-value pairs in the parameter will
124: * be set. Several set_process_context() calls could be used to set the entire context.
125: *
126: * @param new_value a Map
127: * @throws Exception
128: * @throws InvalidData raised when an update request does not match this signature.
129: * @throws UpdateNotAllowed raised when the implementation of the WfM Facility or the
130: * specific workflow process does not allow an update of the context.
131: */
132: void set_process_context(Map new_value) throws Exception,
133: InvalidData, UpdateNotAllowed;
134:
135: /**
136: * Returns relative priority of the execution element in the set of all execution
137: * objects of a given type.
138: * <p>
139: * Valid values are numbers between one and five, with three being 'normal' and one as
140: * the 'highest' priority.
141: */
142: short priority() throws Exception;
143:
144: /**
145: * Sets the relative priority of the execution element in the set of all execution
146: * objects of a given type.
147: * <p>
148: * Valid values are numbers between one and five, with three being 'normal' and one as
149: * the 'highest' priority.
150: * <p>
151: * A request for update of the priority will raise an exception when the specified
152: * priority is out of range, or when the priority cannot be updated.
153: */
154: void set_priority(short new_value) throws Exception;
155:
156: /**
157: * Requests enactment of a suspended execution object to be resumed. The state is set
158: * to open.running (or a substate) from open.not_running.suspended.
159: *
160: * @throws CannotResume raised when the execution object cannot be resumed. For
161: * example, resuming a WfActivity might not be allowed when the containing
162: * WfProcess is suspended.
163: * @throws NotSuspended raised when the object is not suspended.
164: * @throws Exception
165: */
166: void resume() throws Exception, CannotResume, NotSuspended;
167:
168: /**
169: * Requests enactment of an execution object to be suspended. The state is set to
170: * open.not_running.suspended (or one of its substates).
171: *
172: * @throws CannotSuspend exception is raised when the execution object cannot be
173: * suspended. For example, an implementation of the WfM Facility might not
174: * support suspension of a WfActivity.
175: * @throws NotRunning raised when the object is not running.
176: * @throws AlreadySuspended raised when the object is already suspended.
177: * @throws Exception
178: */
179: void suspend() throws Exception, CannotSuspend, NotRunning,
180: AlreadySuspended;
181:
182: /**
183: * Requests enactment of an execution object to be terminated before its normal
184: * completion. A terminate request is different from an abort request in its effect of
185: * execution object associated with the current execution object. The state is set to
186: * closed.terminated (or one of its substates) from open.running (or one of its
187: * substates).
188: *
189: * @throws CannotStop raised when the execution object cannot be terminated; for
190: * example, termination of a WfActivity might not be allowed when its
191: * implementation is still active and cannot be terminated.
192: * @throws NotRunning raised when the object is not running.
193: * @throws Exception
194: */
195: void terminate() throws Exception, CannotStop, NotRunning;
196:
197: /**
198: * Requests enactment of a suspended execution object to be aborted before its normal
199: * completion. The state is set to closed.aborted.
200: *
201: * @throws CannotStop raised when the execution object cannot be aborted.
202: * @throws NotRunning raised when the object is not running.
203: * @throws Exception
204: */
205: void abort() throws Exception, CannotStop, NotRunning;
206:
207: /**
208: * Zero or more WfEventAudit items can be associated with an execution object. An event
209: * audit item is generated (and associated with the source object) for each workflow
210: * relevant status change (change of state, context or result and change of resource
211: * assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
212: * operations that request a change of the objects status or implicitly by the workflow
213: * process logic. We will indicate which operations trigger generation of WfEventAudit
214: * items.
215: * <p>
216: * The following operation provide the information about the number of WfEventAudit
217: * items currently associated with a WfExecutionObject.
218: */
219: int how_many_history() throws Exception, HistoryNotAvailable;
220:
221: /**
222: * Zero or more WfEventAudit items can be associated with an execution object. An event
223: * audit item is generated (and associated with the source object) for each workflow
224: * relevant status change (change of state, context or result and change of resource
225: * assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
226: * operations that request a change of the objects status or implicitly by the workflow
227: * process logic. We will indicate which operations trigger generation of WfEventAudit
228: * items.
229: * <p>
230: * The following operation returns iterator for qurying associated event audits based
231: * on some criteria.
232: */
233: WfEventAuditIterator get_iterator_history(String query,
234: Map names_in_query) throws Exception, HistoryNotAvailable;
235:
236: /**
237: * Zero or more WfEventAudit items can be associated with an execution object. An event
238: * audit item is generated (and associated with the source object) for each workflow
239: * relevant status change (change of state, context or result and change of resource
240: * assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
241: * operations that request a change of the objects status or implicitly by the workflow
242: * process logic. We will indicate which operations trigger generation of WfEventAudit
243: * items.
244: * <p>
245: * The following operation returns max_number of WfEventAudit objects associated with
246: * an WfExecutionObject. If max_number is less or eaqual to zero, or it is greater than
247: * the number of existing event audits, all associated WfEventAudit objects will be
248: * returned.
249: */
250: WfEventAudit[] get_sequence_history(int max_number)
251: throws Exception, HistoryNotAvailable;
252:
253: /**
254: * Zero or more WfEventAudit items can be associated with an execution object. An event
255: * audit item is generated (and associated with the source object) for each workflow
256: * relevant status change (change of state, context or result and change of resource
257: * assignment) of a WfExecutionObject. Status changes can be explicitly triggered by
258: * operations that request a change of the objects status or implicitly by the workflow
259: * process logic. We will indicate which operations trigger generation of WfEventAudit
260: * items.
261: * <p>
262: * The following operation returns true if given event audit is associated with
263: * WfExecutionObject.
264: */
265: boolean is_member_of_history(WfExecutionObject member)
266: throws Exception;
267:
268: /** Returns the time when WfExecutionObject changed its state to the current one. */
269: UtcT last_state_time() throws Exception;
270:
271: }
|