org.wfmc.wapi
Interface WAPI

All Known Subinterfaces:

WAPI2, WMClient

public interface WAPI

Enables client applications to connect to and interact with a workflow engine.

This interface is based on the WfMC's Interface 2 Client WAPI specification. Some of the methods have been modified from the original specification to fit within the normal design of Java applications. For instance, the WfMC specification functions always return an error object (even for success) and uses out parameters to return values. This interface returns the value and throws an exception when an error occurs. If no error occurs then an exception is not thrown. The C WAPI uses query handles and iterator functions to retrieve collections; this Java binding uses WMIterator.

Author:

Anthony Eden, Adrian Price

Method Summary

void	abortProcessInstance(java.lang.String procInstId) Aborts a process instance.
void	abortProcessInstances(java.lang.String procDefId, WMFilter filter) Aborts a group of process instances.
void	assignActivityInstanceAttribute(java.lang.String procInstId, java.lang.String actInstId, java.lang.String attrName, java.lang.Object attrValue) Sets the value of an activity instance attribute.
void	assignActivityInstancesAttribute(java.lang.String procDefId, java.lang.String actDefId, WMFilter filter, java.lang.String attrName, java.lang.Object attrValue) Assigns an attribute value for a group of process instances.
void	assignProcessInstanceAttribute(java.lang.String procInstId, java.lang.String attrName, java.lang.Object attrValue) Sets the specified process instance attribute value.
void	assignProcessInstancesAttribute(java.lang.String procDefId, WMFilter filter, java.lang.String attrName, java.lang.Object attrValue) Assigns an attribute value for a group of process instances.
void	assignWorkItemAttribute(java.lang.String procInstId, java.lang.String workItemId, java.lang.String attrName, java.lang.Object attrValue) Sets the value of a work item attribute.
void	changeActivityInstancesState(java.lang.String procDefId, java.lang.String actDefId, WMFilter filter, WMActivityInstanceState newState) Changes the state of selected activity instances.
void	changeActivityInstanceState(java.lang.String procInstId, java.lang.String actInstId, WMActivityInstanceState newState) Changes the state of an activity instance.
void	changeProcessDefinitionState(java.lang.String procDefId, WMProcessDefinitionState newState) Changes the process definition state.
void	changeProcessInstancesState(java.lang.String procDefId, WMFilter filter, WMProcessInstanceState newState) Changes the state of selected process instances.
void	changeProcessInstanceState(java.lang.String procInstId, WMProcessInstanceState newState) Changes the state of a process instance.
void	changeWorkItemState(java.lang.String procInstId, java.lang.String workItemId, WMWorkItemState newState) Changes the state of a work item.
void	completeWorkItem(java.lang.String procInstId, java.lang.String workItemId) Completes the specified work item.
void	connect(WMConnectInfo connectInfo) Connects to a workflow service.
java.lang.String	createProcessInstance(java.lang.String procDefId, java.lang.String procInstName) Creates a new process instance for the given process definition.
void	disconnect() Disconnects from the workflow service.
WMActivityInstance	getActivityInstance(java.lang.String procInstId, java.lang.String actInstId) Retrieves an activity instance.
WMAttribute	getActivityInstanceAttributeValue(java.lang.String procInstId, java.lang.String actInstId, java.lang.String attrName) Gets the value of an activity instance attribute.
WMProcessInstance	getProcessInstance(java.lang.String procInstId) Retrieves a process instance.
WMAttribute	getProcessInstanceAttributeValue(java.lang.String procInstId, java.lang.String attrName) Gets the specified process instance attribute value.
WMWorkItem	getWorkItem(java.lang.String procInstId, java.lang.String workItemId) Retrieves a work item.
WMAttribute	getWorkItemAttributeValue(java.lang.String procInstId, java.lang.String workItemId, java.lang.String attrName) Retrieves the value of a work item attribute.
void	invokeApplication(int toolAgentHandle, java.lang.String appName, java.lang.String procInstId, java.lang.String workItemId, java.lang.Object[] parameters, int appMode) Invokes a client-side tool.
WMAttributeIterator	listActivityInstanceAttributes(java.lang.String procInstId, java.lang.String actInstId, WMFilter filter, boolean countFlag) Opens a list of activity instance attributes.
WMActivityInstanceIterator	listActivityInstances(WMFilter filter, boolean countFlag) Opens a list of activity instances.
WMActivityInstanceStateIterator	listActivityInstanceStates(java.lang.String procInstId, java.lang.String actInstId, WMFilter filter, boolean countFlag) Opens a list of process instance states.
WMProcessDefinitionIterator	listProcessDefinitions(WMFilter filter, boolean countFlag) Opens a list of process definitions.
WMProcessDefinitionStateIterator	listProcessDefinitionStates(java.lang.String procDefId, WMFilter filter, boolean countFlag) Opens a list of process definition states.
WMAttributeIterator	listProcessInstanceAttributes(java.lang.String procInstId, WMFilter filter, boolean countFlag) Opens a list of process instance attributes.
WMProcessInstanceIterator	listProcessInstances(WMFilter filter, boolean countFlag) Opens a list of process instances.
WMProcessInstanceStateIterator	listProcessInstanceStates(java.lang.String procInstId, WMFilter filter, boolean countFlag) Opens a list of process instance states.
WMAttributeIterator	listWorkItemAttributes(java.lang.String procInstId, java.lang.String workItemId, WMFilter filter, boolean countFlag) Opens a list of work item attributes.
WMWorkItemIterator	listWorkItems(WMFilter filter, boolean countFlag) Opens a worklist.
WMWorkItemStateIterator	listWorkItemStates(java.lang.String procInstId, java.lang.String workItemId, WMFilter filter, boolean countFlag) Opens a list of work item states.
void	reassignWorkItem(java.lang.String sourceUser, java.lang.String targetUser, java.lang.String procInstId, java.lang.String workItemId) Reassigns a work item to another user.
WMAttribute[]	requestAppStatus(int toolAgentHandle, java.lang.String procInstId, java.lang.String workItemId, int[] status) Requests the status of an invoked tool.
java.lang.String	startProcess(java.lang.String procInstId) Starts a process instance.
void	terminateApp(int toolAgentHandle, java.lang.String procInstId, java.lang.String workItemId) Terminates a running tool.
void	terminateProcessInstance(java.lang.String procInstId) Terminates a process instance.
void	terminateProcessInstances(java.lang.String procDefId, WMFilter filter) Terminates a group of process instances.

