001: package org.enhydra.shark.api.internal.toolagent;
002:
003: import org.enhydra.shark.api.client.wfmc.wapi.WMConnectInfo;
004: import org.enhydra.shark.api.client.wfmc.wapi.WMSessionHandle;
005: import org.enhydra.shark.api.client.wfservice.WMEntity;
006: import org.enhydra.shark.api.internal.working.CallbackUtilities;
007:
008: /**
009: * This interface is based on WfMC's definition of ToolAgents. It is pretty
010: * close to the WfMC's specification, but expressed in Object oriented way.
011: * <p>The following is different then WfMC spec proposes:
012: * <ul>
013: * <li> Every method is throwing additional {@link ToolAgentGeneralException}
014: * <li> {@link AppParameter} class is different then WfMC's WMTPAttribute type -
015: * it defines some additional fields.
016: * <li> It has additional configure() method, that is used to pass
017: * {@link CallbackUtilities} to tool agent, which provides ToolAgent to get
018: * some configuration information from Shark, and provides a way to log tool
019: * agent events.
020: * <li> It has additional getInfo() method, that is used to get some information
021: * about tool agent.
022: * </ul>
023: * <p> Also, when calling invokeApplication() method, as the first {@link AppParameter}
024: * parameter in array, Shark is always passing a string representing
025: * ExtendedAttributes section of the corresponding XPDL application, chopped
026: * out from the XPDL definition, i.e.:
027: * <pre>
028: * <ExtendedAttributes>
029: * <ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/>
030: * <ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/>
031: * </ExtendedAttributes>
032: * </pre>
033: * <p> Shark uses tool agents like the following:
034: * <ul>
035: * <li> It aquires ToolAgent instance from {@link ToolAgentManager}. When it
036: * creates ToolAgent instance, {@link ToolAgentManager} implementation has to
037: * call ToolAgent's configure() method.
038: * <li> It calls connect() method, and gets handle to ToolAgent
039: * <li> It calls invokeApplication() method (the {@link AppParameter} array
040: * passed to this method should be considered to be passed as a value, not as
041: * a reference, because Shark doesn't care about it after calling this method).
042: * <li> It calls requestAppStatus() method. Tool agent implementation
043: * has to fill the {@link AppParameter} array that Shark passes to this method,
044: * with the values of appropriate parameters (These parameters are the one
045: * passed in invokeApplication() method call, that could be changed
046: * during tool agent execution). It also expects the information on application
047: * status to be returned, and in our standard implementation, if the status is
048: * equal to -1, shark throws exception (Of course, ToolAgent can also signal an
049: * exception to shark by throwing any of defined exceptions for a method).
050: * <li> finally, shark calls disconnect().
051: * </ul>
052: *
053: * @author Sasa Bojanic
054: * @author Vladimir Puskas
055: */
056: public interface ToolAgent {
057: public static final long APP_STATUS_INVALID = -1;
058: public static final long APP_STATUS_RUNNING = 0;
059: public static final long APP_STATUS_ACTIVE = 1;
060: public static final long APP_STATUS_WAITING = 2;
061: public static final long APP_STATUS_TERMINATED = 3;
062: public static final long APP_STATUS_FINISHED = 4;
063:
064: /**
065: * Used to configure tool agent if needed.
066: */
067: void configure(CallbackUtilities cus) throws Exception;
068:
069: /**
070: * This is the first method that shark calls when accessing some tool agent.
071: *
072: * @param wmci structure holding connection request data
073: *
074: * @return a SessionHandle.
075: *
076: * @throws ConnectFailed If application executed by tool agent needs
077: * authentication, and userId and/or password are not valid
078: * @throws ToolAgentGeneralException If something unexpected happens.
079: *
080: */
081: WMSessionHandle connect(WMConnectInfo wmci) throws ConnectFailed,
082: ToolAgentGeneralException;
083:
084: /**
085: * Method disconnect.
086: *
087: * @param shandle a SessionHandle.
088: *
089: * @throws InvalidSessionHandle If the given session handle is not valid.
090: * @throws ToolAgentGeneralException If something unexpected happens.
091: *
092: */
093: void disconnect(WMSessionHandle shandle)
094: throws InvalidSessionHandle, ToolAgentGeneralException;
095:
096: /**
097: * Executes tool agent application.
098: *
099: * @param handle a long representing unique session Id.
100: * @param applicationName the name of application which will be
101: * executed by this tool agent
102: * @param processInstanceId Id of process instance for which tool
103: * agent application is called.
104: * @param workitemId Id of assignment that is associated with
105: * invoked application.
106: * @param parameters array of parameters (engine variables)
107: * passed to tool agent application. Some of these parameters will be changed
108: * during application execution. These parameters should be considered the
109: * input ones - the engine will not read there value after this method is
110: * finished, but it will give to the {@link #requestAppStatus} method
111: * the array of parameters to be filled with the result of tool agent
112: * application execution.
113: * <p> The value field of the first parameter in the parameter array
114: * is always a string representing ExtendedAttributes section of the
115: * corresponding XPDL application, chopped out from the XPDL definition, i.e.:
116: * <pre>
117: * <ExtendedAttributes>
118: * <ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/>
119: * <ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/>
120: * </ExtendedAttributes>
121: * </pre>
122: * @param applicationMode an Integer representing application mode.
123: *
124: * @throws ApplicationNotStarted If application can't be started.
125: * @throws ApplicationNotDefined If there is no such application.
126: * @throws ApplicationBusy If application is bussy.
127: * @throws ToolAgentGeneralException If something unexpected happens.
128: *
129: */
130: void invokeApplication(WMSessionHandle shandle, long handle,
131: WMEntity appInfo, WMEntity toolInfo,
132: String applicationName, String processInstanceId,
133: String workitemId, AppParameter[] parameters,
134: Integer applicationMode) throws ApplicationNotStarted,
135: ApplicationNotDefined, ApplicationBusy,
136: ToolAgentGeneralException;
137:
138: /**
139: * Returns the status of tool agent application execution, and fills
140: * the parameters with the results of tool agent application execution.
141: *
142: * @param handle a long representing unique session Id.
143: * @param processInstanceId Id of process instance for which tool
144: * agent application is called.
145: * @param workitemId Id of assignment that is associated with
146: * invoked application.
147: * @param parameters array of parameters (engine variables)
148: * passed to application. This is a subset of parameters passed to the
149: * invokeApplication() method, and these parameters need to be filled with
150: * the result of tool agent's application execution.
151: *
152: * @return The status of tool agent application.
153: *
154: * @throws ApplicationBusy If application is bussy.
155: * @throws InvalidToolAgentHandle If handle is invalid.
156: * @throws InvalidWorkitem If there is no such workitem as the one
157: * represented by given Id parameters.
158: * @throws InvalidProcessInstance If there is no process instance with
159: * given Id.
160: * @throws ToolAgentGeneralException If something unexpected happens.
161: *
162: */
163: long requestAppStatus(WMSessionHandle shandle, long handle,
164: WMEntity toolInfo, String processInstanceId,
165: String workitemId, AppParameter[] parameters)
166: throws ApplicationBusy, InvalidToolAgentHandle,
167: InvalidWorkitem, InvalidProcessInstance,
168: ToolAgentGeneralException;
169:
170: /**
171: * Terminates tool agent application.
172: *
173: * @param handle long representing unique session Id.
174: * @param processInstanceId Id of process instance for which tool
175: * agent application is called.
176: * @param workitemId Id of assignment that is associated with
177: * invoked application.
178: *
179: * @throws ApplicationNotStopped If application can't be stopped.
180: * @throws InvalidWorkitem If there is no such workitem as the one
181: * represented by given Id parameters.
182: * @throws InvalidProcessInstance If there is no process instance with
183: * given Id.
184: * @throws ApplicationBusy If application is bussy.
185: * @throws ToolAgentGeneralException If something unexpected happens.
186: *
187: */
188: void terminateApp(WMSessionHandle shandle, long handle,
189: WMEntity toolInfo, String processInstanceId,
190: String workitemId) throws ApplicationNotStopped,
191: InvalidWorkitem, InvalidProcessInstance, ApplicationBusy,
192: ToolAgentGeneralException;
193:
194: /**
195: * Method getInfo.
196: *
197: * @return a String representing brief description on tool agent use.
198: *
199: * @throws ToolAgentGeneralException
200: *
201: */
202: String getInfo(WMSessionHandle shandle)
203: throws ToolAgentGeneralException;
204:
205: }
|