org.yawlfoundation.yawl.engine.interfce.interfaceB

Class InterfaceB_EnvironmentBasedClient

java.lang.Object

org.yawlfoundation.yawl.engine.interfce.Interface_Client

org.yawlfoundation.yawl.engine.interfce.interfaceB.InterfaceB_EnvironmentBasedClient

public class InterfaceB_EnvironmentBasedClient
extends Interface_Client

An API for custom services to call Engine functionalities regarding workitem management, process progression and case state.

Author:

Lachlan Aldred, Michael Adams (refactored for v2.0)

Created/Last Date:

27/01/2004

Constructor Summary

Constructors

Constructor and Description
InterfaceB_EnvironmentBasedClient(java.lang.String backEndURIStr) Constructor.

Method Summary

Modifier and Type	Method and Description
java.lang.String	cancelCase(java.lang.String caseID, java.lang.String sessionHandle) Cancels the case with caseID.
java.lang.String	checkConnection(java.lang.String sessionHandle) Checks whether the connection with the engine is alive, authenticated properly.
java.lang.String	checkInWorkItem(java.lang.String workItemID, java.lang.String data, java.lang.String sessionHandle) Deprecated. since 2.1 - use checkInWorkItem(String, String, String, String) instead Checks the work item back into the engine once the task is complete. Succesfully doing so will cause the work item to be completed in the engine.
java.lang.String	checkInWorkItem(java.lang.String workItemID, java.lang.String data, java.lang.String logPredicate, java.lang.String sessionHandle) Checks the work item back into the engine once the task is complete.
java.lang.String	checkOutWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Allow a client to obtain ownership of a unit of work.
java.lang.String	checkPermissionToAddInstances(java.lang.String workItemID, java.lang.String sessionHandle) Determines whether or not a task will allow a dynamically created new instance to be created.
java.lang.String	connect(java.lang.String userID, java.lang.String password) Connects the user to the engine.
java.lang.String	createNewInstance(java.lang.String workItemID, java.lang.String paramValueForMICreation, java.lang.String sessionHandle) Creates a new instance of a multi instance task.
java.lang.String	disconnect(java.lang.String handle) Disconnects an external entity from the engine
java.lang.String	exportAllCaseStates(java.lang.String sessionHandle)
java.lang.String	exportCaseState(java.lang.String caseID, java.lang.String sessionHandle)
java.lang.String	getAllRunningCases(java.lang.String sessionHandle) Gets a complete list of all running case ids from the engine
java.lang.String	getBackEndURI()
java.lang.String	getCaseData(java.lang.String caseID, java.lang.String sessionHandle) Gets the data of the case
java.lang.String	getCaseInstanceSummary(java.lang.String sessionHandle) Gets a summary table of all currently live process instances
java.lang.String	getCases(java.lang.String specID, java.lang.String sessionHandle) Deprecated. superseded by getCases(YSpecificationID, String)
java.lang.String	getCases(YSpecificationID specID, java.lang.String sessionHandle) Gets the set of active cases in the engine.
java.lang.String	getCaseState(java.lang.String caseID, java.lang.String sessionHandle) Gets the state description of the case
java.util.List<WorkItemRecord>	getChildrenOfWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Finds out the children of a given work item.
java.util.List<WorkItemRecord>	getCompleteListOfLiveWorkItems(java.lang.String sessionHandle) Returns a list (of WorkItemRecord) of all the work items that are currently active in the engine.
java.lang.String	getCompleteListOfLiveWorkItemsAsXML(java.lang.String sessionHandle) Returns an XML string describing all the work items that are currently active in the engine.
java.util.List<WorkItemRecord>	getLiveWorkItemsForIdentifier(java.lang.String idType, java.lang.String id, java.lang.String sessionHandle) Retrieves a List of live workitems for the case or spec id passed
java.lang.String	getLiveWorkItemsForIdentifierAsXML(java.lang.String idType, java.lang.String id, java.lang.String sessionHandle) Retrieves an XML description of live workitems for the case or spec id passed
java.lang.String	getMITaskAttributes(java.lang.String specID, java.lang.String taskID, java.lang.String sessionHandle) Deprecated. superseded by getMITaskAttributes(YSpecificationID, String, String) - this version should be used for pre-2.0 schema-based specifications only
java.lang.String	getMITaskAttributes(YSpecificationID specID, java.lang.String taskID, java.lang.String sessionHandle) Gets an XML representation of the attributes of a multi-instance task.
java.lang.String	getParameterInstanceSummary(java.lang.String caseID, java.lang.String itemID, java.lang.String sessionHandle) Gets a summary table of all data parameters for the workitem of the case specified
java.lang.String	getResourcingSpecs(YSpecificationID specID, java.lang.String taskID, java.lang.String sessionHandle) Gets the set of resourcing specifications for the specified task of the specified spec
java.lang.String	getSpecification(java.lang.String specID, java.lang.String sessionHandle) Deprecated. superseded by getSpecification(YSpecificationID, String)
java.lang.String	getSpecification(YSpecificationID specID, java.lang.String sessionHandle) Gets an XML representation of a workflow specification.
java.lang.String	getSpecificationData(YSpecificationID specID, java.lang.String sessionHandle) Gets an XML representation of some summary information of a workflow specification.
java.lang.String	getSpecificationDataSchema(java.lang.String specID, java.lang.String sessionHandle) Deprecated. superseded by getSpecificationDataSchema(YSpecificationID, String)
java.lang.String	getSpecificationDataSchema(YSpecificationID specID, java.lang.String sessionHandle) Gets the user-defined data schema for a specification
java.lang.String	getSpecificationForCase(java.lang.String caseID, java.lang.String sessionHandle) Gets an XML representation of a workflow specification for a specified, currently executing case.
java.lang.String	getSpecificationIDForCase(java.lang.String caseID, java.lang.String sessionHandle) Gets an XML representation of a workflow specification id for a specified, currently executing case.
java.util.List<SpecificationData>	getSpecificationList(java.lang.String sessionHandle) Creates a list of SpecificationData objects for the specifications currently loaded into the engine.
java.lang.String	getStartingDataSnapshot(java.lang.String workItemID, java.lang.String sessionHandle) Gets a snapshot of data values that would be assigned to an enabled work item IF that work item was started at the moment the method is called.
java.lang.String	getTaskInformationStr(java.lang.String specID, java.lang.String taskID, java.lang.String sessionHandle) Deprecated. superseded by getTaskInformationStr(YSpecificationID, String, String) - this version should be used for pre-2.0 schema-based specifications only
java.lang.String	getTaskInformationStr(YSpecificationID specID, java.lang.String taskID, java.lang.String sessionHandle) Gets an XML representation of information the task declaration.
java.lang.String	getWorkItem(java.lang.String itemID, java.lang.String sessionHandle) Returns an XML string describing a current work item.
long	getWorkItemExpiryTime(java.lang.String itemID, java.lang.String sessionHandle) Returns the expiry time of a work item's timer.
java.lang.String	getWorkItemInstanceSummary(java.lang.String caseID, java.lang.String sessionHandle) Gets a summary table of all completed and live workitems for a case
java.util.List<WorkItemRecord>	getWorkItemsForCase(java.lang.String caseID, java.lang.String sessionHandle) Returns the current set of active workitems for a case
java.util.List<WorkItemRecord>	getWorkItemsForService(java.lang.String serviceURI, java.lang.String sessionHandle) Returns the current set of active workitems that are associated with a specified custom service
java.util.List<WorkItemRecord>	getWorkItemsForSpecification(java.lang.String specName, java.lang.String sessionHandle) Returns the current set of active workitems for a specification
java.util.List<WorkItemRecord>	getWorkItemsForTask(java.lang.String taskID, java.lang.String sessionHandle) Returns the current set of active workitems that are instances of a specified task
java.lang.String	importCases(java.lang.String xml, java.lang.String sessionHandle)
boolean	isAdministrator(java.lang.String sessionHandle) Checks if the session has administrative access
java.lang.String	launchCase(java.lang.String specID, java.lang.String caseParams, java.lang.String sessionHandle) Deprecated. superseded by launchCase(YSpecificationID, String, String)
java.lang.String	launchCase(java.lang.String specID, java.lang.String caseParams, java.lang.String sessionHandle, java.lang.String completionObserverURI) Deprecated. superseded by launchCase(YSpecificationID, String, String)
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, java.lang.String caseID, YLogDataItemList logData, java.lang.String completionObserverURI) Launches a case instance.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, java.lang.String caseID, YLogDataItemList logData, java.lang.String completionObserverURI, java.util.Date start) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, java.lang.String caseID, YLogDataItemList logData, java.lang.String completionObserverURI, javax.xml.datatype.Duration wait) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, java.lang.String caseID, YLogDataItemList logData, java.lang.String completionObserverURI, long mSec) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, YLogDataItemList logData, java.lang.String completionObserverURI) Launches a case instance.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, YLogDataItemList logData, java.lang.String completionObserverURI, java.util.Date start) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, YLogDataItemList logData, java.lang.String completionObserverURI, javax.xml.datatype.Duration wait) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.lang.String sessionHandle, YLogDataItemList logData, java.lang.String completionObserverURI, long mSec) Launches a case instance after a delay.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, YLogDataItemList logData, java.lang.String sessionHandle) Launches a case instance of the latest version of the specification loaded.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, YLogDataItemList logData, java.lang.String caseID, java.lang.String sessionHandle) Launches a case instance.
TaskInformation	parseTaskInformation(java.lang.String taskInfoStr) Parses the XML string and returns a TaskInfo object (easier to manage).
java.lang.String	pollPerfStats(java.lang.String sessionHandle)
java.lang.String	postToExternalURL(java.lang.String url, java.util.Map<java.lang.String,java.lang.String> params) A generic method for sending a HTTP POST message, with parameters, to a URL external to the standard YAWL environment
java.lang.String	rejectAnnouncedEnabledTask(java.lang.String workItemID, java.lang.String sessionHandle) Rejects the announcement of an enabled work item to a service, and passes the the work item back to the engine for processing by the default work list
java.lang.String	rollbackWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Rolls back a work item, from 'executing' to 'fired' status.
java.lang.String	skipWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Skips a work item.
java.lang.String	stripOuterElement(java.lang.String xml) Removes the outermost set of xml tags from a string, if any
java.lang.String	suspendWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Suspends a work item.
java.lang.String	unsuspendWorkItem(java.lang.String workItemID, java.lang.String sessionHandle) Unuspends a work item.

