org.enhydra.shark.api.internal.toolagent
Interface ToolAgent


public interface ToolAgent

This interface is based on WfMC's definition of ToolAgents. It is pretty close to the WfMC's specification, but expressed in Object oriented way.

The following is different then WfMC spec proposes:

Also, when calling invokeApplication() method, as the first AppParameter parameter in array, Shark is always passing a string representing ExtendedAttributes section of the corresponding XPDL application, chopped out from the XPDL definition, i.e.:

 <ExtendedAttributes>
    <ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/>
    <ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/>
 </ExtendedAttributes>
 

Shark uses tool agents like the following:

Author:
Sasa Bojanic, Vladimir Puskas

Field Summary
static long APP_STATUS_ACTIVE
           
static long APP_STATUS_FINISHED
           
static long APP_STATUS_INVALID
           
static long APP_STATUS_RUNNING
           
static long APP_STATUS_TERMINATED
           
static long APP_STATUS_WAITING
           
 
Method Summary
 void configure(CallbackUtilities cus)
          Used to configure tool agent if needed.
 WMSessionHandle connect(WMConnectInfo wmci)
          This is the first method that shark calls when accessing some tool agent.
 void disconnect(WMSessionHandle shandle)
          Method disconnect.
 java.lang.String getInfo(WMSessionHandle shandle)
          Method getInfo.
 void invokeApplication(WMSessionHandle shandle, long handle, WMEntity appInfo, WMEntity toolInfo, java.lang.String applicationName, java.lang.String processInstanceId, java.lang.String workitemId, AppParameter[] parameters, java.lang.Integer applicationMode)
          Executes tool agent application.
 long requestAppStatus(WMSessionHandle shandle, long handle, WMEntity toolInfo, java.lang.String processInstanceId, java.lang.String workitemId, AppParameter[] parameters)
          Returns the status of tool agent application execution, and fills the parameters with the results of tool agent application execution.
 void terminateApp(WMSessionHandle shandle, long handle, WMEntity toolInfo, java.lang.String processInstanceId, java.lang.String workitemId)
          Terminates tool agent application.
 

Field Detail

APP_STATUS_INVALID

public static final long APP_STATUS_INVALID
See Also:
Constant Field Values

APP_STATUS_RUNNING

public static final long APP_STATUS_RUNNING
See Also:
Constant Field Values

APP_STATUS_ACTIVE

public static final long APP_STATUS_ACTIVE
See Also:
Constant Field Values

APP_STATUS_WAITING

public static final long APP_STATUS_WAITING
See Also:
Constant Field Values

APP_STATUS_TERMINATED

public static final long APP_STATUS_TERMINATED
See Also:
Constant Field Values

APP_STATUS_FINISHED

public static final long APP_STATUS_FINISHED
See Also:
Constant Field Values
Method Detail

configure

public void configure(CallbackUtilities cus)
               throws java.lang.Exception
Used to configure tool agent if needed.

Throws:
java.lang.Exception

connect

public WMSessionHandle connect(WMConnectInfo wmci)
                        throws ConnectFailed,
                               ToolAgentGeneralException
This is the first method that shark calls when accessing some tool agent.

Parameters:
wmci - structure holding connection request data
Returns:
a SessionHandle.
Throws:
ConnectFailed - If application executed by tool agent needs authentication, and userId and/or password are not valid
ToolAgentGeneralException - If something unexpected happens.

disconnect

public void disconnect(WMSessionHandle shandle)
                throws InvalidSessionHandle,
                       ToolAgentGeneralException
Method disconnect.

Parameters:
shandle - a SessionHandle.
Throws:
InvalidSessionHandle - If the given session handle is not valid.
ToolAgentGeneralException - If something unexpected happens.

invokeApplication

