de.danet.an.workflow.api
Interface WorkflowService

All Superinterfaces:

WfObject

public interface WorkflowService

extends WfObject

This interface defines the methods provided by the workflow engine.

Version:

$Revision: 1.7 $

Author:

Method Summary

WfResource	asResource(java.security.Principal principal) Given a principal, return the workflow resource associated with this principal.
java.util.Collection	authorizers(WfResource resource) Given a WfResource object, return the collection of resources this resource is authorized for.
java.security.Principal	caller() Returns the currently (i.e. for this call) authenticated user as a Principal.
Configuration	configuration() Return the workflow engine configuration.
EventSubscriber	createEventSubscriber() Returns an event subscriber.
EventSubscriber	createEventSubscriber(java.lang.String processKey, java.lang.String eventTypes) Returns an event subscriber that receives events as specified by the parameters.
void	doFinish(WfActivity act, ProcessData result) Set a result and complete an activity in a new transaction.
WfObject	eventReceiver(WfAuditHandler handler) Deprecated. since version 1.3.2. Use createEventSubscriber instead and set a handler for the object thus obtained
java.lang.Object	executeBatch(Batch batch) Execute a batch in the context of the workflow service i.e. on the server.
Channel	getChannel(WfProcess process, java.lang.String channelName) Return a named communication channel to the given process.
Channel	getChannel(WfProcess process, java.lang.String channelName, boolean sendOnly) Return a named communication channel to the given process.
java.util.Collection	knownResources() Returns at least the collection of all the workflow resources that have been assigned work items, but optionally it can return the additional workflow resources that are known to the resource assignment service.
ProcessDefinitionDirectory	processDefinitionDirectory() Return the process definition directory of the workflow service.
ProcessDirectory	processDirectory() Return the process directory of the workflow service.
void	registerRequester(WfRequester requester) Register a WfRequester.
void	release(WfObject obj) Release an object obtained from the workflow service immediately instead of waiting for it to be automatically released.
java.util.Collection	requestedBy(WfRequester req) Return the processes requested by the given requester.
WfResource	resourceByKey(java.lang.String key) Given the key of a WfResource (obtained with resourceKey()), return the workflow resource associated with this key.
java.util.Map	serviceProperties() Returns the properties that uniquely decribe the workflow service in the current environment.

Method Detail

serviceProperties

public java.util.Map serviceProperties()
                                throws java.rmi.RemoteException

Returns the properties that uniquely decribe the workflow service in the current environment.

WorkflowService does not implement Serializable because implementations of this class may have attributes that e.g. include network connections to the server and may thus not be serializable. Nevertheless it should be possible to obtain some unique reference to a workflow service and to restore this service without having to "manually" collect the (implementation dependant!) properties set for WorkflowServiceFactory before the call to newInstance.

This methods therefore returns a set of relevant properties that will restore this workflow service when set as properties of WorkflowServiceFactory in the same or an equivalent environment before newInstance is called. The properties returned by this method are, of course, based on the properties in effect when the WorkflowService was initially created.

Note the restriction "same or equivalent environment" in the previous paragraph. One of the explicitly mentioned properties of the WorkflowServiceFactory (in a J2EE based implementation) is the InitialContext used. If not set explicitly, the default initial context may be specified by something like "localhost:1099". While the properties returned by serviceProperties will include this property of the connection to the JNDI provider, using the properties in a different JVM on a different machine may result in a different workflow service (or no workflow service at all) because a different JNDI server is accessed. The impossibility to transfer all relevant information between JVM's under all circumstances (InitialContext is not serializable as may be some other crucial information in an implementation based on some other technology than J2EE) has prevented us from demanding serializability for WorkflowService. The requirement to obtain the service information explicitly and to create a new instance should result in some awareness of the problems.

Returns:

the service properties

Throws:

java.rmi.RemoteException - if a system-level error occurs

configuration

public Configuration configuration()
                            throws java.rmi.RemoteException

Return the workflow engine configuration.

Returns:

the configuration.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

processDefinitionDirectory

