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.


SourceForge.net Logo OBE-1.0 Copyright (C) 2002-2006 Adrian Price. All Rights Reserved.