public void invokeApplication(WMSessionHandle shandle,
                              long handle,
                              WMEntity appInfo,
                              WMEntity toolInfo,
                              java.lang.String applicationName,
                              java.lang.String processInstanceId,
                              java.lang.String workitemId,
                              AppParameter[] parameters,
                              java.lang.Integer applicationMode)
                       throws ApplicationNotStarted,
                              ApplicationNotDefined,
                              ApplicationBusy,
                              ToolAgentGeneralException
Executes tool agent application.

Parameters:
handle - a long representing unique session Id.
applicationName - the name of application which will be executed by this tool agent
processInstanceId - Id of process instance for which tool agent application is called.
workitemId - Id of assignment that is associated with invoked application.
parameters - array of parameters (engine variables) passed to tool agent application. Some of these parameters will be changed during application execution. These parameters should be considered the input ones - the engine will not read there value after this method is finished, but it will give to the requestAppStatus(org.enhydra.shark.api.client.wfmc.wapi.WMSessionHandle, long, org.enhydra.shark.api.client.wfservice.WMEntity, java.lang.String, java.lang.String, org.enhydra.shark.api.internal.toolagent.AppParameter[]) method the array of parameters to be filled with the result of tool agent application execution.

The value field of the first parameter in the parameter array is always a string representing ExtendedAttributes section of the corresponding XPDL application, chopped out from the XPDL definition, i.e.:

 <ExtendedAttributes>
    <ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/>
    <ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/>
 </ExtendedAttributes>
 
applicationMode - an Integer representing application mode.
Throws:
ApplicationNotStarted - If application can't be started.
ApplicationNotDefined - If there is no such application.
ApplicationBusy - If application is bussy.
ToolAgentGeneralException - If something unexpected happens.

requestAppStatus

public long requestAppStatus(WMSessionHandle shandle,
                             long handle,
                             WMEntity toolInfo,
                             java.lang.String processInstanceId,
                             java.lang.String workitemId,
                             AppParameter[] parameters)
                      throws ApplicationBusy,
                             InvalidToolAgentHandle,
                             InvalidWorkitem,
                             InvalidProcessInstance,
                             ToolAgentGeneralException
Returns the status of tool agent application execution, and fills the parameters with the results of tool agent application execution.

Parameters:
handle - a long representing unique session Id.
processInstanceId - Id of process instance for which tool agent application is called.
workitemId - Id of assignment that is associated with invoked application.
parameters - array of parameters (engine variables) passed to application. This is a subset of parameters passed to the invokeApplication() method, and these parameters need to be filled with the result of tool agent's application execution.
Returns:
The status of tool agent application.
Throws:
ApplicationBusy - If application is bussy.
InvalidToolAgentHandle - If handle is invalid.
InvalidWorkitem - If there is no such workitem as the one represented by given Id parameters.
InvalidProcessInstance - If there is no process instance with given Id.
ToolAgentGeneralException - If something unexpected happens.

terminateApp

public void terminateApp(WMSessionHandle shandle,
                         long handle,
                         WMEntity toolInfo,
                         java.lang.String processInstanceId,
                         java.lang.String workitemId)
                  throws ApplicationNotStopped,
                         InvalidWorkitem,
                         InvalidProcessInstance,
                         ApplicationBusy,
                         ToolAgentGeneralException
Terminates tool agent application.

Parameters:
handle - long representing unique session Id.
processInstanceId - Id of process instance for which tool agent application is called.
workitemId - Id of assignment that is associated with invoked application.
Throws:
ApplicationNotStopped - If application can't be stopped.
InvalidWorkitem - If there is no such workitem as the one represented by given Id parameters.
InvalidProcessInstance - If there is no process instance with given Id.
ApplicationBusy - If application is bussy.
ToolAgentGeneralException - If something unexpected happens.

getInfo

public java.lang.String getInfo(WMSessionHandle shandle)
                         throws ToolAgentGeneralException
Method getInfo.

Returns:
a String representing brief description on tool agent use.
Throws:
ToolAgentGeneralException