org.yawlfoundation.yawl.engine

Class YEngine

java.lang.Object

org.yawlfoundation.yawl.engine.YEngine

All Implemented Interfaces:

InterfaceADesign, InterfaceAManagement, InterfaceBClient, InterfaceBInterop

Direct Known Subclasses:

YEngineImpl

public class YEngine
extends java.lang.Object
implements InterfaceADesign, InterfaceAManagement, InterfaceBClient, InterfaceBInterop

Author:

Lachlan Aldred Date: 17/06/2003 Time: 13:46:54, Michael Adams (refactoring for v2.0-2.1)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	YEngine.Status

Field Summary

Fields

Modifier and Type	Field and Description
protected YNetRunnerRepository	_netRunnerRepository
protected static YPersistenceManager	_pmgr
protected static YEngine	_thisInstance

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	YEngine() The Constructor - called from getInstance().

Method Summary

Modifier and Type	Method and Description
boolean	addExternalClient(YExternalClient client) Adds an external client credentials object to the engine.
boolean	addInterfaceXListener(java.lang.String observerURI) sets the URI passed as an listener for exception events
protected void	addRunner(YNetRunner runner) Adds a net runner instance to the engine caches.
void	addRunner(YNetRunner runner, YSpecification specification) Adds a net runner instance to the engine caches.
java.util.List<YSpecificationID>	addSpecifications(java.lang.String specStr, boolean ignoreErrors, YVerificationHandler verificationHandler) Adds the specification(s) (expressed as an xml string) to the engine
void	addYawlService(YAWLServiceReference yawlService) Adds a YAWL service to the engine.
java.lang.String	allocateCaseID() AJH: Public method which returns the next available caseID Note: This is only available with a non-persisting engine and is used to ascertain the case ID prior to launching a case (eg.
boolean	canAddNewInstances(java.lang.String workItemID) Checks whether new dynamic workitem instances can be started for a task
void	cancelCase(YIdentifier id) Deprecated. use cancelCase(YIdentifier, String)
void	cancelCase(YIdentifier caseID, java.lang.String serviceHandle) Cancels a running case.
void	cancelWorkItem(YWorkItem workItem)
void	checkElegibilityToAddInstances(java.lang.String workItemID) Determines whether or not a task will allow a dynamically created new instance to be created.
void	checkEngineRunning()
protected void	clearCaseFromPersistence(YIdentifier id) Clears a case from persistence
void	completeWorkItem(YWorkItem workItem, java.lang.String data, java.lang.String logPredicate, WorkItemCompletion completionType) Completes the work item.
YWorkItem	createNewInstance(YWorkItem workItem, java.lang.String paramValueForMICreation) Creates a new work item instance when possible.
void	deleteObject(java.lang.Object obj)
void	demote()
void	disableProcessLogging()
void	dump() Invokes a diagnostic dump of the engine's internal tables.
protected Element	formatCaseParams(java.lang.String paramStr, YSpecification spec)
boolean	generateUIMetaData() Indicates if user interface metadata will be generated within a task's input XML doclet.
java.util.Set<YWorkItem>	getAllWorkItems() Returns a set of all work items, regardless of state, from the engine.
AnnouncementContext	getAnnouncementContext()
YAnnouncer	getAnnouncer()
java.util.Set<YWorkItem>	getAvailableWorkItems() Returns a set of all availkable workitems from the engine.
YBuildProperties	getBuildProperties()
java.lang.String	getCaseData(java.lang.String caseID) Returns an XML representation of the current net data of the case corresponding to caseID.
YNetData	getCaseData(YIdentifier id)
Document	getCaseDataDocument(java.lang.String id)
YIdentifier	getCaseID(java.lang.String caseIDStr) Returns the internal engine identifier for a case.
java.util.Set<YIdentifier>	getCasesForSpecification(YSpecificationID specID) Given a process specification id return the cases that are its running instances.
java.util.Set	getChildrenOfWorkItem(YWorkItem workItem)
YAWLServiceReference	getDefaultWorklist()
java.lang.String	getEngineClassesRootFilePath()
YEngine.Status	getEngineStatus()
YExternalClient	getExternalClient(java.lang.String name)
java.util.Set<YExternalClient>	getExternalClients()
java.lang.String	getHibernateStatistics()
static YEngine	getInstance() Initialises the engine (if not already initialised) & returns the engine instance, using the default persistence flag.
static YEngine	getInstance(boolean persisting)
static YEngine	getInstance(boolean persisting, boolean gatherHbnStats)
static YEngine	getInstance(boolean persisting, boolean gatherHbnStats, boolean redundantMode) Initialises the engine (if not already initialised) & returns the engine instance.
InstanceCache	getInstanceCache()
YSpecification	getLatestSpecification(java.lang.String key) Returns the latest loaded version of a specification identified by 'key'
java.util.Set<YSpecificationID>	getLoadedSpecificationIDs() Provides the set of specification ids for specs loaded into the engine.
java.lang.String	getLoadStatus(YSpecificationID specID) Indicates the load status of the supplied specification ID.
java.lang.String	getNetData(java.lang.String caseID)
YNetRunner	getNetRunner(YIdentifier identifier)
YNetRunner	getNetRunner(YWorkItem workItem)
YNetRunnerRepository	getNetRunnerRepository()
java.lang.String	getNextCaseNbr()
java.util.Map<java.lang.String,YParameter>	getParameters(YSpecificationID specID, java.lang.String taskID, boolean input)
static YPersistenceManager	getPersistenceManager()
YSpecification	getProcessDefinition(YSpecificationID specID) Returns the specification for a loaded specification via the supplied specification ID.
YAWLServiceReference	getRegisteredYawlService(java.lang.String yawlServiceID)
java.util.List<YNetRunner>	getRunnersForPrimaryCase(YIdentifier primaryCaseID) Returns a vector of all net runners for a top level caseID.
java.util.List<YIdentifier>	getRunningCaseIDs() Returns a list of the YIdentifiers objects for running cases.
java.util.Map<YSpecificationID,java.util.List<YIdentifier>>	getRunningCaseMap() Gets the complete map of all running case ids, grouped by specification id
YSessionCache	getSessionCache()
YSpecification	getSpecification(YSpecificationID specID)
java.lang.String	getSpecificationDataSchema(YSpecificationID specID)
YSpecification	getSpecificationForCase(YIdentifier caseID)
Element	getStartingDataSnapshot(java.lang.String itemID)
java.lang.String	getStateForCase(YIdentifier caseID) Returns the state for a case.
java.lang.String	getStateTextForCase(YIdentifier caseID) Returns the text description for the state that a case is currently in.
YTask	getTaskDefinition(YSpecificationID specID, java.lang.String taskID) Returns the task definition, not the task instance.
java.util.Set	getUsers() Returns a set of users currently loaded within the engine.
YWorkItem	getWorkItem(java.lang.String workItemID)
YWorkItemRepository	getWorkItemRepository()
java.util.Set<YAWLServiceReference>	getYAWLServices() Returns a set of YAWL services registered in the engine.
void	initBuildProperties(java.io.InputStream stream)
protected static void	initialise(YPersistenceManager pmgr, boolean persisting, boolean gatherHbnStats, boolean redundantMode)
void	initialised(int maxWaitSeconds)
boolean	isGenericAdminAllowed()
boolean	isHibernateStatisticsEnabled()
static boolean	isPersisting() Indicates if persistence is enabled.
static boolean	isRunning() Checks if the engine is currently running
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.net.URI completionObserver, java.lang.String caseID, YLogDataItemList logData, java.lang.String serviceHandle, boolean delayed) Starts an instance of a specification (known as a 'case') within the engine.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.net.URI completionObserver, YLogDataItemList logData) Starts an instance of a specification (known as a 'case') within the engine.
java.lang.String	launchCase(YSpecificationID specID, java.lang.String caseParams, java.net.URI completionObserver, YLogDataItemList logData, java.lang.String serviceHandle)
protected java.util.Set<YClient>	loadDefaultClients() Loads the logon accounts for the standard client apps and services from a properties file on startup when they have not previously been persisted (ie.
boolean	loadSpecification(YSpecification spec) Loads a specification
void	promote()
int	reannounceEnabledWorkItems() Causes the engine to re-announce all workitems which are in an "enabled" state.
int	reannounceExecutingWorkItems() Causes the engine to re-announce all workitems which are in an "executing" state.
int	reannounceFiredWorkItems() Causes the engine to re-announce all workitems which are in an "fired" state.
void	reannounceWorkItem(YWorkItem workItem) Causes the engine to re-announce a specific workitem regardless of state.
void	registerInterfaceAClient(InterfaceAManagementObserver observer) Register an InterfaceA management client with the engine in order to recieve callbacks.
void	registerInterfaceBObserver(InterfaceBClientObserver observer) Register an InterfaceB client with the engine in order to receive callbacks.
void	registerInterfaceBObserverGateway(ObserverGateway gateway) Registers an InterfaceB Observer Gateway with the engine in order to receive callbacks.
protected void	removeCaseFromCaches(YIdentifier caseID) Finalises a case completion.
YExternalClient	removeExternalClient(java.lang.String clientName)
boolean	removeInterfaceXListener(java.lang.String uri) removes an exception event listener
YAWLServiceReference	removeYawlService(java.lang.String serviceURI) Removes a YAWL service from the engine.
void	resumeCase(YIdentifier id) Resumes execution of a case.
void	rollbackWorkItem(java.lang.String workItemID)
void	setAllowAdminID(boolean allow)
void	setDefaultWorklist(java.lang.String paramStr) Sets the custom service that will serve as the default worklist.
void	setEngineClassesRootFilePath(java.lang.String path)
void	setEngineStatus(YEngine.Status status)
void	setGenerateUIMetaData(boolean generate) Indicate if user interface metadata is to be generated within a task's input XML doclet.
void	setHibernateStatisticsEnabled(boolean enabled)
void	shutdown()
YWorkItem	skipWorkItem(YWorkItem workItem, YClient client)
protected YIdentifier	startCase(YSpecificationID specID, java.lang.String caseParams, java.net.URI completionObserver, java.lang.String caseID, YLogDataItemList logData, java.lang.String serviceRef, boolean delayed)
YWorkItem	startWorkItem(java.lang.String itemID, YClient client)
YWorkItem	startWorkItem(YWorkItem workItem, YClient client) Starts a work item.
void	storeObject(java.lang.Object obj) Public interface to allow engine clients to ask the engine to store an object reference in its persistent storage.
void	suspendCase(YIdentifier caseID) Suspends the execution of a case - currently only called from YAdminGUI.
YWorkItem	suspendWorkItem(java.lang.String workItemID)
void	unloadSpecification(YSpecificationID specID) Removes a previously loaded specification from the engine
YWorkItem	unsuspendWorkItem(java.lang.String workItemID)
boolean	updateCaseData(java.lang.String idStr, java.lang.String data) updates the case data with the data passed after completion of an exception handler
boolean	updateExternalClient(java.lang.String id, java.lang.String password, java.lang.String doco)
void	updateObject(java.lang.Object obj)
boolean	updateWorkItemData(java.lang.String workItemID, java.lang.String data) updates the workitem with the data passed after completion of an exception handler

Methods inherited from class java.lang.Object

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

Field Detail

_pmgr

protected static YPersistenceManager _pmgr

_thisInstance

protected static YEngine _thisInstance

_netRunnerRepository

protected YNetRunnerRepository _netRunnerRepository

Constructor Detail

YEngine

protected YEngine()

The Constructor - called from getInstance().

Method Detail

getInstance

public static YEngine getInstance(boolean persisting,
                                  boolean gatherHbnStats,
                                  boolean redundantMode)
                           throws YPersistenceException

Initialises the engine (if not already initialised) & returns the engine instance.

Parameters:

persisting - true if engine state is to be persisted

Returns:

a reference to the initialised engine

Throws:

YPersistenceException - if there's a problem restoring from persistence

getInstance

public static YEngine getInstance(boolean persisting)
                           throws YPersistenceException

Throws:

YPersistenceException

getInstance

public static YEngine getInstance(boolean persisting,
                                  boolean gatherHbnStats)
                           throws YPersistenceException

Throws:

YPersistenceException

getInstance

public static YEngine getInstance()

Initialises the engine (if not already initialised) & returns the engine instance, using the default persistence flag.

Returns:

a reference to the initialised engine

initialise

protected static void initialise(YPersistenceManager pmgr,
                                 boolean persisting,
                                 boolean gatherHbnStats,
                                 boolean redundantMode)
                          throws YPersistenceException

Throws:

YPersistenceException

isRunning

public static boolean isRunning()

Checks if the engine is currently running

Returns:

true if running, false otherwise

promote

public void promote()
             throws YPersistenceException

Throws:

YPersistenceException

demote

public void demote()

loadDefaultClients

protected java.util.Set<YClient> loadDefaultClients()
                                             throws YPersistenceException

Loads the logon accounts for the standard client apps and services from a properties file on startup when they have not previously been persisted (ie. on first startup) or when persistence is disabled.

Returns:

the set of default clients loaded.

Throws:

YPersistenceException - A passthrough - since it is only called when restoring or when persistence is disabled, this exception is never thrown.

setGenerateUIMetaData

public void setGenerateUIMetaData(boolean generate)

Indicate if user interface metadata is to be generated within a task's input XML doclet.

Parameters:

generate - true to generate metadata, false to not generate it

generateUIMetaData

public boolean generateUIMetaData()

Indicates if user interface metadata will be generated within a task's input XML doclet.

Returns:

true=UIMetaData generated, false=UIMetaData not supported

getInstanceCache

public InstanceCache getInstanceCache()

getParameters

public java.util.Map<java.lang.String,YParameter> getParameters(YSpecificationID specID,
                                                                java.lang.String taskID,
                                                                boolean input)

getEngineClassesRootFilePath

public java.lang.String getEngineClassesRootFilePath()

setEngineClassesRootFilePath

public void setEngineClassesRootFilePath(java.lang.String path)

initialised

public void initialised(int maxWaitSeconds)

shutdown

public void shutdown()

initBuildProperties

public void initBuildProperties(java.io.InputStream stream)

getBuildProperties

public YBuildProperties getBuildProperties()

getSessionCache

public YSessionCache getSessionCache()

checkEngineRunning

public void checkEngineRunning()
                        throws YEngineStateException

Throws:

YEngineStateException

registerInterfaceAClient

public void registerInterfaceAClient(InterfaceAManagementObserver observer)

Description copied from interface: InterfaceAManagement

Register an InterfaceA management client with the engine in order to recieve callbacks.

Specified by:

registerInterfaceAClient in interface InterfaceAManagement

registerInterfaceBObserver

public void registerInterfaceBObserver(InterfaceBClientObserver observer)

Description copied from interface: InterfaceBClient

Register an InterfaceB client with the engine in order to receive callbacks.

Specified by:

registerInterfaceBObserver in interface InterfaceBClient

registerInterfaceBObserverGateway

public void registerInterfaceBObserverGateway(ObserverGateway gateway)
                                       throws YAWLException

Registers an InterfaceB Observer Gateway with the engine in order to receive callbacks.

Specified by:

registerInterfaceBObserverGateway in interface InterfaceBClient

Parameters:

gateway - the gateway to register

Throws:

YAWLException - if the observerGateway has a null scheme value.

getAnnouncer

public YAnnouncer getAnnouncer()

Specified by:

getAnnouncer in interface InterfaceAManagement

setEngineStatus

public void setEngineStatus(YEngine.Status status)

Specified by:

setEngineStatus in interface InterfaceAManagement

getEngineStatus

public YEngine.Status getEngineStatus()

Specified by:

getEngineStatus in interface InterfaceAManagement

getAnnouncementContext

public AnnouncementContext getAnnouncementContext()

Specified by:

getAnnouncementContext in interface InterfaceAManagement

reannounceEnabledWorkItems

public int reannounceEnabledWorkItems()
                               throws YStateException

Description copied from interface: InterfaceAManagement

Causes the engine to re-announce all workitems which are in an "enabled" state.

Specified by:

reannounceEnabledWorkItems in interface InterfaceAManagement

Returns:

The number of enabled workitems that were reannounced

Throws:

YStateException

reannounceExecutingWorkItems

public int reannounceExecutingWorkItems()
                                 throws YStateException

Description copied from interface: InterfaceAManagement

Causes the engine to re-announce all workitems which are in an "executing" state.

Specified by:

reannounceExecutingWorkItems in interface InterfaceAManagement

Returns:

The number of executing workitems that were reannounced

Throws:

YStateException

reannounceFiredWorkItems

public int reannounceFiredWorkItems()
                             throws YStateException

Description copied from interface: InterfaceAManagement

Causes the engine to re-announce all workitems which are in an "fired" state.

Specified by:

reannounceFiredWorkItems in interface InterfaceAManagement

Returns:

The number of fired workitems that were reannounced

Throws:

YStateException

reannounceWorkItem

public void reannounceWorkItem(YWorkItem workItem)
                        throws YStateException

Description copied from interface: InterfaceAManagement

Causes the engine to re-announce a specific workitem regardless of state.

Note: This interface current;y only supported workitems in the following states:

Enabled Executing Fired

Specified by:

reannounceWorkItem in interface InterfaceAManagement

Throws:

YStateException

addRunner

protected void addRunner(YNetRunner runner)

Adds a net runner instance to the engine caches. The specification is derived from the runner instance.

Parameters:

runner - the runner to add

addRunner

public void addRunner(YNetRunner runner,
                      YSpecification specification)

Adds a net runner instance to the engine caches.

Parameters:

runner - the runner to add

specification - its specification

getRunnersForPrimaryCase

public java.util.List<YNetRunner> getRunnersForPrimaryCase(YIdentifier primaryCaseID)

Returns a vector of all net runners for a top level caseID.

Parameters:

primaryCaseID - the id of the case

Returns:

Vector of net runners for the case

getNetRunner

public YNetRunner getNetRunner(YWorkItem workItem)

getNetRunner

public YNetRunner getNetRunner(YIdentifier identifier)

getNetRunnerRepository

public YNetRunnerRepository getNetRunnerRepository()

getNetData

public java.lang.String getNetData(java.lang.String caseID)
                            throws YStateException

Throws:

YStateException

addSpecifications

public java.util.List<YSpecificationID> addSpecifications(java.lang.String specStr,
                                                          boolean ignoreErrors,
                                                          YVerificationHandler verificationHandler)
                                                   throws YPersistenceException

Adds the specification(s) (expressed as an xml string) to the engine

Specified by:

addSpecifications in interface InterfaceAManagement

Parameters:

specStr - an XML formatted specification

ignoreErrors - ignore verification errors and load the spec anyway.

verificationHandler - an in/out param passing any error messages.

Returns:

the specification ids of the successfully loaded specs

Throws:

YPersistenceException

loadSpecification

public boolean loadSpecification(YSpecification spec)

Loads a specification

Specified by:

loadSpecification in interface InterfaceAManagement

Parameters:

spec - the specification to load

Returns:

true if spec is loaded, false if it was already loaded

unloadSpecification

public void unloadSpecification(YSpecificationID specID)
                         throws YStateException,
                                YPersistenceException

Removes a previously loaded specification from the engine

Specified by:

unloadSpecification in interface InterfaceAManagement

Parameters:

specID - the identifier of the specification to unload

Throws:

YStateException - if the spec is still in use (with a live case)

YPersistenceException - if there's some persistence problem

getLoadedSpecificationIDs

public java.util.Set<YSpecificationID> getLoadedSpecificationIDs()

Provides the set of specification ids for specs loaded into the engine. It returns those that were loaded as well as those with running instances that are unloaded.

Specified by:

getLoadedSpecificationIDs in interface InterfaceAManagement

Returns:

A set of specification ids

getLatestSpecification

public YSpecification getLatestSpecification(java.lang.String key)

Returns the latest loaded version of a specification identified by 'key'

Specified by:

getLatestSpecification in interface InterfaceAManagement

Parameters:

key - the spec's identifier (v2.0+) or uri (pre-v2.0)

Returns:

the matching specification or null if no match found

getSpecification

public YSpecification getSpecification(YSpecificationID specID)

Specified by:

getSpecification in interface InterfaceAManagement

getSpecificationForCase

public YSpecification getSpecificationForCase(YIdentifier caseID)

Specified by:

getSpecificationForCase in interface InterfaceAManagement

getProcessDefinition

public YSpecification getProcessDefinition(YSpecificationID specID)

Description copied from interface: InterfaceAManagement

Returns the specification for a loaded specification via the supplied specification ID.

Specified by:

getProcessDefinition in interface InterfaceAManagement

Returns:

the specification matching the id

getSpecificationDataSchema

public java.lang.String getSpecificationDataSchema(YSpecificationID specID)

getLoadStatus

public java.lang.String getLoadStatus(YSpecificationID specID)

Description copied from interface: InterfaceAManagement

Indicates the load status of the supplied specification ID.

Specified by:

getLoadStatus in interface InterfaceAManagement

Returns:

the current laod status for the specification with the id passed

getCasesForSpecification

public java.util.Set<YIdentifier> getCasesForSpecification(YSpecificationID specID)

Given a process specification id return the cases that are its running instances.

Specified by:

getCasesForSpecification in interface InterfaceAManagement

Parameters:

specID - the process specification id string.

Returns:

a set of YIdentifer caseIDs that are run time instances of the process specification with id = specID

getRunningCaseMap

public java.util.Map<YSpecificationID,java.util.List<YIdentifier>> getRunningCaseMap()

Gets the complete map of all running case ids, grouped by specification id

Returns:

a map of [YSpecificationID, List]

startCase

protected YIdentifier startCase(YSpecificationID specID,
                                java.lang.String caseParams,
                                java.net.URI completionObserver,
                                java.lang.String caseID,
                                YLogDataItemList logData,
                                java.lang.String serviceRef,
                                boolean delayed)
                         throws YStateException,
                                YDataStateException,
                                YQueryException,
                                YPersistenceException

Throws:

YStateException

YDataStateException

YQueryException

YPersistenceException

formatCaseParams

protected Element formatCaseParams(java.lang.String paramStr,
                                   YSpecification spec)
                            throws YStateException

Throws:

YStateException

removeCaseFromCaches

protected void removeCaseFromCaches(YIdentifier caseID)

Finalises a case completion.

Parameters:

caseID - the id of the completing case

Throws:

YPersistenceException - if theres a persistence problem

cancelCase

public void cancelCase(YIdentifier caseID,
                       java.lang.String serviceHandle)
                throws YPersistenceException,
                       YEngineStateException

Cancels a running case.

Parameters:

caseID - the identifier of the cancelling case

Throws:

YPersistenceException - if there's some persistence problem

YEngineStateException

cancelCase

public void cancelCase(YIdentifier id)
                throws YPersistenceException,
                       YEngineStateException

Deprecated. use cancelCase(YIdentifier, String)

Description copied from interface: InterfaceAManagement

Cancel the execution of a case.

Specified by:

cancelCase in interface InterfaceAManagement

Parameters:

id -

Throws:

YPersistenceException

YEngineStateException

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.net.URI completionObserver,
                                   YLogDataItemList logData)
                            throws YStateException,
                                   YDataStateException,
                                   YPersistenceException,
                                   YEngineStateException,
                                   YQueryException