public ProcessDefinitionDirectory processDefinitionDirectory()
                                                      throws java.rmi.RemoteException

Return the process definition directory of the workflow service.

Returns:

the process definition directory.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

processDirectory

public ProcessDirectory processDirectory()
                                  throws java.rmi.RemoteException

Return the process directory of the workflow service.

Returns:

the process directory.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

asResource

public WfResource asResource(java.security.Principal principal)
                      throws java.rmi.RemoteException,
                             InvalidKeyException

Given a principal, return the workflow resource associated with this principal. This method is usually used to get a WfResource object corresponding to the current user. The WfResource object can subsequently be used to e.g. determine the current user's worklist.

Calls to this method are typically delegated to ResourceAssignmentService.asResource. Note that since implementation of this method by the resource assignment service is optional, calling this method may result in an UnsupportedOperationException.

Parameters:

principal - the principal.

Returns:

a WfResource object corresponding to the given principal.

Throws:

InvalidKeyException - if a resource with the given principal can't be found.

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

resourceByKey

public WfResource resourceByKey(java.lang.String key)
                         throws InvalidKeyException,
                                java.rmi.RemoteException

Given the key of a WfResource (obtained with resourceKey()), return the workflow resource associated with this key.

Calls to this method are typically delegated to ResourceAssignmentService.resourceByKey. Note that since implementation of this method by the resource assignment service is optional, calling this method may result in an UnsupportedOperationException.

Parameters:

key - the key.

Returns:

a WfResource object corresponding to the given key.

Throws:

InvalidKeyException - if the resource with the given key can't be found. As the environment is a concurrent multi user environment, WfResource objects (and keys obtained from WfResource objects) may become invalid.

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

See Also:

ResourceAssignmentService#resourceByKey

knownResources

public java.util.Collection knownResources()
                                    throws java.rmi.RemoteException

Returns at least the collection of all the workflow resources that have been assigned work items, but optionally it can return the additional workflow resources that are known to the resource assignment service. Calls to this method are typically delegated to ResourceAssignmentService.knownResources. Note that since implementation of this method by the resource assignment service is optional, calling this method may result in an UnsupportedOperationException.

Returns:

the collection of the known resources to the ras (instances of WfResource).

Throws:

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

See Also:

ResourceAssignmentService#knownResources

authorizers

public java.util.Collection authorizers(WfResource resource)
                                 throws java.rmi.RemoteException

Given a WfResource object, return the collection of resources this resource is authorized for.

This method usually returns all groups the resource is a member of and all roles assigned to the resource.

Calls to this method are typically delegated to ResourceAssignmentService.authorizers. Note that since implementation of this method by the resource assignment service is optional, calling this method may result in an UnsupportedOperationException.

Parameters:

resource - the resource.

Returns:

a collection of WfResource objects, not including resource

Throws:

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

eventReceiver

public WfObject eventReceiver(WfAuditHandler handler)
                       throws java.rmi.RemoteException

Deprecated. since version 1.3.2. Use createEventSubscriber instead and set a handler for the object thus obtained

Returns an event receiver. The events received will be handled by the given handler. Event receivers should be released using release when no longer needed as they may consume considerable resources.

Parameters:

handler - the handler for received events.

Returns:

the receiver.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

createEventSubscriber

public EventSubscriber createEventSubscriber()
                                      throws java.io.IOException

Returns an event subscriber. Event subscriber should be released using release when no longer needed as they may consume considerable resources.

Returns:

the subscriber

Throws:

java.io.IOException - if an error occurs.

createEventSubscriber

public EventSubscriber createEventSubscriber(java.lang.String processKey,
                                             java.lang.String eventTypes)
                                      throws java.io.IOException

Returns an event subscriber that receives events as specified by the parameters. Event subscriber should be released using release when no longer needed as they may consume considerable resources.

Parameters:

processKey - if not null, receive events for the given process only

eventTypes - if not null, receive events of the given types only. Types are specified as a whitespace, comma or semicolon separated list of event names. See WfAuditEvent for a list of valid event names.

