de.danet.an.workflow.spis.aii
Interface ToolAgent

All Known Implementing Classes:

SimpleApplicationAgent

public interface ToolAgent

This interface is used to control applications that execute work items. An application may implement this interface directly (it is "workflow aware"). Usually, however, this interface will be implemented by some adapter class that controls the application, and thus acts as an agent for the application.

An application is declared to participate in a workflow by the application tag in the XPDL. This declaration is associated with the implementation class of ToolAgent using an extension. The extension syntax supported allows to specify properties of the tool agent (see the User Manual for details).

An implementation of ToolAgent must be aware that several application invocations may be performed using the same instance of the class implementing ToolAgent. This implies that implementations must be thread-safe.

By default, the invoke method has full access to the activity as specified by the activity interface. Implementations that require long term storage of the activity must be aware that the activity is passed as an interface to a remote object and therefore unsuitable for long term persistence. Tool agents should persist the activity's unique key instead of the activity. The activity may later be retrieved from the key using ProcessDirectory.lookupActivity (obtaining the process directory from the WorkflowService.

See Also:

de.danet.an.workflow.spis.aii

Method Summary

void	invoke(Activity activity, FormalParameter[] formalParameters, java.util.Map actualParameters) Invoke an application on the given activity.
void	terminate(Activity activity) Terminates execution of the given activity.

Method Detail

invoke

public void invoke(Activity activity,
                   FormalParameter[] formalParameters,
                   java.util.Map actualParameters)
            throws java.rmi.RemoteException,
                   CannotExecuteException

Invoke an application on the given activity.

Parameters:

activity - the activity to be executed. The supplied object must be serializable in order to support applications running as servers

formalParameters - the formal parameter definition as specified in the process definition. May be used e.g. by generic applications to adapt to specific formal parameter lists

actualParameters - the actual parameters of the application invocation. There is an entry in the map for every formal parameter using the id as key in the map. OUT parameters are initialized to zero. The map and the objects contained in the map must be serializable in order to support applications running as servers.

Throws:

java.rmi.RemoteException - if a temporary problem occurs and the workflow engine should retry the tool invocation (usually thrown when a deadlock situation occurs while accessing the activity).

CannotExecuteException - if thrown, causes the activity to be terminated unless a mapping to a process exception is defined for the cause of the CannotExecuteException. If such a mapping is defined, the activity is abandoned. See the user manual for details.

terminate

public void terminate(Activity activity)
               throws ApplicationNotStoppedException,
                      java.rmi.RemoteException

Terminates execution of the given activity. If the activity has been terminated already, the method should do nothing (i.e. under certain conditions this method may be called more than once for a given activity).

Only the activity's methods key and uniqueKey should be used in an implementation of this method. Else, depending on the application server and database configuration, deadlocks may occur.

Up to version 1.3 this method has been called by the workflow engine when processing an invoked tool's call of WfActivity.complete(). The reasoning has been that the engine cannot be sure that complete() is called by the tool that has previously been invoked. (To ensure this, the engine would have to pass some token to the tool during invocation and the tool would have to pass this back to the engine when calling complete(). Such a procedure is, however, not defined by the OMG API.) By invoking terminate() on the currently running tool when processing complete(), the engine tried to make sure that at least the invoked tool is terminated if some imposter calls complete() instead of the invoked tool.

The overlapping of the tool processing the completion and the invocation of terminate() on the tool has, however, turned out to cause various problems with respect to transactions if the tool uses a database. Therefore, this procedure has been abandoned. Note that this change does not formally change the API as there has never been a contract about terminate() being called as part of processing complete(). The subject has been explained extensively only to provide an explanation if someone observes this change of behaviour.

Parameters:

activity - the activity to be canceled. The supplied object must be serializable in order to support applications running as servers.

Throws:

ApplicationNotStoppedException - if execution cannot be terminated (see ApplicationNotStoppedException).

java.rmi.RemoteException - if a temporary problem occurs and the workflow engine should retry the tool termination