Methods inherited from class org.yawlfoundation.yawl.engine.interfce.Interface_Client

executeGet, executePost, getReply, initPostConnection, prepareParamMap, send, setReadTimeout, successful

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InterfaceB_EnvironmentBasedClient

public InterfaceB_EnvironmentBasedClient(java.lang.String backEndURIStr)

Constructor.

Parameters:

backEndURIStr - the back end uri of where to find the engine. A default deployment of this value is http://localhost:8080/yawl/ib

Method Detail

getBackEndURI

public java.lang.String getBackEndURI()

connect

public java.lang.String connect(java.lang.String userID,
                                java.lang.String password)
                         throws java.io.IOException

Connects the user to the engine.

Parameters:

userID - the user id.

password - the user password

Returns:

the session handle

Throws:

java.io.IOException - if engine cannot be found

disconnect

public java.lang.String disconnect(java.lang.String handle)
                            throws java.io.IOException

Disconnects an external entity from the engine

Parameters:

handle - the sessionHandle to disconnect

Throws:

java.io.IOException - if the engine can't be reached

getCompleteListOfLiveWorkItems

public java.util.List<WorkItemRecord> getCompleteListOfLiveWorkItems(java.lang.String sessionHandle)
                                                              throws java.io.IOException

Returns a list (of WorkItemRecord) of all the work items that are currently active in the engine.