Description copied from interface: InterfaceBClient

Starts an instance of a specification (known as a 'case') within the engine.

Specified by:

launchCase in interface InterfaceBClient

Parameters:

specID - the specification id.

caseParams - the XML string of the case params (can be null).

completionObserver - the observer for completion events (can be null).

Returns:

the caseid of the started case

Throws:

YStateException

YDataStateException

YPersistenceException

YEngineStateException

YQueryException

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.net.URI completionObserver,
                                   YLogDataItemList logData,
                                   java.lang.String serviceHandle)
                            throws YStateException,
                                   YDataStateException,
                                   YPersistenceException,
                                   YEngineStateException,
                                   YQueryException

Throws:

YStateException

YDataStateException

YPersistenceException

YEngineStateException

YQueryException

launchCase

public java.lang.String launchCase(YSpecificationID specID,
                                   java.lang.String caseParams,
                                   java.net.URI completionObserver,
                                   java.lang.String caseID,
                                   YLogDataItemList logData,
                                   java.lang.String serviceHandle,
                                   boolean delayed)
                            throws YStateException,
                                   YDataStateException,
                                   YEngineStateException,
                                   YQueryException,
                                   YPersistenceException

Description copied from interface: InterfaceBClient

Starts an instance of a specification (known as a 'case') within the engine.

