org.enhydra.shark.api.client.wfmodel
Interface WfExecutionObject

All Superinterfaces:
BaseBusinessObject, java.io.Serializable
All Known Subinterfaces:
WfActivity, WfProcess

public interface WfExecutionObject
extends BaseBusinessObject

OMG definition: WfExecutionObject is an abstract base interface that defines common attributes, states, and operations for WfProcess and WfActivity. It provides the capability to get and set and internal states. Operations are provided to get the current state and to make a transition from the current state into another state. Operations are also provided for specific state transitions. These operations are suspend, resume, terminate, and abort. States returned by these operations should not be confused with the state of the process which is calculated by the top level WfProcess. States returned by these operations pertain only to the object they are returned from. For example, regardless of what activity is currently enabled, a process as a whole can be paused and resumed. The propagation of state change of a WfProcess object down to WfActivity objects or subprocesses is implementation and process definition dependent.

The interface includes name, description, priority, and key attributes. It also provides an operation for monitoring WfExecutionObject executions by returning, based on filter specified, event audit records that represent the history of the execution. Other operations include methods for getting and setting context.

We extended OMG's interface by duplicating methods, and adding additional parameter that represents transaction. If you use methods without SharkTransaction parameter, the transaction will be implicitly created, and if you use it with SharkTransaction parameter you must obey to some rules explained in HowTo documentation.


Method Summary
 void abort()
          Requests enactment of a suspended execution object to be aborted before its normal completion.
 void change_state(java.lang.String new_state)
          Updates the current state of the execution object.
 java.lang.String description()
          Returns description of the execution object.
 WfEventAuditIterator get_iterator_history(java.lang.String query, java.util.Map names_in_query)
          Zero or more WfEventAudit items can be associated with an execution object.
 WfEventAudit[] get_sequence_history(int max_number)
          Zero or more WfEventAudit items can be associated with an execution object.
 how_closedType how_closed()
          Returns the sub-state of execution object that is in closed state: completed, aborted or terminated.
 int how_many_history()
          Zero or more WfEventAudit items can be associated with an execution object.
 boolean is_member_of_history(WfExecutionObject member)
          Zero or more WfEventAudit items can be associated with an execution object.
 java.lang.String key()
          Gets the identifier of the execution object.
 UtcT last_state_time()
          Returns the time when WfExecutionObject changed its state to the current one.
 java.lang.String name()
          Returns human readable, descriptive identifier of the execution object.
 short priority()
          Returns relative priority of the execution element in the set of all execution objects of a given type.
 java.util.Map process_context()
          The process context is described by a set of named properties; the following operation support access to the context of an execution object.
 void resume()
          Requests enactment of a suspended execution object to be resumed.
 void set_description(java.lang.String new_value)
          Sets description of the execution object.
 void set_name(java.lang.String new_value)
          Sets the human readable, descriptive identifier of the execution object.
 void set_priority(short new_value)
          Sets the relative priority of the execution element in the set of all execution objects of a given type.
 void set_process_context(java.util.Map new_value)
          Sets the process relevant data that define the context of the execution object.
 java.lang.String state()
          Gets the current state of the object.
 void suspend()
          Requests enactment of an execution object to be suspended.
 void terminate()
          Requests enactment of an execution object to be terminated before its normal completion.
 java.lang.String[] valid_states()
          The following operations support access to a potentially extended set of states; a state is represented by a dot-notation representing hierarchical states (e.g., open.running).
 while_openType while_open()
          Returns the sub-state of execution object that is in open state: running or not running.
 why_not_runningType why_not_running()
          Returns the sub-state of execution object that is in open.not_running state: not started or suspended.
 workflow_stateType workflow_state()
          Returns the basic state of execution object: open or closed.
 

Method Detail

workflow_state

workflow_stateType workflow_state()
                                  throws java.lang.Exception
Returns the basic state of execution object: open or closed.

Throws:
java.lang.Exception

while_open

while_openType while_open()
                          throws java.lang.Exception
Returns the sub-state of execution object that is in open state: running or not running.

Throws:
java.lang.Exception

why_not_running

why_not_runningType why_not_running()
                                    throws java.lang.Exception
Returns the sub-state of execution object that is in open.not_running state: not started or suspended.

Throws:
java.lang.Exception