Parameters:

sessionHandle - the session handle

Returns:

the list of WorkItemRecord objects

Throws:

java.io.IOException - if engine can't be found.

See Also:

WorkItemRecord

getCompleteListOfLiveWorkItemsAsXML

public java.lang.String getCompleteListOfLiveWorkItemsAsXML(java.lang.String sessionHandle)
                                                     throws java.io.IOException

Returns an XML string describing all the work items that are currently active in the engine.

Parameters:

sessionHandle - the session handle

Returns:

an XML representation of the set of live workitems

Throws:

java.io.IOException - if engine can't be found.

getWorkItem

public java.lang.String getWorkItem(java.lang.String itemID,
                                    java.lang.String sessionHandle)
                             throws java.io.IOException

Returns an XML string describing a current work item.

Parameters:

itemID - the workitem id

sessionHandle - the session handle

Returns:

an XML representation of the of workitem

Throws:

java.io.IOException - if engine can't be found.

getWorkItemExpiryTime

public long getWorkItemExpiryTime(java.lang.String itemID,
                                  java.lang.String sessionHandle)
                           throws java.io.IOException

Returns the expiry time of a work item's timer.

Parameters:

itemID - the workitem id

sessionHandle - the session handle

Returns:

a long value representing the moment the timer will expire, or 0 if the work item does not have a timer or does not exist

Throws:

java.io.IOException - if engine can't be found.

getWorkItemsForCase

public java.util.List<WorkItemRecord> getWorkItemsForCase(java.lang.String caseID,
                                                          java.lang.String sessionHandle)
                                                   throws java.io.IOException

Returns the current set of active workitems for a case

Parameters:

caseID - the case in question

sessionHandle - the session handle

Returns:

a list of live workitems (as WorkItemRecords)

Throws:

java.io.IOException - if engine can't be found.

getWorkItemsForSpecification

public java.util.List<WorkItemRecord> getWorkItemsForSpecification(java.lang.String specName,
                                                                   java.lang.String sessionHandle)
                                                            throws java.io.IOException