Specified by:

launchCase in interface InterfaceBClient

Parameters:

specID - the specification id.

caseParams - the XML string of the case params (can be null).

completionObserver - the observer for completion events (can be null).

caseID - The case identifier to use (not supported in a persisting engine)

Returns:

the caseid of the started case

Throws:

YStateException

YDataStateException

YEngineStateException

YQueryException

YPersistenceException

getCaseID

public YIdentifier getCaseID(java.lang.String caseIDStr)

Description copied from interface: InterfaceAManagement

Returns the internal engine identifier for a case.

Specified by:

getCaseID in interface InterfaceAManagement

Returns:

the internal engine identifier for a case

getStateTextForCase

public java.lang.String getStateTextForCase(YIdentifier caseID)

Description copied from interface: InterfaceAManagement

Returns the text description for the state that a case is currently in.

Specified by:

getStateTextForCase in interface InterfaceAManagement

Returns:

a text description of the current case state

getStateForCase

public java.lang.String getStateForCase(YIdentifier caseID)

Description copied from interface: InterfaceAManagement

Returns the state for a case.

Specified by:

getStateForCase in interface InterfaceAManagement

Returns:

the current case state

getCaseData

public java.lang.String getCaseData(java.lang.String caseID)
                             throws YStateException

Description copied from interface: InterfaceBClient