Method Detail

connect

public void connect(WMConnectInfo connectInfo)
             throws WMWorkflowException

Connects to a workflow service.

Parameters:

connectInfo - The connection info. In OBE, pass null to skip the JAAS login and retain the current security identity (if any).

Throws:

WMWorkflowException - Workflow client exception.

disconnect

public void disconnect()
                throws WMWorkflowException

Disconnects from the workflow service.

Throws:

WMWorkflowException - Workflow client exception.

listProcessDefinitions

public WMProcessDefinitionIterator listProcessDefinitions(WMFilter filter,
                                                          boolean countFlag)
                                                   throws WMWorkflowException

Opens a list of process definitions. The items in the list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMProcessDefinition objects.

Throws:

WMWorkflowException - Workflow client exception.

listProcessDefinitionStates

public WMProcessDefinitionStateIterator listProcessDefinitionStates(java.lang.String procDefId,
                                                                    WMFilter filter,
                                                                    boolean countFlag)
                                                             throws WMWorkflowException

Opens a list of process definition states. The items in the state list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

procDefId - The unique process definition ID.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMProcessDefinitionState objects.

Throws:

WMWorkflowException - Workflow client exception.

changeProcessDefinitionState

public void changeProcessDefinitionState(java.lang.String procDefId,
                                         WMProcessDefinitionState newState)
                                  throws WMWorkflowException

Changes the process definition state.

Parameters:

procDefId - The process definition id.

newState - The new process definition state.

Throws:

WMWorkflowException - Workflow client exception.

createProcessInstance

public java.lang.String createProcessInstance(java.lang.String procDefId,
                                              java.lang.String procInstName)
                                       throws WMWorkflowException

Creates a new process instance for the given process definition.

Parameters:

procDefId - The process definition id.

procInstName - The name of the process instance.

Returns:

The process instance id.

Throws:

WMWorkflowException - Workflow client exception.

startProcess

public java.lang.String startProcess(java.lang.String procInstId)
                              throws WMWorkflowException

Starts a process instance. The process instance id is retrieved from a prior call to createProcessInstance()

Parameters:

procInstId - The process instance id retrieved in a prior call to createProcessInstance().

Returns:

The new process instance id (which may be the same as the old).

Throws:

WMWorkflowException - Workflow client exception.

terminateProcessInstance

public void terminateProcessInstance(java.lang.String procInstId)
                              throws WMWorkflowException

Terminates a process instance.

Parameters:

procInstId - The process instance id.

Throws:

WMWorkflowException - Workflow client exception.

listProcessInstanceStates