Returns the current set of active workitems for a specification

Parameters:

specName - the specification in question

sessionHandle - the session handle

Returns:

a list of live workitems (as WorkItemRecords)

Throws:

java.io.IOException - if engine can't be found.

getWorkItemsForTask

public java.util.List<WorkItemRecord> getWorkItemsForTask(java.lang.String taskID,
                                                          java.lang.String sessionHandle)
                                                   throws java.io.IOException

Returns the current set of active workitems that are instances of a specified task

Parameters:

taskID - the task in question

sessionHandle - the session handle

Returns:

a list of live workitems (as WorkItemRecords)

Throws:

java.io.IOException - if engine can't be found.

getLiveWorkItemsForIdentifier

public java.util.List<WorkItemRecord> getLiveWorkItemsForIdentifier(java.lang.String idType,
                                                                    java.lang.String id,
                                                                    java.lang.String sessionHandle)
                                                             throws java.io.IOException,
                                                                    JDOMException

Retrieves a List of live workitems for the case or spec id passed

Parameters:

idType - : "case" for a case's workitems, "spec" for a specification's, "task" for a specific taskID

id - the identifier for the case/spec/task

sessionHandle - the session handle

Returns:

the List of live workitems (as WorkItemRecords)

Throws:

java.io.IOException - if there's a problem connecting to the engine

JDOMException - if there's a problem with xml conversions

getWorkItemsForService

public java.util.List<WorkItemRecord> getWorkItemsForService(java.lang.String serviceURI,
                                                             java.lang.String sessionHandle)
                                                      throws java.io.IOException

Returns the current set of active workitems that are associated with a specified custom service

Parameters:

serviceURI - the uri of the service in question

sessionHandle - the session handle

Returns:

a list of live workitems (as WorkItemRecords)

Throws:

java.io.IOException - if engine can't be found.

getLiveWorkItemsForIdentifierAsXML

public java.lang.String getLiveWorkItemsForIdentifierAsXML(java.lang.String idType,
                                                           java.lang.String id,
                                                           java.lang.String sessionHandle)
                                                    throws java.io.IOException,
                                                           JDOMException

Retrieves an XML description of live workitems for the case or spec id passed

Parameters:

idType - : "case" for a case's workitems, "spec" for a specification's, "task" for a specific taskID

id - the identifier for the case/spec/task

sessionHandle - the session handle

Returns:

the XML representation of live workitems in the engine

Throws:

java.io.IOException - if there's a problem connecting to the engine

JDOMException - if there's a problem with xml conversions

getSpecificationList

public java.util.List<SpecificationData> getSpecificationList(java.lang.String sessionHandle)
                                                       throws java.io.IOException

Creates a list of SpecificationData objects for the specifications currently loaded into the engine. These are brief meta data summary information objects that describe a workflow specification.

Parameters:

sessionHandle - the session handle

Returns:

the list of spec data objects

Throws:

java.io.IOException - if engine can't be found.

getSpecification

public java.lang.String getSpecification(java.lang.String specID,
                                         java.lang.String sessionHandle)
                                  throws java.io.IOException

Deprecated. superseded by getSpecification(YSpecificationID, String)

Gets an XML representation of a workflow specification.

Parameters:

specID - the specid.

sessionHandle - the session handle

Returns:

the XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecification

public java.lang.String getSpecification(YSpecificationID specID,
                                         java.lang.String sessionHandle)
                                  throws java.io.IOException

Gets an XML representation of a workflow specification.

Parameters:

specID - the specid.

sessionHandle - the session handle

Returns:

the XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecificationData

public java.lang.String getSpecificationData(YSpecificationID specID,
                                             java.lang.String sessionHandle)
                                      throws java.io.IOException

Gets an XML representation of some summary information of a workflow specification.

Parameters:

specID - the specid.

sessionHandle - the session handle

Returns:

the XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecificationForCase

public java.lang.String getSpecificationForCase(java.lang.String caseID,
                                                java.lang.String sessionHandle)
                                         throws java.io.IOException

Gets an XML representation of a workflow specification for a specified, currently executing case.

Parameters:

caseID - the identifier of a currently executing case.

sessionHandle - the session handle

Returns:

the XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecificationIDForCase

public java.lang.String getSpecificationIDForCase(java.lang.String caseID,
                                                  java.lang.String sessionHandle)
                                           throws java.io.IOException

Gets an XML representation of a workflow specification id for a specified, currently executing case.

Parameters:

caseID - the identifier of a currently executing case.

sessionHandle - the session handle

Returns:

the XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecificationDataSchema

public java.lang.String getSpecificationDataSchema(java.lang.String specID,
                                                   java.lang.String sessionHandle)
                                            throws java.io.IOException

Deprecated. superseded by getSpecificationDataSchema(YSpecificationID, String)

Gets the user-defined data schema for a specification

Parameters:

specID - the specification id

sessionHandle - an active session handle

Returns:

an XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

getSpecificationDataSchema

public java.lang.String getSpecificationDataSchema(YSpecificationID specID,
                                                   java.lang.String sessionHandle)
                                            throws java.io.IOException

Gets the user-defined data schema for a specification

Parameters:

specID - the specification id

sessionHandle - an active session handle

Returns:

an XML representation, or an XML diagnostic error message.

Throws:

java.io.IOException - if the engine can't be found.

checkOutWorkItem

public java.lang.String checkOutWorkItem(java.lang.String workItemID,
                                         java.lang.String sessionHandle)
                                  throws java.io.IOException

Allow a client to obtain ownership of a unit of work. This means that the workitem must be enabled or fired first, and that upon successful checkout the workitem will be exectuing.

Parameters:

workItemID - the workitem id.

sessionHandle - the sessionhandle

Returns:

in case of success returns a WorkItemRecord object of the created workitem. In case of failure returns a diagnostic XML message.

Throws:

java.io.IOException - if the engine can't be found.

rejectAnnouncedEnabledTask

public java.lang.String rejectAnnouncedEnabledTask(java.lang.String workItemID,
                                                   java.lang.String sessionHandle)
                                            throws java.io.IOException

Rejects the announcement of an enabled work item to a service, and passes the the work item back to the engine for processing by the default work list

Parameters:

workItemID - the workitem id.

sessionHandle - the sessionhandle

Returns:

a success or error message

Throws:

java.io.IOException - if the engine can't be found.

getStartingDataSnapshot

public java.lang.String getStartingDataSnapshot(java.lang.String workItemID,
                                                java.lang.String sessionHandle)
                                         throws java.io.IOException

Gets a snapshot of data values that would be assigned to an enabled work item IF that work item was started at the moment the method is called. Note that the work item must have Enabled status only.

Parameters:

workItemID - the workitem id

sessionHandle - the sessionhandle

Returns:

an XML string of the data snapshot, or an error message.

Throws:

java.io.IOException - if the engine can't be found.

getTaskInformationStr

public java.lang.String getTaskInformationStr(java.lang.String specID,
                                              java.lang.String taskID,
                                              java.lang.String sessionHandle)
                                       throws java.io.IOException

Deprecated. superseded by getTaskInformationStr(YSpecificationID, String, String) - this version should be used for pre-2.0 schema-based specifications only

Gets an XML representation of information the task declaration. This can be parsed into a copy of a YTask

Parameters:

specID - the spec id.

taskID - the task id.

sessionHandle - the session handle

Returns:

an XML Representation of the task information

Throws:

java.io.IOException - if the engine can't be found.

getTaskInformationStr

public java.lang.String getTaskInformationStr(YSpecificationID specID,
                                              java.lang.String taskID,
                                              java.lang.String sessionHandle)
                                       throws java.io.IOException

Gets an XML representation of information the task declaration. This can be parsed into a copy of a YTask

Parameters:

specID - the spec id.

taskID - the task id.

sessionHandle - the session handle

Returns:

an XML Representation of the task information

Throws:

java.io.IOException - if the engine can't be found.

checkConnection

public java.lang.String checkConnection(java.lang.String sessionHandle)
                                 throws java.io.IOException

Checks whether the connection with the engine is alive, authenticated properly.

Parameters:

sessionHandle - the session handle

Returns:

a diagnostic message indicating connection state.

Throws:

java.io.IOException - if engine cannot be found.

checkInWorkItem

public java.lang.String checkInWorkItem(java.lang.String workItemID,
                                        java.lang.String data,
                                        java.lang.String logPredicate,
                                        java.lang.String sessionHandle)
                                 throws java.io.IOException

Checks the work item back into the engine once the task is complete. Succesfully doing so will cause the work item to be completed in the engine.

Parameters:

workItemID - the work item id.

data - formated data eg. value

logPredicate - configurable logging string to be logged with the checkin

sessionHandle - the session handle

Returns:

in case success returns the work item as xml. In case of failure returns the reason for failure.

Throws:

java.io.IOException - if engine cannot be found.

checkInWorkItem

public java.lang.String checkInWorkItem(java.lang.String workItemID,
                                        java.lang.String data,
                                        java.lang.String sessionHandle)
                                 throws java.io.IOException

