org.yawlfoundation.yawl.engine.interfce.interfaceB
Class InterfaceBWebsideController

java.lang.Object
  org.yawlfoundation.yawl.engine.interfce.interfaceB.InterfaceBWebsideController

Direct Known Subclasses:

DigitalSignature, MailSender, MailService, ProcletService, ResourceManager, Service, SMSSender, TestService, TimeService, TwitterService, WorkletService, WSIFController

public abstract class InterfaceBWebsideController
extends Object

An abstract class designed to be implemented by YAWL custom services. It provides access to, and receives event notifications from, the Engine via Interface B.

Author:

Lachlan Aldred Date: 19/03/2004 Time: 11:44:49, Michael Adams (refactored and enhanced for v2.0 2008-09)

Field Summary

protected IBControllerCache	_ibCache
protected InterfaceB_EnvironmentBasedClient	_interfaceBClient
protected org.apache.log4j.Category	_logger
protected String	_report
protected String	engineLogonName
protected String	engineLogonPassword
protected static String	XSD_ANYURI_TYPE
protected static String	XSD_NAMESPACE
protected static String	XSD_NCNAME_TYPE
protected static String	XSD_STRINGTYPE

Constructor Summary

InterfaceBWebsideController()
Constructs a controller.

Method Summary

boolean	checkConnection(String sessionHandle) Checks if the sessionhandle with the engine is currently active.
String	checkInWorkItem(String workItemID, org.jdom.Element inputData, org.jdom.Element outputData, String sessionHandle) Deprecated. since 2.1 - use checkInWorkItem(String, Element, Element, String, String) Checks a work item into the engine.
String	checkInWorkItem(String workItemID, org.jdom.Element inputData, org.jdom.Element outputData, String logPredicate, String sessionHandle) Checks a work item into the engine.
String	checkInWorkItem(String workItemID, String inputData, String outputData, String sessionHandle) Deprecated. since 2.1 - use checkInWorkItem(String, Element, Element, String, String) Checks a work item back into the engine.
WorkItemRecord	checkOut(String workItemID, String sessionHandle) Checks a work item out of the engine.
protected List<WorkItemRecord>	checkOutAllInstancesOfThisTask(WorkItemRecord enabledWorkItem, String sessionHandle) Utility method for implementers to use for helping to check all instances of a given task out of the engine.
String	connect(String userID, String password) Creates a session with the engine.
YParameter[]	describeRequiredParams() Override this method if you wish to allow other tools to find out what input parameters are required for your custom YAWL service to work.
void	destroy() Receives notification when the environment is being shutdown.
void	doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Override this method to provide a welcome screen for your Custom YAWL Service For instance you could redirect to a JSP or just write typical servlet doGet() code inside your subclass.
AuthenticationConfig	getAuthenticationConfig() Gets a reference to the authentication configuration for the local service (if any)
WorkItemRecord	getCachedWorkItem(String workItemID) Gets a locally stored copy of a work item.
List<WorkItemRecord>	getChildren(String workItemID, String sessionHandle) Retrieve a list of all the child work items for a given parent work item
WorkItemRecord	getEngineStoredWorkItem(String workItemID, String sessionHandle) Gets a copy of a workitem form the engine's cache
IBControllerCache	getIBCache()
IBControllerCache	getModel() Deprecated. use getIBCache() instead
protected org.jdom.Element	getResourcingSpecs(YSpecificationID specID, String taskID, String sessionHandle) Retrieve the resourcing specifications for a given task
SpecificationData	getSpecificationData(String specID, String sessionHandle) Deprecated. superseded by getSpecificationData(YSpecificationID, String)
SpecificationData	getSpecificationData(YSpecificationID specID, String sessionHandle) Gets the specification data object with the spec id.
List<SpecificationData>	getSpecificationPrototypesList(String sessionHandle) Gets a list of all specifications currently loaded in the engine
TaskInformation	getTaskInformation(String specID, String taskID, String sessionHandle) Deprecated. superseded by getTaskInformation(YSpecificationID, String, String)
TaskInformation	getTaskInformation(YSpecificationID specID, String taskID, String sessionHandle) Gets metadata of a task.
void	handleCancelledCaseEvent(String caseID) Receives notification from the engine that an active case has been cancelled.
abstract void	handleCancelledWorkItemEvent(WorkItemRecord workItemRecord) Receives notification from the engine that an active workitem has been cancelled.
void	handleCaseResumedEvent(String caseID) Receives notification from the engine that an active case has been cancelled.
void	handleCaseSuspendedEvent(String caseID) Receives notification from the engine that an active case has been cancelled.
void	handleCaseSuspendingEvent(String caseID) Receives notification from the engine that an active case has been cancelled.
void	handleCompleteCaseEvent(String caseID, String casedata) Receives notification from the engine that an active case has been completed.
abstract void	handleEnabledWorkItemEvent(WorkItemRecord enabledWorkItem) Receives notification from the engine of an enabled workitem.
void	handleEngineInitialisationCompletedEvent() Receives notification from the engine that it has finished startup initialisation and is now in a running state.
void	handleStartCaseEvent(YSpecificationID specID, String caseID, String launchingService, boolean delayed) Receives notification from the engine that a case has been started.
void	handleTimerExpiryEvent(WorkItemRecord expiredWorkItem) Receives notification from the engine that an active workitem's timer has expired.
void	handleWorkItemStatusChangeEvent(WorkItemRecord workItem, String oldStatus, String newStatus) Receives notification from the engine that the status of a workitem has been modified.
static void	logContactError(IOException e, String backEndURIStr) Logs the failure of a client to contact the YAWL engine.
protected org.jdom.Element	prepareReplyRootElement(WorkItemRecord enabledWorkItem, String sessionHandle) Utility method to prepare the reply element for checking a work item back into the engine.
protected void	setEngineLogonName(String logonName)
protected void	setEngineLogonPassword(String logonPassword)
void	setRemoteAuthenticationDetails(String userName, String password, String httpProxyHost, String proxyPort) If a custom service is installed outside of a firewall then you will need to set this method once.
void	setUpInterfaceBClient(String backEndURI) Provided that you set up the web.xml file according to the YAWL documentation you do not need to call this method.
boolean	successful(String input) Checks an interface return message for success .