Returns an XML representation of the current net data of the case corresponding to caseID.

Specified by:

getCaseData in interface InterfaceBClient

Parameters:

caseID - to retrieve net data of

Returns:

XML representation of the net

Throws:

YStateException

getRunningCaseIDs

public java.util.List<YIdentifier> getRunningCaseIDs()

Returns a list of the YIdentifiers objects for running cases.

Returns:

List of running cases

getNextCaseNbr

public java.lang.String getNextCaseNbr()

Returns:

the next available case number.

allocateCaseID

public java.lang.String allocateCaseID()
                                throws YPersistenceException

AJH: Public method which returns the next available caseID Note: This is only available with a non-persisting engine and is used to ascertain the case ID prior to launching a case (eg. for an XForms execution framework).

Specified by:

allocateCaseID in interface InterfaceBClient

Returns:

A unique case ID

Throws:

YPersistenceException - if there's a problem persisting the change

suspendCase

public void suspendCase(YIdentifier caseID)
                 throws YPersistenceException,
                        YStateException

Suspends the execution of a case - currently only called from YAdminGUI.

Specified by:

suspendCase in interface InterfaceAManagement

Parameters:

caseID - the id of the case to suspend

Throws:

YPersistenceException - if there's a problem persisting the change

YStateException - if case cannot be suspended given the current engine