Returns:

the subscriber

Throws:

java.io.IOException - if an error occurs.

registerRequester

public void registerRequester(WfRequester requester)
                       throws java.rmi.RemoteException

Register a WfRequester. Registered requesters' receiveEvent methods will be called for their performers. Note that a requester must be registered before it is used for process creation. Else events may be lost.

Parameters:

requester - the requester to be registered.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

requestedBy

public java.util.Collection requestedBy(WfRequester req)
                                 throws java.rmi.RemoteException

Return the processes requested by the given requester. This is a helper method intended to be used when implementing a WfRequester. Applications should use WfRequester.performers() instead.

Parameters:

req - the requester.

Returns:

the processes created with the given requester.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

doFinish

public void doFinish(WfActivity act,
                     ProcessData result)
              throws InvalidDataException,
                     CannotCompleteException,
                     java.rmi.RemoteException

Set a result and complete an activity in a new transaction. This is usually required to implement tools with reasonable behaviour since a failure when calling setResult or complete on an activity may not cause the tool invocation to be repeated (as would be the case when simply calling setResult or complete due to the transaction rollback associated with an exception).

As an example consider an InvalidDataException. This usually occurs when the result contains an item that is not a declared process data field. Ususally, repeating the tool invocation will not solve this problem.

Parameters:

act - the Activity.

result - the tool's result data. If null do not call setResult.

Throws:

InvalidDataException - see WfActivity.setResult(...)

CannotCompleteException - see WfActivity.complete()

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.1

release

public void release(WfObject obj)

Release an object obtained from the workflow service immediately instead of waiting for it to be automatically released. This may be called to optimize resource utilization.

We do not want to define a specific mechanism for implementing the remote invocation mechanism used with the workflow API. Therefore, we cannot demand that each object defines a method to release resources (like e.g. CORBA's release). This method knows about the implementation specifics and acts appropriately.

Parameters:

obj - the object which is no longer used.

executeBatch

public java.lang.Object executeBatch(Batch batch)
                              throws java.rmi.RemoteException,
                                     java.lang.reflect.InvocationTargetException

Execute a batch in the context of the workflow service i.e. on the server.

We do not want to define a specific mechanism for implementing the remote invocation mechanism used with the workflow API. Yet it is obvious that any implementation can profit from the possibility to execute several actions as one call to the server.

Parameters:

batch - the batch to be executed.

Returns:

the result returned by Batch.execute.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

java.lang.reflect.InvocationTargetException - if thrown by Batch.execute

getChannel

public Channel getChannel(WfProcess process,
                          java.lang.String channelName)
                   throws java.rmi.RemoteException

Return a named communication channel to the given process. The channel may be used to send messages to the receiver tool and receive messages from the sender tool.

Channels should be released when no longer needed to free resources.

Parameters:

process - the process to communicate with

channelName - the channel name

Returns:

the channel

Throws:

java.rmi.RemoteException - if a system-level error occurs.

getChannel

public Channel getChannel(WfProcess process,
                          java.lang.String channelName,
                          boolean sendOnly)
                   throws java.rmi.RemoteException

Return a named communication channel to the given process. The channel may be used to send messages to the receiver tool and optionally receive messages from the sender tool.

Channels should be released when no longer needed to free resources.

Parameters:

process - the process to communicate with

channelName - the channel name

sendOnly - if set, returns a channel that may only be used for sending messages. This may save some resources.

Returns:

the channel

Throws:

java.rmi.RemoteException - if a system-level error occurs.

caller

public java.security.Principal caller()
                               throws java.rmi.RemoteException

Returns the currently (i.e. for this call) authenticated user as a Principal.

In an environment where authentication is performed by the container, it may not be easy to discover this information. Although most container environments provide a possibility to access the current principal, there may be a mapping between the client's representation of the currently authenticated user and the workflow engine's (i.e. server's) representation.

Returns:

the caller principal.

Throws:

java.rmi.RemoteException

See Also:

asResource(java.security.Principal)