Methods inherited from class java.lang.Object

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

Field Detail

_interfaceBClient

protected InterfaceB_EnvironmentBasedClient _interfaceBClient

_ibCache

protected IBControllerCache _ibCache

_report

protected String _report

XSD_STRINGTYPE

protected static final String XSD_STRINGTYPE

See Also:

Constant Field Values

XSD_ANYURI_TYPE

protected static final String XSD_ANYURI_TYPE

See Also:

Constant Field Values

XSD_NCNAME_TYPE

protected static final String XSD_NCNAME_TYPE

See Also:

Constant Field Values

XSD_NAMESPACE

protected static final String XSD_NAMESPACE

See Also:

Constant Field Values

engineLogonName

protected String engineLogonName

engineLogonPassword

protected String engineLogonPassword

_logger

protected org.apache.log4j.Category _logger

Constructor Detail

InterfaceBWebsideController

public InterfaceBWebsideController()

Constructs a controller.

Method Detail

setUpInterfaceBClient

public void setUpInterfaceBClient(String backEndURI)

Provided that you set up the web.xml file according to the YAWL documentation you do not need to call this method. It allows implementers to set up their webapp so that it has the right objects, and correctly addressed pointers to the engine.

Parameters:

backEndURI - the uri of the engine.

handleEnabledWorkItemEvent

public abstract void handleEnabledWorkItemEvent(WorkItemRecord enabledWorkItem)

Receives notification from the engine of an enabled workitem. Typically, a custom service will implement this method to check out the work item, and process it as appropriate for the service.

Parameters:

enabledWorkItem - the enabled work item

handleCancelledWorkItemEvent

public abstract void handleCancelledWorkItemEvent(WorkItemRecord workItemRecord)

Receives notification from the engine that an active workitem has been cancelled. A custom service will implement this method to take any cleanup action on a previously checked out workitem.

Parameters:

workItemRecord - the cancelled work item

handleCancelledCaseEvent