resumeCase

public void resumeCase(YIdentifier id)
                throws YPersistenceException,
                       YStateException

Resumes execution of a case.

Specified by:

resumeCase in interface InterfaceAManagement

Parameters:

id - the id of the case to resume

Throws:

YPersistenceException - if there's a problem persisting the resumed case

YStateException - if case cannot be resumed

getCaseData

public YNetData getCaseData(YIdentifier id)

Parameters:

id - the id of the case

Returns:

the case level data for the case

updateCaseData

public boolean updateCaseData(java.lang.String idStr,
                              java.lang.String data)
                       throws YPersistenceException

updates the case data with the data passed after completion of an exception handler

Throws:

YPersistenceException

getCaseDataDocument

public Document getCaseDataDocument(java.lang.String id)

Returns:

the current case data for the case id passed

getTaskDefinition

public YTask getTaskDefinition(YSpecificationID specID,
                               java.lang.String taskID)

Returns the task definition, not the task instance.

Specified by:

getTaskDefinition in interface InterfaceBClient

Parameters:

specID - the specification id

taskID - the task id

Returns:

the task definition object.

getWorkItemRepository

public YWorkItemRepository getWorkItemRepository()

getAvailableWorkItems

public java.util.Set<YWorkItem> getAvailableWorkItems()