public WMProcessInstanceStateIterator listProcessInstanceStates(java.lang.String procInstId,
                                                                WMFilter filter,
                                                                boolean countFlag)
                                                         throws WMWorkflowException

Opens a list of process instance states. The items in the state list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

procInstId - The unique process instance ID.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMProcessInstanceState objects.

Throws:

WMWorkflowException - Workflow client exception.

changeProcessInstanceState

public void changeProcessInstanceState(java.lang.String procInstId,
                                       WMProcessInstanceState newState)
                                throws WMWorkflowException

Changes the state of a process instance.

Parameters:

procInstId - The process instance id.

newState - The new process instance state.

Throws:

WMWorkflowException - Workflow client exception.

listProcessInstanceAttributes

public WMAttributeIterator listProcessInstanceAttributes(java.lang.String procInstId,
                                                         WMFilter filter,
                                                         boolean countFlag)
                                                  throws WMWorkflowException

Opens a list of process instance attributes. The items in the attribute list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMAttribute objects.

Throws:

WMWorkflowException - Workflow client exception.

getProcessInstanceAttributeValue

public WMAttribute getProcessInstanceAttributeValue(java.lang.String procInstId,
                                                    java.lang.String attrName)
                                             throws WMWorkflowException

Gets the specified process instance attribute value.

Parameters:

procInstId - The process instance id.

attrName - The attribute name.

Returns:

The attribute.

Throws:

WMWorkflowException - Workflow client exception.

assignProcessInstanceAttribute

public void assignProcessInstanceAttribute(java.lang.String procInstId,
                                           java.lang.String attrName,
                                           java.lang.Object attrValue)
                                    throws WMWorkflowException

Sets the specified process instance attribute value.

Parameters:

procInstId - The process instance id.

attrName - The attribute name.

attrValue - The attribute value.

Throws:

WMWorkflowException - Workflow client exception.

listActivityInstanceStates

public WMActivityInstanceStateIterator listActivityInstanceStates(java.lang.String procInstId,
                                                                  java.lang.String actInstId,
                                                                  WMFilter filter,
                                                                  boolean countFlag)
                                                           throws WMWorkflowException

Opens a list of process instance states. The items in the state list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMActivityInstanceState objects.

Throws:

WMWorkflowException - Workflow client exception.

changeActivityInstanceState

public void changeActivityInstanceState(java.lang.String procInstId,
                                        java.lang.String actInstId,
                                        WMActivityInstanceState newState)
                                 throws WMWorkflowException

Changes the state of an activity instance.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

newState - The new activity instance state.

Throws:

WMWorkflowException - Workflow client exception.

listActivityInstanceAttributes

public WMAttributeIterator listActivityInstanceAttributes(java.lang.String procInstId,
                                                          java.lang.String actInstId,
                                                          WMFilter filter,
                                                          boolean countFlag)
                                                   throws WMWorkflowException

Opens a list of activity instance attributes. The items in the attribute list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMAttribute objects.

Throws:

WMWorkflowException - Workflow client exception.

getActivityInstanceAttributeValue

public WMAttribute getActivityInstanceAttributeValue(java.lang.String procInstId,
                                                     java.lang.String actInstId,
                                                     java.lang.String attrName)
                                              throws WMWorkflowException

Gets the value of an activity instance attribute.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

attrName - The attribute name.

Returns:

The attribute.

Throws:

WMWorkflowException - Workflow client exception.

assignActivityInstanceAttribute

public void assignActivityInstanceAttribute(java.lang.String procInstId,
                                            java.lang.String actInstId,
                                            java.lang.String attrName,
                                            java.lang.Object attrValue)
                                     throws WMWorkflowException

Sets the value of an activity instance attribute.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

attrName - The attribute name.

attrValue - The attribute value.

Throws:

WMWorkflowException - Workflow client exception.

listProcessInstances

public WMProcessInstanceIterator listProcessInstances(WMFilter filter,
                                                      boolean countFlag)
                                               throws WMWorkflowException

Opens a list of process instances. The items in the list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMProcessInstance objects.

Throws:

WMWorkflowException - Workflow client exception.

getProcessInstance

public WMProcessInstance getProcessInstance(java.lang.String procInstId)
                                     throws WMWorkflowException

Retrieves a process instance.

Parameters:

procInstId - The process instance id.

Returns:

The process instance.

Throws:

WMWorkflowException - Workflow client exception.

listActivityInstances

public WMActivityInstanceIterator listActivityInstances(WMFilter filter,
                                                        boolean countFlag)
                                                 throws WMWorkflowException

Opens a list of activity instances. The items in the list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMActivityInstance objects.