Deprecated. since 2.1 - use checkInWorkItem(String, String, String, String) instead Checks the work item back into the engine once the task is complete. Succesfully doing so will cause the work item to be completed in the engine.

Parameters:

workItemID - the work item id.

data - formated data eg. value

sessionHandle - the session handle

Returns:

in case success returns the work item as xml. In case of failure returns the reason for failure.

Throws:

java.io.IOException - if engine cannot be found.

checkPermissionToAddInstances

public java.lang.String checkPermissionToAddInstances(java.lang.String workItemID,
                                                      java.lang.String sessionHandle)
                                               throws java.io.IOException

Determines whether or not a task will allow a dynamically created new instance to be created.

Parameters:

workItemID - the workItemID of a sibling work item.

sessionHandle - the session handle

Returns:

diagnostic message that should indicate permission if task is MultiInstance, and if task allows dynamic instance creation, and if current number of instances is less than the maxInstances for the task.

Throws:

java.io.IOException - if engine cannot be found if task does not allow dynamic instance creation, or if current number of instances is not less than the maxInstances for the task.

Precondition:

the 'parent' task is a MultiInstance Task with dynamic instance creation.

createNewInstance

public java.lang.String createNewInstance(java.lang.String workItemID,
                                          java.lang.String paramValueForMICreation,
                                          java.lang.String sessionHandle)
                                   throws java.io.IOException

Creates a new instance of a multi instance task.

Parameters:

workItemID - the work item id of a sibling workitem

paramValueForMICreation - the data needed for creating a new instance.

sessionHandle - the session handle

Returns:

diagnostic string indicating result of action

Throws:

java.io.IOException - if engine cannot be found.

Precondition:

the referenced task is multi-instance and allows dynamic creation

skipWorkItem

public java.lang.String skipWorkItem(java.lang.String workItemID,
                                     java.lang.String sessionHandle)
                              throws java.io.IOException

Skips a work item.

Parameters:

workItemID - the work item id.

sessionHandle - the sessoin handle

Returns:

diagnostic XML message

Throws:

java.io.IOException - if the engine can't be found.

suspendWorkItem

public java.lang.String suspendWorkItem(java.lang.String workItemID,
                                        java.lang.String sessionHandle)
                                 throws java.io.IOException

Suspends a work item.

Parameters:

workItemID - the work item id.

sessionHandle - the sessoin handle

Returns:

diagnostic XML message

Throws:

java.io.IOException - if the engine can't be found.

unsuspendWorkItem

public java.lang.String unsuspendWorkItem(java.lang.String workItemID,
                                          java.lang.String sessionHandle)
                                   throws java.io.IOException

Unuspends a work item.

Parameters:

workItemID - the work item id.

sessionHandle - the sessoin handle

Returns:

diagnostic XML message

Throws:

java.io.IOException - if the engine can't be found.

rollbackWorkItem

public java.lang.String rollbackWorkItem(java.lang.String workItemID,
                                         java.lang.String sessionHandle)
                                  throws java.io.IOException

Rolls back a work item, from 'executing' to 'fired' status.

Parameters:

workItemID - the work item id.

sessionHandle - the sessoin handle

Returns:

diagnostic XML message

Throws:

java.io.IOException - if the engine can't be found.

launchCase

public java.lang.String launchCase(java.lang.String specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle)
                            throws java.io.IOException

Deprecated. superseded by launchCase(YSpecificationID, String, String)

Launches a case instance of the latest version of the specification loaded.

Parameters:

specID - the specification id (see SpecificationData.getID())

caseParams - the case params in XML. i.e.

    <data>
        <firstParam>value</firstParam>
        <secondParam>value</secondParam>
    </data>
 

If there are no case params then null should be passed.

sessionHandle - the session handle

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   YLogDataItemList logData,
                                   java.lang.String sessionHandle)
                            throws java.io.IOException

Launches a case instance of the latest version of the specification loaded.

Parameters:

specID - the specification id

caseParams - the case params in XML. i.e.

    <data>
        <firstParam>value</firstParam>
        <secondParam>value</secondParam>
    </data>
 

If there are no case params then null should be passed.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   YLogDataItemList logData,
                                   java.lang.String caseID,
                                   java.lang.String sessionHandle)
                            throws java.io.IOException

Launches a case instance.

Parameters:

specID - the specification id (see SpecificationData.getID())

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

caseID - a pre-selected, unique case identifier

sessionHandle - the session handle

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(java.lang.String specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   java.lang.String completionObserverURI)
                            throws java.io.IOException

Deprecated. superseded by launchCase(YSpecificationID, String, String)

Launches a case instance.

Parameters:

specID - the specification id (see SpecificationData.getID())

caseParams - the case params in XML.

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI)
                            throws java.io.IOException