Description copied from interface: InterfaceBClient

Returns a set of all availkable workitems from the engine.

Specified by:

getAvailableWorkItems in interface InterfaceBClient

Returns:

Set of available work items

getWorkItem

public YWorkItem getWorkItem(java.lang.String workItemID)

Specified by:

getWorkItem in interface InterfaceBClient

getAllWorkItems

public java.util.Set<YWorkItem> getAllWorkItems()

Description copied from interface: InterfaceBClient

Returns a set of all work items, regardless of state, from the engine.

Specified by:

getAllWorkItems in interface InterfaceBClient

Returns:

Set of work items

startWorkItem

public YWorkItem startWorkItem(java.lang.String itemID,
                               YClient client)
                        throws YStateException,
                               YDataStateException,
                               YQueryException,
                               YPersistenceException,
                               YEngineStateException

Throws:

YStateException

YDataStateException

YQueryException

YPersistenceException

YEngineStateException

getStartingDataSnapshot

public Element getStartingDataSnapshot(java.lang.String itemID)
                                throws YStateException,
                                       YEngineStateException,
                                       YDataStateException,
                                       YQueryException

Throws:

YStateException

YEngineStateException

YDataStateException

YQueryException

startWorkItem

public YWorkItem startWorkItem(YWorkItem workItem,
                               YClient client)
                        throws YStateException,
                               YDataStateException,
                               YQueryException,
                               YPersistenceException,
                               YEngineStateException