how_closed

how_closedType how_closed()
                          throws java.lang.Exception
Returns the sub-state of execution object that is in closed state: completed, aborted or terminated.

Throws:
java.lang.Exception

valid_states

java.lang.String[] valid_states()
                                throws java.lang.Exception
The following operations support access to a potentially extended set of states; a state is represented by a dot-notation representing hierarchical states (e.g., open.running).

Returns a list of all the valid states that can be reached from the current state. For example, open.running and closed.terminated would be in the list of valid states if the current state was open.not_running.not_started - open.not_running.suspended probably would not be in that list.

Throws:
java.lang.Exception

state

java.lang.String state()
                       throws java.lang.Exception
Gets the current state of the object.

Throws:
java.lang.Exception

change_state

void change_state(java.lang.String new_state)
                  throws java.lang.Exception,
                         InvalidState,
                         TransitionNotAllowed
Updates the current state of the execution object. As a result the state of execution objects associated with this execution object might be updated, too.

Throws:
InvalidState - raised when the new_state is not a valid state for the execution object
TransitionNotAllowed - raised when the transition from the current state to new_state is not allowed.
java.lang.Exception

name

java.lang.String name()
                      throws java.lang.Exception
Returns human readable, descriptive identifier of the execution object.

Throws:
java.lang.Exception

set_name

void set_name(java.lang.String new_value)
              throws java.lang.Exception
Sets the human readable, descriptive identifier of the execution object.

Throws:
java.lang.Exception

key

java.lang.String key()
                     throws java.lang.Exception
Gets the identifier of the execution object. The key of a WfProcess is unique among the set of all WfProcesses created by a particular WfProcessMgr; the key of a WfActivity is unique within the set of all WfActivities contained in a particular WfProcess. A key is assigned to the execution object by its WfProcessMgr when it is created.

The key of a workflow object should not be confused with an object identifier. It is used for reference to the process or activity independently of the lifetime of the execution object.

Throws:
java.lang.Exception

description

java.lang.String description()
                             throws java.lang.Exception
Returns description of the execution object.

Throws:
java.lang.Exception

set_description

void set_description(java.lang.String new_value)
                     throws java.lang.Exception
Sets description of the execution object.

Throws:
java.lang.Exception

process_context

java.util.Map process_context()
                              throws java.lang.Exception
The process context is described by a set of named properties; the following operation support access to the context of an execution object. The Map structure identifies a set of property names and values matching the signature of the execution object. The signature of a WfProcess can be obtained using the get_context_signature operation provided by the WfProcessMgr of the process.

Throws:
java.lang.Exception

set_process_context

void set_process_context(java.util.Map new_value)
                         throws java.lang.Exception,
                                InvalidData,
                                UpdateNotAllowed
Sets the process relevant data that define the context of the execution object. The process context is described by a set of named properties. The Map structure identifies a set of property names and values matching the signature of the execution object. The signature of a WfProcess can be obtained using the get_context_signature operation provided by the WfProcessMgr of the process.

When this method has been called, only those name-value pairs in the parameter will be set. Several set_process_context() calls could be used to set the entire context.

Parameters:
new_value - a Map
Throws:
java.lang.Exception
InvalidData - raised when an update request does not match this signature.
UpdateNotAllowed - raised when the implementation of the WfM Facility or the specific workflow process does not allow an update of the context.

priority

short priority()
               throws java.lang.Exception
Returns relative priority of the execution element in the set of all execution objects of a given type.

Valid values are numbers between one and five, with three being 'normal' and one as the 'highest' priority.

Throws:
java.lang.Exception

set_priority

void set_priority(short new_value)
                  throws java.lang.Exception
Sets the relative priority of the execution element in the set of all execution objects of a given type.

Valid values are numbers between one and five, with three being 'normal' and one as the 'highest' priority.

A request for update of the priority will raise an exception when the specified priority is out of range, or when the priority cannot be updated.

Throws:
java.lang.Exception

resume

void resume()
            throws java.lang.Exception,
                   CannotResume,
                   NotSuspended
Requests enactment of a suspended execution object to be resumed. The state is set to open.running (or a substate) from open.not_running.suspended.

Throws:
CannotResume - raised when the execution object cannot be resumed. For example, resuming a WfActivity might not be allowed when the containing WfProcess is suspended.
NotSuspended - raised when the object is not suspended.
java.lang.Exception