Launches a case instance.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   java.lang.String caseID,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI)
                            throws java.io.IOException

Launches a case instance.

Parameters:

specID - the specification id

caseParams - the case params in XML.

caseID - the pre-selected, unique case identifier

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   long mSec)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

mSec - the number of milliseconds to wait before launching the case

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   java.lang.String caseID,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   long mSec)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

caseID - the pre-selected, unique case identifier

completionObserverURI - the URI of the IB service that will listen for a case-completed event

mSec - the number of milliseconds to wait before launching the case

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   java.util.Date start)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

start - the date and time when the case is to be launched

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   java.lang.String caseID,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   java.util.Date start)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

caseID - the pre-selected, unique case identifier

completionObserverURI - the URI of the IB service that will listen for a case-completed event

start - the date and time when the case is to be launched

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   javax.xml.datatype.Duration wait)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

completionObserverURI - the URI of the IB service that will listen for a case-completed event

wait - a Duration object that specifies a period to to wait before launching the case

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.lang.String sessionHandle,
                                   java.lang.String caseID,
                                   YLogDataItemList logData,
                                   java.lang.String completionObserverURI,
                                   javax.xml.datatype.Duration wait)
                            throws java.io.IOException

Launches a case instance after a delay.

Parameters:

specID - the specification id

caseParams - the case params in XML.

logData - a list of log data items for logging when the case starts (can be null)

sessionHandle - the session handle

caseID - the pre-selected, unique case identifier

completionObserverURI - the URI of the IB service that will listen for a case-completed event

wait - a Duration object that specifies a period to to wait before launching the case

Returns:

the case identifier, or a diagnostic message in case of failure

Throws:

java.io.IOException - if engine can't be found

getCases

public java.lang.String getCases(java.lang.String specID,
                                 java.lang.String sessionHandle)
                          throws java.io.IOException

Deprecated. superseded by getCases(YSpecificationID, String)

Gets the set of active cases in the engine.

Parameters:

specID - the specification id.

sessionHandle - the session handle

Returns:

an XML list of case ids that are instances of the spec with specid.

Throws:

java.io.IOException - if engine cannot be found

getCases

public java.lang.String getCases(YSpecificationID specID,
                                 java.lang.String sessionHandle)
                          throws java.io.IOException

Gets the set of active cases in the engine.

Parameters:

specID - the specification id.

sessionHandle - the session handle

Returns:

an XML list of case ids that are instances of the spec with specid.

Throws:

java.io.IOException - if engine cannot be found

getAllRunningCases

public java.lang.String getAllRunningCases(java.lang.String sessionHandle)
                                    throws java.io.IOException

Gets a complete list of all running case ids from the engine

Parameters:

sessionHandle - the session handle

Returns:

an XML list of case ids that are currently executing

Throws:

java.io.IOException - if engine cannot be found

getCaseState

public java.lang.String getCaseState(java.lang.String caseID,
                                     java.lang.String sessionHandle)
                              throws java.io.IOException

Gets the state description of the case

Parameters:

caseID - the case id.

sessionHandle - the session handle

Returns:

An XML representation of the case state, or a diagnostic error message.

Throws:

java.io.IOException - if engine cannot be found

exportCaseState

public java.lang.String exportCaseState(java.lang.String caseID,
                                        java.lang.String sessionHandle)
                                 throws java.io.IOException

Throws:

java.io.IOException

exportAllCaseStates

public java.lang.String exportAllCaseStates(java.lang.String sessionHandle)
                                     throws java.io.IOException

Throws:

java.io.IOException

importCases

public java.lang.String importCases(java.lang.String xml,
                                    java.lang.String sessionHandle)
                             throws java.io.IOException

Throws:

java.io.IOException

getCaseData

public java.lang.String getCaseData(java.lang.String caseID,
                                    java.lang.String sessionHandle)
                             throws java.io.IOException

Gets the data of the case

Parameters:

caseID - the case id.

sessionHandle - the session handle

Returns:

An XML representation of the case data, or a diagnostic error message.

Throws:

java.io.IOException - if engine cannot be found

cancelCase

public java.lang.String cancelCase(java.lang.String caseID,
                                   java.lang.String sessionHandle)
                            throws java.io.IOException

Cancels the case with caseID.

Parameters:

caseID - the case id.

sessionHandle - the session handle

Returns:

a diagnostic string providing information about the result of cancellation.

Throws:

java.io.IOException - if the engine cannot be found.

getChildrenOfWorkItem

public java.util.List<WorkItemRecord> getChildrenOfWorkItem(java.lang.String workItemID,
                                                            java.lang.String sessionHandle)
                                                     throws java.io.IOException