Throws:

WMWorkflowException - Workflow client exception.

getActivityInstance

public WMActivityInstance getActivityInstance(java.lang.String procInstId,
                                              java.lang.String actInstId)
                                       throws WMWorkflowException

Retrieves an activity instance.

Parameters:

procInstId - The process instance id.

actInstId - The activity instance id.

Returns:

The activity instance.

Throws:

WMWorkflowException - Workflow client exception.

listWorkItems

public WMWorkItemIterator listWorkItems(WMFilter filter,
                                        boolean countFlag)
                                 throws WMWorkflowException

Opens a worklist. The items in the list can be retrieved sequentially using the iterator's tsNext() method.

Parameters:

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMWorkItem objects.

Throws:

WMWorkflowException - Workflow client exception.

getWorkItem

public WMWorkItem getWorkItem(java.lang.String procInstId,
                              java.lang.String workItemId)
                       throws WMWorkflowException

Retrieves a work item.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

Returns:

The work item.

Throws:

WMWorkflowException - Workflow client exception.

completeWorkItem

public void completeWorkItem(java.lang.String procInstId,
                             java.lang.String workItemId)
                      throws WMWorkflowException

Completes the specified work item.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

Throws:

WMWorkflowException - Workflow client exception.

listWorkItemStates

public WMWorkItemStateIterator listWorkItemStates(java.lang.String procInstId,
                                                  java.lang.String workItemId,
                                                  WMFilter filter,
                                                  boolean countFlag)
                                           throws WMWorkflowException

Opens a list of work item states. The items in the work item states list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

N.B. This function is poorly documented in the WfMC specification, which contains several 'copy/paste' errors.

N.B. The signature of this method differs from that described in the WAPI2 specification, in that it has a procInstId parameter. This is because the specification's definition for this function is clearly in error, having been copied badly from that for WMOpenProcessDefinitionStatesList. The other WAPI functions that refer to work items invariably require the procInstId parameter.

Parameters:

procInstId - The process instance id.

workItemId - The process instance id.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMWorkItemState objects.

Throws:

WMWorkflowException - Workflow client exception.

changeWorkItemState

public void changeWorkItemState(java.lang.String procInstId,
                                java.lang.String workItemId,
                                WMWorkItemState newState)
                         throws WMWorkflowException

Changes the state of a work item. N.B. The signature of this method differs from that described in the WAPI2 specification, in that it has a procInstId parameter. This is because the specification's definition for this function is clearly in error, having been badly copied from that for WMChangeDefinitionState. The other WAPI functions that refer to work items invariably require the procInstId parameter.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

newState - The new work item state.

Throws:

WMWorkflowException - Workflow client exception.

reassignWorkItem

public void reassignWorkItem(java.lang.String sourceUser,
                             java.lang.String targetUser,
                             java.lang.String procInstId,
                             java.lang.String workItemId)
                      throws WMWorkflowException

Reassigns a work item to another user.

Parameters:

sourceUser - The current user.

targetUser - The new user.

procInstId - The process instance id.

workItemId - The work item id.

Throws:

WMWorkflowException - Workflow client exception.

listWorkItemAttributes

public WMAttributeIterator listWorkItemAttributes(java.lang.String procInstId,
                                                  java.lang.String workItemId,
                                                  WMFilter filter,
                                                  boolean countFlag)
                                           throws WMWorkflowException

Opens a list of work item attributes. The items in the attribute list can be retrieved sequentially in a typesafe way by calling the iterator's tsNext() method.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

filter - The filter or null.

countFlag - True to return count value.

Returns:

An iterator to access the WMAttribute objects.

Throws:

WMWorkflowException - Workflow client exception.

getWorkItemAttributeValue

public WMAttribute getWorkItemAttributeValue(java.lang.String procInstId,
                                             java.lang.String workItemId,
                                             java.lang.String attrName)
                                      throws WMWorkflowException

Retrieves the value of a work item attribute.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

attrName - The attribute name.

Returns:

The attribute.

Throws:

WMWorkflowException - Workflow client exception.

assignWorkItemAttribute

public void assignWorkItemAttribute(java.lang.String procInstId,
                                    java.lang.String workItemId,
                                    java.lang.String attrName,
                                    java.lang.Object attrValue)
                             throws WMWorkflowException

Sets the value of a work item attribute.

Parameters:

procInstId - The process instance id.

workItemId - The work item id.

attrName - The attribute name.

attrValue - The attribute value.

Throws:

WMWorkflowException - Workflow client exception.

changeProcessInstancesState