public void handleCancelledCaseEvent(String caseID)

Receives notification from the engine that an active case has been cancelled. Override this method to take any necessary action.

Parameters:

caseID - the id of the case that has been cancelled

handleStartCaseEvent

public void handleStartCaseEvent(YSpecificationID specID,
                                 String caseID,
                                 String launchingService,
                                 boolean delayed)

Receives notification from the engine that a case has been started. By overriding this method a service can process case start events as required.

Parameters:

specID - the specification id of the started case

caseID - the id of the case

launchingService - the uri (String) of the service that started the case

delayed - true if this is a delayed case start, false if immediate

handleCompleteCaseEvent

public void handleCompleteCaseEvent(String caseID,
                                    String casedata)

Receives notification from the engine that an active case has been completed. By overriding this method a service can process case completion events as required.

Parameters:

caseID - the id of the completed case.

casedata - the set of net-level data for the case when it completes

handleTimerExpiryEvent

public void handleTimerExpiryEvent(WorkItemRecord expiredWorkItem)

Receives notification from the engine that an active workitem's timer has expired. Override this method to handle timer expiries on timed workitems.

Parameters:

expiredWorkItem - the workitem that has an expired timer

handleEngineInitialisationCompletedEvent

public void handleEngineInitialisationCompletedEvent()

Receives notification from the engine that it has finished startup initialisation and is now in a running state. Override this method to handle final service initialisation tasks that require a running engine

handleWorkItemStatusChangeEvent

public void handleWorkItemStatusChangeEvent(WorkItemRecord workItem,
                                            String oldStatus,
                                            String newStatus)

Receives notification from the engine that the status of a workitem has been modified. Override this method to handle any effects a status change might have on a custom service

Parameters:

workItem - the work item that has had its status modified

oldStatus - the work item's previous status

newStatus - the work item's new status

handleCaseSuspendingEvent

public void handleCaseSuspendingEvent(String caseID)

Receives notification from the engine that an active case has been cancelled. Override this method to take any necessary action.

Parameters:

caseID - the id of the case that has been cancelled

handleCaseSuspendedEvent

public void handleCaseSuspendedEvent(String caseID)

Receives notification from the engine that an active case has been cancelled. Override this method to take any necessary action.

Parameters:

caseID - the id of the case that has been cancelled

handleCaseResumedEvent

public void handleCaseResumedEvent(String caseID)

Receives notification from the engine that an active case has been cancelled. Override this method to take any necessary action.

Parameters:

caseID - the id of the case that has been cancelled

destroy

public void destroy()

Receives notification when the environment is being shutdown. Override this method to take any necessary finalisation action.

describeRequiredParams

public YParameter[] describeRequiredParams()

Override this method if you wish to allow other tools to find out what input parameters are required for your custom YAWL service to work.

Returns:

an array of input parameters.

setRemoteAuthenticationDetails

public void setRemoteAuthenticationDetails(String userName,
                                           String password,
                                           String httpProxyHost,
                                           String proxyPort)

If a custom service is installed outside of a firewall then you will need to set this method once. Doing so will allow the WSIF code to access Web services outside your organisation's firewall (http authenticating proxy). NOTE: If your custom YAWL service doesn't need to negotiate a a firewall this method can be ignored

Parameters:

userName - mandatory

password - mandatory

httpProxyHost - optional (if using a non authenticating proxy firewall).

proxyPort - optional (if using a non authenticating proxy firewall).

setEngineLogonName

protected void setEngineLogonName(String logonName)

setEngineLogonPassword

protected void setEngineLogonPassword(String logonPassword)

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws IOException,
                  javax.servlet.ServletException

Override this method to provide a welcome screen for your Custom YAWL Service For instance you could redirect to a JSP or just write typical servlet doGet() code inside your subclass.

Parameters:

request - the request

response - the response.

Throws:

IOException - if an error is detected when the servlet handles the GET request

javax.servlet.ServletException - if the request for the GET could not be handled

checkConnection

public boolean checkConnection(String sessionHandle)
                        throws IOException

Checks if the sessionhandle with the engine is currently active.

Parameters:

sessionHandle - the session handle

Returns:

true if the session handle is valid and active; else false.

Throws:

IOException - if a connection with the engine cannot be established.

connect

public String connect(String userID,
                      String password)
               throws IOException

Creates a session with the engine. A session is automatically disconnected after 60 minutes of inactivity (although this value can be changed via config value in the web.xml file).

Parameters:

userID - the userID

password - the password.

Returns:

a sessionhandle string

Throws:

IOException - if a connection with the engine cannot be established.

checkOut

public WorkItemRecord checkOut(String workItemID,
                               String sessionHandle)
                        throws IOException,
                               YAWLException

Checks a work item out of the engine. Also stores a local copy of the active item.

Parameters:

workItemID - the work item id.

sessionHandle - a valid session handle

Returns:

the resultant checked-out workitem.

Throws:

IOException - if a connection with the engine cannot be established.

YAWLException - if the checkout was unsuccessful

checkInWorkItem

public String checkInWorkItem(String workItemID,
                              String inputData,
                              String outputData,
                              String sessionHandle)
                       throws IOException,
                              org.jdom.JDOMException

Deprecated. since 2.1 - use checkInWorkItem(String, Element, Element, String, String) Checks a work item back into the engine.

Parameters:

workItemID - the work item id.

inputData - the input data.

outputData - the output data.

sessionHandle - the session handle.

Returns:

a diagnostic result of the action - in XML.

Throws:

IOException - if there is a problem contacting the engine.

org.jdom.JDOMException - if there is a problem parsing XML of input or output data

checkInWorkItem

public String checkInWorkItem(String workItemID,
                              org.jdom.Element inputData,
                              org.jdom.Element outputData,
                              String sessionHandle)
                       throws IOException,
                              org.jdom.JDOMException

Deprecated. since 2.1 - use checkInWorkItem(String, Element, Element, String, String) Checks a work item into the engine.

Parameters:

workItemID - the work item id.

inputData - the input data as an XML String.

outputData - the output data as an XML String

sessionHandle - a valid session handle

Returns:

a diagnostic result of the action - in XML.

Throws:

IOException - if there is a problem contacting the engine.

org.jdom.JDOMException - if there is a problem parsing XML of input or output data

checkInWorkItem

public String checkInWorkItem(String workItemID,
                              org.jdom.Element inputData,
                              org.jdom.Element outputData,
                              String logPredicate,
                              String sessionHandle)
                       throws IOException,
                              org.jdom.JDOMException

Checks a work item into the engine.

Parameters:

workItemID - the work item id.

inputData - the input data as an XML String.

outputData - the output data as an XML String

logPredicate - a configurable logging string to be logged when the item completes. May be a simple string or an xml'd YLogDataItemList object.

sessionHandle - a valid session handle

Returns:

a diagnostic result of the action - in XML.

Throws:

IOException - if there is a problem contacting the engine.

org.jdom.JDOMException - if there is a problem parsing XML of input or output data

getCachedWorkItem

public WorkItemRecord getCachedWorkItem(String workItemID)

Gets a locally stored copy of a work item.

Parameters:

workItemID - the id of the workitem to retrieve

Returns:

a local (to the custom service) cached copy of the workitem.

getEngineStoredWorkItem

public WorkItemRecord getEngineStoredWorkItem(String workItemID,
                                              String sessionHandle)
                                       throws IOException

Gets a copy of a workitem form the engine's cache

Parameters:

workItemID - the id of the workitem to retrieve

sessionHandle - a valid sesion handle

Returns:

a remote (to the custom service) cached copy of the workitem.

Throws:

IOException - if there is a problem contacting the engine.

getTaskInformation

public TaskInformation getTaskInformation(String specID,
                                          String taskID,
                                          String sessionHandle)
                                   throws IOException

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

Gets metadata of a task.

Parameters:

specID - the specification id

taskID - the task id

sessionHandle - a valid session handle

Returns:

a task metadata description

Throws:

IOException - if there is a problem contacting the engine.

getTaskInformation

public TaskInformation getTaskInformation(YSpecificationID specID,
                                          String taskID,
                                          String sessionHandle)
                                   throws IOException