Finds out the children of a given work item. Only work items that are parents have children.

Parameters:

workItemID - the work item id of the parent workitem.

sessionHandle - the session handle

Returns:

a Java.util.List of WorkItemRecord objects.

Throws:

java.io.IOException - if the engine cannot be found.

parseTaskInformation

public TaskInformation parseTaskInformation(java.lang.String taskInfoStr)

Parses the XML string and returns a TaskInfo object (easier to manage).

Parameters:

taskInfoStr - the task information String

Returns:

the TaskInformation object

See Also:

getTaskInformationStr(YSpecificationID, String, String)

isAdministrator

public boolean isAdministrator(java.lang.String sessionHandle)
                        throws java.io.IOException

Checks if the session has administrative access

Parameters:

sessionHandle - the session to check

Returns:

true if this session has administration privileges

Throws:

java.io.IOException - if the engine cannot be found.

getMITaskAttributes

public java.lang.String getMITaskAttributes(java.lang.String specID,
                                            java.lang.String taskID,
                                            java.lang.String sessionHandle)
                                     throws java.io.IOException

Deprecated. superseded by getMITaskAttributes(YSpecificationID, String, String) - this version should be used for pre-2.0 schema-based specifications only

Gets an XML representation of the attributes of a multi-instance task.

Parameters:

specID - the spec id.

taskID - the task id.

sessionHandle - the session handle

Returns:

an XML Representation of the task information

Throws:

java.io.IOException - if the engine cannot be found.

getMITaskAttributes

public java.lang.String getMITaskAttributes(YSpecificationID specID,
                                            java.lang.String taskID,
                                            java.lang.String sessionHandle)
                                     throws java.io.IOException

Gets an XML representation of the attributes of a multi-instance task.

Parameters:

specID - the spec id.

taskID - the task id.

sessionHandle - the session handle

Returns:

an XML Representation of the task information

Throws:

java.io.IOException - if the engine cannot be found.

getResourcingSpecs

public java.lang.String getResourcingSpecs(YSpecificationID specID,
                                           java.lang.String taskID,
                                           java.lang.String sessionHandle)
                                    throws java.io.IOException

Gets the set of resourcing specifications for the specified task of the specified spec

Parameters:

specID - the specification id

taskID - the id of the task to get the resourcing specs for

sessionHandle - the session handle

Returns:

an XML Representation of the resourcing information for the task

Throws:

java.io.IOException - if the engine cannot be found.

getCaseInstanceSummary

public java.lang.String getCaseInstanceSummary(java.lang.String sessionHandle)
                                        throws java.io.IOException

Gets a summary table of all currently live process instances

Parameters:

sessionHandle - the session handle

Returns:

an XML Representation of live processes

Throws:

java.io.IOException - if the engine cannot be found.

getWorkItemInstanceSummary

public java.lang.String getWorkItemInstanceSummary(java.lang.String caseID,
                                                   java.lang.String sessionHandle)
                                            throws java.io.IOException

Gets a summary table of all completed and live workitems for a case

Parameters:

caseID - the case id of the process to get the workitems for

sessionHandle - the session handle

Returns:

an XML Representation of workitems for a live case

Throws:

java.io.IOException - if the engine cannot be found.

getParameterInstanceSummary

public java.lang.String getParameterInstanceSummary(java.lang.String caseID,
                                                    java.lang.String itemID,
                                                    java.lang.String sessionHandle)
                                             throws java.io.IOException

Gets a summary table of all data parameters for the workitem of the case specified

Parameters:

caseID - the case id of the process to get the workitems for

itemID - the id of the workitem to get the data params for

sessionHandle - the session handle

Returns:

an XML Representation of parameters for a workitem

Throws:

java.io.IOException - if the engine cannot be found.

postToExternalURL

public java.lang.String postToExternalURL(java.lang.String url,
                                          java.util.Map<java.lang.String,java.lang.String> params)
                                   throws java.io.IOException

A generic method for sending a HTTP POST message, with parameters, to a URL external to the standard YAWL environment

Parameters:

url - the external URL to which the message is posted

params - a map of attribute-value pairs to post with the message

Returns:

a reply string from the external URL

Throws:

java.io.IOException - if the external URL is invalid or unresponsive.

pollPerfStats

public java.lang.String pollPerfStats(java.lang.String sessionHandle)
                               throws java.io.IOException

Throws:

java.io.IOException

stripOuterElement

public java.lang.String stripOuterElement(java.lang.String xml)

Removes the outermost set of xml tags from a string, if any

Overrides:

stripOuterElement in class Interface_Client

Parameters:

xml - the xml string to strip

Returns:

the stripped xml string