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

java.lang.Object
  extended by 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.


Copyright © 2004-2012 The YAWL Foundation.