Starts a work item. If the workitem param is enabled this method fires the task and returns the first of its child instances in the executing state. Else if the workitem is fired then it moves the state from fired to executing. Either way the method returns the resultant work item.

Specified by:

startWorkItem in interface InterfaceBClient

Parameters:

workItem - the enabled, or fired workitem.

client - the YAWL external client or service starting the workitem

Returns:

the resultant work item in the executing state.

Throws:

YStateException - if the workitem is not in either of these states.

YDataStateException

YQueryException

YPersistenceException

YEngineStateException

completeWorkItem

public void completeWorkItem(YWorkItem workItem,
                             java.lang.String data,
                             java.lang.String logPredicate,
                             WorkItemCompletion completionType)
                      throws YStateException,
                             YDataStateException,
                             YQueryException,
                             YPersistenceException,
                             YEngineStateException

Completes the work item.

Specified by:

completeWorkItem in interface InterfaceBClient

Parameters:

workItem -

data -

logPredicate - - a pre-parse of the completion log predicate for this item

completionType - - one of the completion types 'normal' (ordinary completion) 'force' (forced completion) or 'fail' (forced fail) completion

Throws:

YStateException

YDataStateException

YQueryException

YPersistenceException

YEngineStateException

skipWorkItem

public YWorkItem skipWorkItem(YWorkItem workItem,
                              YClient client)
                       throws YStateException,
                              YDataStateException,
                              YQueryException,
                              YPersistenceException,
                              YEngineStateException

Throws:

YStateException

YDataStateException

YQueryException

YPersistenceException

YEngineStateException

checkElegibilityToAddInstances

public void checkElegibilityToAddInstances(java.lang.String workItemID)
                                    throws YStateException

Determines whether or not a task will allow a dynamically created new instance to be created. MultiInstance Task with dynamic instance creation.

Specified by:

checkElegibilityToAddInstances in interface InterfaceBClient

Parameters:

workItemID - the workItemID of a sibling work item.

Throws:

YStateException - if task is not MultiInstance, or if task does not allow dynamic instance creation, or if current number of instances is not less than the maxInstances for the task.

canAddNewInstances

public boolean canAddNewInstances(java.lang.String workItemID)

Checks whether new dynamic workitem instances can be started for a task

Parameters:

workItemID - the id of the workitem to check against

Returns:

true if a new workitem can be dynamically spawned

Precondition:

the workitem is in executing state

createNewInstance

public YWorkItem createNewInstance(YWorkItem workItem,
                                   java.lang.String paramValueForMICreation)
                            throws YStateException,
                                   YPersistenceException

Creates a new work item instance when possible.

Specified by:

createNewInstance in interface InterfaceBClient

Parameters:

workItem - the id of a work item inside the task to have a new instance.

paramValueForMICreation - format "[InputParam]* InputParam == varValue

Returns:

the work item of the new instance.

Throws:

YStateException - if the task is not able to create a new instance, due to its state or its design.

YPersistenceException - if there's a problem with the persistence session

suspendWorkItem

public YWorkItem suspendWorkItem(java.lang.String workItemID)
                          throws YStateException,
                                 YPersistenceException

Specified by:

suspendWorkItem in interface InterfaceBClient

Throws:

YStateException

YPersistenceException

unsuspendWorkItem

public YWorkItem unsuspendWorkItem(java.lang.String workItemID)
                            throws YStateException,
                                   YPersistenceException

Throws:

YStateException

YPersistenceException

rollbackWorkItem

public void rollbackWorkItem(java.lang.String workItemID)
                      throws YStateException,
                             YPersistenceException

Specified by:

rollbackWorkItem in interface InterfaceBClient

Throws:

YStateException

YPersistenceException

getChildrenOfWorkItem

public java.util.Set getChildrenOfWorkItem(YWorkItem workItem)

Specified by:

getChildrenOfWorkItem in interface InterfaceBClient

updateWorkItemData

public boolean updateWorkItemData(java.lang.String workItemID,
                                  java.lang.String data)

updates the workitem with the data passed after completion of an exception handler

cancelWorkItem

public void cancelWorkItem(YWorkItem workItem)

getRegisteredYawlService

public YAWLServiceReference getRegisteredYawlService(java.lang.String yawlServiceID)

Specified by:

getRegisteredYawlService in interface InterfaceAManagement

getYAWLServices

public java.util.Set<YAWLServiceReference> getYAWLServices()

Returns a set of YAWL services registered in the engine.

Returns:

Set of services

addYawlService

public void addYawlService(YAWLServiceReference yawlService)
                    throws YPersistenceException

Adds a YAWL service to the engine.

Specified by:

addYawlService in interface InterfaceAManagement

Parameters:

yawlService -

Throws:

YPersistenceException

removeYawlService

public YAWLServiceReference removeYawlService(java.lang.String serviceURI)
                                       throws YPersistenceException

Description copied from interface: InterfaceAManagement

Removes a YAWL service from the engine.

Specified by:

removeYawlService in interface InterfaceAManagement

Parameters:

serviceURI -

Returns:

the removed service reference

Throws:

YPersistenceException

addExternalClient

public boolean addExternalClient(YExternalClient client)
                          throws YPersistenceException

Adds an external client credentials object to the engine. An external client is an application that connects to the engine (as opposed to a service)

Specified by:

addExternalClient in interface InterfaceAManagement

Parameters:

client - the external client to add

Throws:

YPersistenceException

updateExternalClient

public boolean updateExternalClient(java.lang.String id,
                                    java.lang.String password,
                                    java.lang.String doco)
                             throws YPersistenceException

Throws:

YPersistenceException

getExternalClient

public YExternalClient getExternalClient(java.lang.String name)

Specified by:

getExternalClient in interface InterfaceAManagement

getExternalClients

public java.util.Set<YExternalClient> getExternalClients()

getUsers

public java.util.Set getUsers()

Description copied from interface: InterfaceAManagement

Returns a set of users currently loaded within the engine.

Specified by:

getUsers in interface InterfaceAManagement

removeExternalClient

public YExternalClient removeExternalClient(java.lang.String clientName)
                                     throws YPersistenceException

Throws:

YPersistenceException

setDefaultWorklist

public void setDefaultWorklist(java.lang.String paramStr)

Sets the custom service that will serve as the default worklist. Called on startup with values loaded from web.xml

Parameters:

paramStr - the URL and password of the service (separated by a hash)

Throws:

java.lang.RuntimeException - if the parameters read from web.xml are incorrectly formatted

getDefaultWorklist

public YAWLServiceReference getDefaultWorklist()

setAllowAdminID

public void setAllowAdminID(boolean allow)

isGenericAdminAllowed

public boolean isGenericAdminAllowed()

isPersisting

public static boolean isPersisting()

Indicates if persistence is enabled.

Returns:

True=Persistent, False=Not Persistent

storeObject

public void storeObject(java.lang.Object obj)
                 throws YPersistenceException

Public interface to allow engine clients to ask the engine to store an object reference in its persistent storage. It does this in its own transaction block.

Specified by:

storeObject in interface InterfaceAManagement

Parameters:

obj -

Throws:

YPersistenceException

updateObject

public void updateObject(java.lang.Object obj)
                  throws YPersistenceException

Throws:

YPersistenceException

deleteObject

public void deleteObject(java.lang.Object obj)
                  throws YPersistenceException

Throws:

YPersistenceException

clearCaseFromPersistence

protected void clearCaseFromPersistence(YIdentifier id)
                                 throws YPersistenceException

Clears a case from persistence

Parameters:

id - the case id to clear

Throws:

YPersistenceException - if there's a problem clearing the case

getPersistenceManager

public static YPersistenceManager getPersistenceManager()

addInterfaceXListener

public boolean addInterfaceXListener(java.lang.String observerURI)

sets the URI passed as an listener for exception events

removeInterfaceXListener

public boolean removeInterfaceXListener(java.lang.String uri)

removes an exception event listener

dump

public void dump()

Description copied from interface: InterfaceAManagement

Invokes a diagnostic dump of the engine's internal tables.

Specified by:

dump in interface InterfaceAManagement

setHibernateStatisticsEnabled

public void setHibernateStatisticsEnabled(boolean enabled)

isHibernateStatisticsEnabled

public boolean isHibernateStatisticsEnabled()

getHibernateStatistics

public java.lang.String getHibernateStatistics()

disableProcessLogging

public void disableProcessLogging()