suspend

void suspend()
             throws java.lang.Exception,
                    CannotSuspend,
                    NotRunning,
                    AlreadySuspended
Requests enactment of an execution object to be suspended. The state is set to open.not_running.suspended (or one of its substates).

Throws:
CannotSuspend - exception is raised when the execution object cannot be suspended. For example, an implementation of the WfM Facility might not support suspension of a WfActivity.
NotRunning - raised when the object is not running.
AlreadySuspended - raised when the object is already suspended.
java.lang.Exception

terminate

void terminate()
               throws java.lang.Exception,
                      CannotStop,
                      NotRunning
Requests enactment of an execution object to be terminated before its normal completion. A terminate request is different from an abort request in its effect of execution object associated with the current execution object. The state is set to closed.terminated (or one of its substates) from open.running (or one of its substates).

Throws:
CannotStop - raised when the execution object cannot be terminated; for example, termination of a WfActivity might not be allowed when its implementation is still active and cannot be terminated.
NotRunning - raised when the object is not running.
java.lang.Exception

abort

void abort()
           throws java.lang.Exception,
                  CannotStop,
                  NotRunning
Requests enactment of a suspended execution object to be aborted before its normal completion. The state is set to closed.aborted.

Throws:
CannotStop - raised when the execution object cannot be aborted.
NotRunning - raised when the object is not running.
java.lang.Exception

how_many_history

int how_many_history()
                     throws java.lang.Exception,
                            HistoryNotAvailable
Zero or more WfEventAudit items can be associated with an execution object. An event audit item is generated (and associated with the source object) for each workflow relevant status change (change of state, context or result and change of resource assignment) of a WfExecutionObject. Status changes can be explicitly triggered by operations that request a change of the objects status or implicitly by the workflow process logic. We will indicate which operations trigger generation of WfEventAudit items.

The following operation provide the information about the number of WfEventAudit items currently associated with a WfExecutionObject.

Throws:
java.lang.Exception
HistoryNotAvailable

get_iterator_history

WfEventAuditIterator get_iterator_history(java.lang.String query,
                                          java.util.Map names_in_query)
                                          throws java.lang.Exception,
                                                 HistoryNotAvailable
Zero or more WfEventAudit items can be associated with an execution object. An event audit item is generated (and associated with the source object) for each workflow relevant status change (change of state, context or result and change of resource assignment) of a WfExecutionObject. Status changes can be explicitly triggered by operations that request a change of the objects status or implicitly by the workflow process logic. We will indicate which operations trigger generation of WfEventAudit items.

The following operation returns iterator for qurying associated event audits based on some criteria.

Throws:
java.lang.Exception
HistoryNotAvailable

get_sequence_history

WfEventAudit[] get_sequence_history(int max_number)
                                    throws java.lang.Exception,
                                           HistoryNotAvailable
Zero or more WfEventAudit items can be associated with an execution object. An event audit item is generated (and associated with the source object) for each workflow relevant status change (change of state, context or result and change of resource assignment) of a WfExecutionObject. Status changes can be explicitly triggered by operations that request a change of the objects status or implicitly by the workflow process logic. We will indicate which operations trigger generation of WfEventAudit items.

The following operation returns max_number of WfEventAudit objects associated with an WfExecutionObject. If max_number is less or eaqual to zero, or it is greater than the number of existing event audits, all associated WfEventAudit objects will be returned.

Throws:
java.lang.Exception
HistoryNotAvailable

is_member_of_history

boolean is_member_of_history(WfExecutionObject member)
                             throws java.lang.Exception
Zero or more WfEventAudit items can be associated with an execution object. An event audit item is generated (and associated with the source object) for each workflow relevant status change (change of state, context or result and change of resource assignment) of a WfExecutionObject. Status changes can be explicitly triggered by operations that request a change of the objects status or implicitly by the workflow process logic. We will indicate which operations trigger generation of WfEventAudit items.

The following operation returns true if given event audit is associated with WfExecutionObject.

Throws:
java.lang.Exception

last_state_time

UtcT last_state_time()
                     throws java.lang.Exception
Returns the time when WfExecutionObject changed its state to the current one.

Throws:
java.lang.Exception