Gets metadata of a task.

Parameters:

specID - the specification id

taskID - the task id

sessionHandle - a valid session handle

Returns:

a task metadata description

Throws:

IOException - if there is a problem contacting the engine.

getModel

public IBControllerCache getModel()

Deprecated. use getIBCache() instead

Gets a reference to the local cache

Returns:

a reference to the cache

getIBCache

public IBControllerCache getIBCache()

getAuthenticationConfig

public AuthenticationConfig getAuthenticationConfig()

Gets a reference to the authentication configuration for the local service (if any)

Returns:

the authentication object for this instantiation

getChildren

public List<WorkItemRecord> getChildren(String workItemID,
                                        String sessionHandle)
                                 throws IOException

Retrieve a list of all the child work items for a given parent work item

Parameters:

workItemID - the id of the parent workitem

sessionHandle - a valid session handle

Returns:

the list of child workitems

Throws:

IOException - if there is a problem contacting the engine.

logContactError

public static void logContactError(IOException e,
                                   String backEndURIStr)

Logs the failure of a client to contact the YAWL engine. gives some suggestion of why?

Parameters:

e - the thrown exception

backEndURIStr - the uri of the engine

successful

public boolean successful(String input)

Checks an interface return message for success .

Parameters:

input - the return message

Returns:

true if the message indicates success; false if otherwise

getSpecificationPrototypesList

public List<SpecificationData> getSpecificationPrototypesList(String sessionHandle)
                                                       throws IOException

Gets a list of all specifications currently loaded in the engine

Parameters:

sessionHandle - a valid session handle

Returns:

the full list of specifications

Throws:

IOException - if there is a problem contacting the engine.

getSpecificationData

public SpecificationData getSpecificationData(String specID,
                                              String sessionHandle)
                                       throws IOException

Deprecated. superseded by getSpecificationData(YSpecificationID, String)

Gets the specification data object with the spec id. If called it will return the specdata object and the entire XML representation of the specification.

Parameters:

specID - the specification id

sessionHandle - a valid session handle

Returns:

a specification data object

Throws:

IOException - if there is a problem contacting the engine.

getSpecificationData

public SpecificationData getSpecificationData(YSpecificationID specID,
                                              String sessionHandle)
                                       throws IOException

Gets the specification data object with the spec id. If called it will return the specdata object including the entire XML representation of the specification.

Parameters:

specID - the specification id

sessionHandle - a valid session handle

Returns:

a specification data object

Throws:

IOException - if there is a problem contacting the engine.

checkOutAllInstancesOfThisTask

protected List<WorkItemRecord> checkOutAllInstancesOfThisTask(WorkItemRecord enabledWorkItem,
                                                              String sessionHandle)
                                                       throws IOException,
                                                              YAWLException

Utility method for implementers to use for helping to check all instances of a given task out of the engine.

Parameters:

enabledWorkItem - an enabled WorkItemRecord.

sessionHandle - a valid session handle with the engine.

Returns:

a list of work item records that correspond to the executing work-items that should be checked back into the engine when the task is complete.

Throws:

IOException - if there is a problem communicating with the engine.

YAWLException - if the checkout is unsuccessful

prepareReplyRootElement

protected org.jdom.Element prepareReplyRootElement(WorkItemRecord enabledWorkItem,
                                                   String sessionHandle)
                                            throws IOException

Utility method to prepare the reply element for checking a work item back into the engine.

Parameters:

enabledWorkItem - the enabled work item.

sessionHandle - the session handle

Returns:

an empty root element correctly named according to the version of the process specification.

Throws:

IOException - if there is a problem communicating with the engine.

getResourcingSpecs

protected org.jdom.Element getResourcingSpecs(YSpecificationID specID,
                                              String taskID,
                                              String sessionHandle)
                                       throws IOException

Retrieve the resourcing specifications for a given task

Parameters:

specID - the specification id

taskID - the task id

sessionHandle - a valid sessionhandle

Returns:

the task's resourcing specification, or null if it doesn't have one (pre v2.0)

Throws:

IOException - if there is a problem communicating with the engine.