KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > enhydra > shark > api > internal > toolagent > ToolAgent


1 package org.enhydra.shark.api.internal.toolagent;
2
3
4 import org.enhydra.shark.api.*;
5 import org.enhydra.shark.api.internal.working.CallbackUtilities;
6
7 /**
8  * This interface is based on WfMC's definition of ToolAgents. It is pretty
9  * close to the WfMC's specification, but expressed in Object oriented way.
10  * <p>The following is different then WfMC spec proposes:
11  * <ul>
12  * <li> Every method is throwing additional {@link ToolAgentGeneralException}
13  * <li> Every method has an additional SharkTransaction parameter, which
14  * represents the shark's current transaction, and provides a way for tool
15  * agents to access the same database as shark does by using shark's current
16  * transaction.
17  * <li> {@link AppParameter} class is different then WfMC's WMTPAttribute type -
18  * it defines some additional fields.
19  * <li> It has additional configure() method, that is used to pass
20  * {@link CallbackUtilities} to tool agent, which provides ToolAgent to get
21  * some configuration information from Shark, and provides a way to log tool
22  * agent events.
23  * <li> It has additional getInfo() method, that is used to get some information
24  * about tool agent.
25  * </ul>
26  * <p> Also, when calling invokeApplication() method, as the first {@link AppParameter}
27  * parameter in array, Shark is always passing a string representing
28  * ExtendedAttributes section of the corresponding XPDL application, chopped
29  * out from the XPDL definition, i.e.:
30  * <pre>
31  * &lt;ExtendedAttributes&gt;
32  * &lt;ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/&gt;
33  * &lt;ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/&gt;
34  * &lt;/ExtendedAttributes&gt;
35  * </pre>
36  * <p> Shark uses tool agents like the following:
37  * <ul>
38  * <li> It aquires ToolAgent instance from {@link ToolAgentFactory}. When it
39  * creates ToolAgent instance, {@link ToolAgentFactory} implementation has to
40  * call ToolAgent's configure() method.
41  * <li> It calls connect() method, and gets handle to ToolAgent
42  * <li> It calls invokeApplication() method (the {@link AppParameter} array
43  * passed to this method should be considered to be passed as a value, not as
44  * a reference, because Shark doesn't care about it after calling this method).
45  * <li> It calls requestAppStatus() method. Tool agent implementation
46  * has to fill the {@link AppParameter} array that Shark passes to this method,
47  * with the values of appropriate parameters (These parameters are the one
48  * passed in invokeApplication() method call, that could be changed
49  * during tool agent execution). It also expects the information on application
50  * status to be returned, and in our standard implementation, if the status is
51  * equal to -1, shark throws exception (Of course, ToolAgent can also signal an
52  * exception to shark by throwing any of defined exceptions for a method).
53  * <li> finally, shark calls disconnect().
54  * </ul>
55  *
56  * @author Sasa Bojanic
57  * @author Vladimir Puskas
58  */
59 public interface ToolAgent {
60    /**
61     * Used to configure tool agent if needed.
62     */
63    void configure (CallbackUtilities cus) throws RootException;
64
65    /**
66     * This is the first method that shark calls when accessing some tool agent.
67     *
68     * @param t Current shark transaction.
69     * @param userId Applications executed by toolagent might
70     * require login procedures, therefore authentication should be passed to
71     * a Tool Agent to provide single-login mechanisms.
72     * @param password Applications executed by toolagent might
73     * require login procedures, therefore authentication should be passed to
74     * a Tool Agent to provide single-login mechanisms.
75     * @param engineName The name of shark instance that connects to
76     * Tool agent.
77     * @param scope Identification of scope for the application.
78     * If scope is not relevant, then this field would be empty and ignored.
79     *
80     * @return a SessionHandle.
81     *
82     * @throws ConnectFailed If application executed by tool agent needs
83     * authentication, and userId and/or password are not valid
84     * @throws ToolAgentGeneralException If something unexpected happens.
85     *
86     */
87    SessionHandle connect (SharkTransaction t,
88                           String JavaDoc userId,
89                           String JavaDoc password,
90                           String JavaDoc engineName,
91                           String JavaDoc scope)
92       throws ConnectFailed, ToolAgentGeneralException;
93
94    /**
95     * Method disconnect.
96     *
97     * @param t Current shark transaction.
98     * @param shandle a SessionHandle.
99     *
100     * @throws InvalidSessionHandle If the given session handle is not valid.
101     * @throws ToolAgentGeneralException If something unexpected happens.
102     *
103     */
104    void disconnect (SharkTransaction t,SessionHandle shandle)
105       throws InvalidSessionHandle, ToolAgentGeneralException;
106
107    /**
108     * Executes tool agent application.
109     *
110     * @param t Current shark transaction.
111     * @param handle a long representing unique session Id.
112     * @param applicationName the name of application which will be
113     * executed by this tool agent
114     * @param processInstanceId Id of process instance for which tool
115     * agent application is called.
116     * @param workitemId Id of assignment that is associated with
117     * invoked application.
118     * @param parameters array of parameters (engine variables)
119     * passed to tool agent application. Some of these parameters will be changed
120     * during application execution. These parameters should be considered the
121     * input ones - the engine will not read there value after this method is
122     * finished, but it will give to the {@link #requestAppStatus} method
123     * the array of parameters to be filled with the result of tool agent
124     * application execution.
125     * <p> The value field of the first parameter in the parameter array
126     * is always a string representing ExtendedAttributes section of the
127     * corresponding XPDL application, chopped out from the XPDL definition, i.e.:
128     * <pre>
129     * &lt;ExtendedAttributes&gt;
130     * &lt;ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/&gt;
131     * &lt;ExtendedAttribute Name="Script" Value="java.lang.Thread.sleep(wait_ms);"/&gt;
132     * &lt;/ExtendedAttributes&gt;
133     * </pre>
134     * @param applicationMode an Integer representing application mode.
135     *
136     * @throws ApplicationNotStarted If application can't be started.
137     * @throws ApplicationNotDefined If there is no such application.
138     * @throws ApplicationBusy If application is bussy.
139     * @throws ToolAgentGeneralException If something unexpected happens.
140     *
141     */
142    void invokeApplication (SharkTransaction t,
143                            long handle,
144                            String JavaDoc applicationName,
145                            String JavaDoc processInstanceId,
146                            String JavaDoc workitemId,
147                            AppParameter[] parameters,
148                            Integer JavaDoc applicationMode)
149       throws ApplicationNotStarted, ApplicationNotDefined,
150       ApplicationBusy, ToolAgentGeneralException;
151
152    /**
153     * Returns the status of tool agent application execution, and fills
154     * the parameters with the results of tool agent application execution.
155     *
156     * @param t Current shark transaction.
157     * @param handle a long representing unique session Id.
158     * @param processInstanceId Id of process instance for which tool
159     * agent application is called.
160     * @param workitemId Id of assignment that is associated with
161     * invoked application.
162     * @param parameters array of parameters (engine variables)
163     * passed to application. This is a subset of parameters passed to the
164     * invokeApplication() method, and these parameters need to be filled with
165     * the result of tool agent's application execution.
166     *
167     * @return The status of tool agent application.
168     *
169     * @throws ApplicationBusy If application is bussy.
170     * @throws InvalidToolAgentHandle If handle is invalid.
171     * @throws InvalidWorkitem If there is no such workitem as the one
172     * represented by given Id parameters.
173     * @throws InvalidProcessInstance If there is no process instance with
174     * given Id.
175     * @throws ToolAgentGeneralException If something unexpected happens.
176     *
177     */
178    long requestAppStatus (SharkTransaction t,
179                           long handle,
180                           String JavaDoc processInstanceId,
181                           String JavaDoc workitemId,
182                           AppParameter[] parameters)
183       throws ApplicationBusy, InvalidToolAgentHandle, InvalidWorkitem,
184       InvalidProcessInstance, ToolAgentGeneralException;
185
186    /**
187     * Terminates tool agent application.
188     *
189     * @param t Current shark transaction.
190     * @param handle long representing unique session Id.
191     * @param processInstanceId Id of process instance for which tool
192     * agent application is called.
193     * @param workitemId Id of assignment that is associated with
194     * invoked application.
195     *
196     * @throws ApplicationNotStopped If application can't be stopped.
197     * @throws InvalidWorkitem If there is no such workitem as the one
198     * represented by given Id parameters.
199     * @throws InvalidProcessInstance If there is no process instance with
200     * given Id.
201     * @throws ApplicationBusy If application is bussy.
202     * @throws ToolAgentGeneralException If something unexpected happens.
203     *
204     */
205    void terminateApp (SharkTransaction t,
206                       long handle,
207                       String JavaDoc processInstanceId,
208                       String JavaDoc workitemId)
209       throws ApplicationNotStopped, InvalidWorkitem,
210       InvalidProcessInstance, ApplicationBusy, ToolAgentGeneralException;
211
212
213    /**
214     * Method getInfo.
215     *
216     * @param t a SharkTransaction
217     *
218     * @return a String representing brief description on tool agent use.
219     *
220     * @throws ToolAgentGeneralException
221     *
222     */
223    String JavaDoc getInfo (SharkTransaction t) throws ToolAgentGeneralException;
224
225 }
226
Popular Tags