public void changeProcessInstancesState(java.lang.String procDefId,
                                        WMFilter filter,
                                        WMProcessInstanceState newState)
                                 throws WMWorkflowException

Changes the state of selected process instances.

Parameters:

procDefId - The ID of the process definition for which instances are to be changed.

filter - A filter specification; can be null.

newState - The new state to apply.

Throws:

WMWorkflowException - Workflow client exception.

changeActivityInstancesState

public void changeActivityInstancesState(java.lang.String procDefId,
                                         java.lang.String actDefId,
                                         WMFilter filter,
                                         WMActivityInstanceState newState)
                                  throws WMWorkflowException

Changes the state of selected activity instances.

Parameters:

procDefId - The ID of the process definition for which activity instances are to be changed.

actDefId - The ID of the activity definition for which instances are to be changed.

filter - A filter specification; can be null.

newState - The new state to apply.

Throws:

WMWorkflowException - Workflow client exception.

terminateProcessInstances

public void terminateProcessInstances(java.lang.String procDefId,
                                      WMFilter filter)
                               throws WMWorkflowException

Terminates a group of process instances.

Parameters:

procDefId - The ID of the process definition for which instances are to be terminated.

filter - A filter specification; can be null.

Throws:

WMWorkflowException - Workflow client exception.

assignProcessInstancesAttribute

public void assignProcessInstancesAttribute(java.lang.String procDefId,
                                            WMFilter filter,
                                            java.lang.String attrName,
                                            java.lang.Object attrValue)
                                     throws WMWorkflowException

Assigns an attribute value for a group of process instances.

Parameters:

procDefId - The ID of the process definition for which instance attributes are to be assigned.

filter - A filter specification; can be null.

attrName - The attribute name.

attrValue - The attribute value.

Throws:

WMWorkflowException - Workflow client exception.

assignActivityInstancesAttribute

public void assignActivityInstancesAttribute(java.lang.String procDefId,
                                             java.lang.String actDefId,
                                             WMFilter filter,
                                             java.lang.String attrName,
                                             java.lang.Object attrValue)
                                      throws WMWorkflowException

Assigns an attribute value for a group of process instances.

Parameters:

procDefId - The ID of the process definition for which activity instance attributes are to be assigned.

actDefId - The ID of the activity definition for which instance attributes are to be assigned.

filter - A filter specification; can be null.

attrName - The attribute name.

attrValue - The attribute value.

Throws:

WMWorkflowException - Workflow client exception.

abortProcessInstances

public void abortProcessInstances(java.lang.String procDefId,
                                  WMFilter filter)
                           throws WMWorkflowException

Aborts a group of process instances.

Parameters:

procDefId - The ID of the process definition for which instances are to be aborted.

filter - A filter specification; can be null.

Throws:

WMWorkflowException - Workflow client exception.

abortProcessInstance

public void abortProcessInstance(java.lang.String procInstId)
                          throws WMWorkflowException

Aborts a process instance.

Parameters:

procInstId - The ID of the process instance to abort.

Throws:

WMWorkflowException - Workflow client exception.

invokeApplication

public void invokeApplication(int toolAgentHandle,
                              java.lang.String appName,
                              java.lang.String procInstId,
                              java.lang.String workItemId,
                              java.lang.Object[] parameters,
                              int appMode)
                       throws WMWorkflowException

Invokes a client-side tool.

Parameters:

toolAgentHandle -

appName - The tag name of the tool.

procInstId - The ID of the associated process instance.

workItemId - The ID of the associated work item.

parameters - Parameters to pass to the tool.

appMode - Application mode, one of:

Throws:

WMWorkflowException - Workflow client exception.

requestAppStatus

public WMAttribute[] requestAppStatus(int toolAgentHandle,
                                      java.lang.String procInstId,
                                      java.lang.String workItemId,
                                      int[] status)
                               throws WMWorkflowException

Requests the status of an invoked tool.

Parameters:

toolAgentHandle - The tool handle, returned by the prior call to invokeApplication(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object[], int).

procInstId - The ID of the associated process instance.

workItemId - The ID of the associated work item.

status -

Returns:

The status of specified tool.

Throws:

WMWorkflowException - Workflow client exception.

terminateApp

public void terminateApp(int toolAgentHandle,
                         java.lang.String procInstId,
                         java.lang.String workItemId)
                  throws WMWorkflowException

Terminates a running tool.

Parameters:

toolAgentHandle -

procInstId - The ID of the associated process instance.

workItemId - The ID of the associated work item.

Throws:

WMWorkflowException - Workflow client exception.