1 /*
2 * Copyright 2010 Fraunhofer Gesellschaft, Munich, Germany,
3 * for its Fraunhofer Institute for Computer Architecture and Software
4 * Technology (FIRST), Berlin, Germany. All rights reserved.
5 * http://www.first.fraunhofer.de/
6 */
7
8 package net.kwfgrid.gwes;
9
10 import net.kwfgrid.gwes.exception.*;
11 import net.kwfgrid.gworkflowdl.structure.WorkflowFormatException;
12
13 import java.rmi.RemoteException;
14
15 /**
16 * This is the public Interface to the Generic Workflow Execution Service (GWES). This Interface is implemented
17 * by the <CODE>GWESEngine</CODE>
18 *
19 * @author Andreas Hoheisel
20 * (<a href="http://www.andreas-hoheisel.de">www.andreas-hoheisel.de</a>)
21 * @version $Id: GWES.java 1537 2011-07-27 15:34:04Z hoheisel $
22 * @see GWESEngine
23 */
24 public interface GWES extends java.rmi.Remote {
25
26 /**
27 * Initiates a workflow with a certain userID.
28 *
29 * @param gworkflowdl The description of the workflow.
30 * @param userID userID|credential: The ID of the user who owns the workflow. Use the DN of the
31 * certificate if available. The optional user credential is separated from userID by "|".
32 * user ID MUST NOT contain "|" or spaces!
33 * @return The unique workflow ID.
34 */
35 String initiate(String gworkflowdl, String userID) throws WorkflowFormatException, WorkflowSecurityException, StateTransitionException, LoggingException, GWESException, RemoteException;
36
37 /**
38 * Start a workflow with a certain identifier.
39 *
40 * @param workflowID The unique workflow identifier.
41 * @param userID
42 */
43 void start(String workflowID, String userID) throws NoSuchWorkflowException, StateTransitionException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
44
45 /**
46 * Suspend a workflow with a certain identifier.
47 * This method returns after the workflow has been fully suspended. This may need some time.
48 *
49 * @param workflowID The unique workflow identifier.
50 * @param userID
51 */
52 void suspend(String workflowID, String userID) throws NoSuchWorkflowException, StateTransitionException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
53
54 /**
55 * Resume a workflow with a certain identifier.
56 *
57 * @param workflowID The unique workflow identifier.
58 * @param userID
59 */
60 void resume(String workflowID, String userID) throws NoSuchWorkflowException, StateTransitionException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
61
62 /**
63 * Abort a workflow with a certain identifier.
64 *
65 * @param workflowID The unique workflow identifier.
66 * @param userID
67 */
68 void abort(String workflowID, String userID) throws NoSuchWorkflowException, StateTransitionException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
69
70 /**
71 * Restart a workflow with a certain identifier from the beginning. The restarted workflow will have a new ID.
72 * This method looks for the earliest snapshot of the workflow in the database. Then the GWES initiates
73 * the workflow.
74 *
75 * @param workflowID The unique identifier of the workflow to restart.
76 * @param userID The user identifier of the user who owns the workflow.
77 * @return The new workflowID.
78 * @throws NoSuchWorkflowException If the workflow identifier is not available in the workflow database
79 * @throws WorkflowFormatException If the workflow stored in the database has the wrong format
80 * @throws DatabaseException If there is a problem with retrieving the workflow from the database
81 * @throws StateTransitionException If the state of the workflow is not INITIATED at the beginning.
82 */
83 String restart(String workflowID, String userID) throws NoSuchWorkflowException, WorkflowFormatException, WorkflowSecurityException, DatabaseException, StateTransitionException, LoggingException, GWESException, RemoteException;
84
85 /**
86 * Get the current Generic Workflow Description document of the workflow specified by its identifier.
87 *
88 * @param workflowID The unique workflow identifier.
89 * @param userID
90 * @return The current workflow description as String.
91 */
92 String getWorkflowDescription(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
93
94 /**
95 * Overwrite the current Generic Workflow Description document of the workflow specified by its identifier.
96 * The status of the workflow should be SUSPENDED or INITIATED.
97 *
98 * @param workflowID The unique workflow identifier.
99 * @param gworkflowdl The GWorkflowDL description of the workflow.
100 * @param userID
101 */
102 void setWorkflowDescription(String workflowID, String gworkflowdl, String userID) throws NoSuchWorkflowException, StateTransitionException, WorkflowFormatException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
103
104 /**
105 * Get the current status code of the workflow specified by its identifier.
106 * Valid codes are:
107 * <code>
108 * <li>STATUS_UNDEFINED = 0
109 * <li>STATUS_INITIATED = 1
110 * <li>STATUS_RUNNING = 2
111 * <li>STATUS_SUSPENDED = 3
112 * <li>STATUS_ACTIVE = 4
113 * <li>STATUS_TERMINATED = 5
114 * <li>STATUS_COMPLETED = 6
115 * </code>
116 *
117 * @param workflowID The unique workflow identifier.
118 * @param userID
119 * @return The current state of the workflow.
120 */
121 int getStatus(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
122
123 /**
124 * Wait for workflow to change its status from an specified status.
125 * @param workflowID The workflow identifier
126 * @param oldStatus The old status of the workflow
127 * @param userID
128 * @return the new status
129 */
130 public int waitForStatusChangeFrom(String workflowID, int oldStatus, String userID) throws NoSuchWorkflowException, InterruptedException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
131
132
133 /**
134 * Wait for workflow to change its status to final states COMPLETED or TERMINATED.
135 * @param workflowID The workflow identifier
136 * @param userID
137 * @return the new status
138 */
139 public int waitForStatusChangeToCompletedOrTerminated(String workflowID, String userID) throws NoSuchWorkflowException, InterruptedException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
140
141 /**
142 * Get the identifiers of all the workflows that are handled by this Generic Workflow Execution Service.
143 * The level denotes from where to get the workflow IDs:
144 * <code>
145 * <li><b>level = 1: workflows handled in main memory</b>
146 * <li><b>level = 2: workflows stored in workflow database</b>
147 * <li>level = 3: workflows handled in main memory AND stored in workflow database
148 * </code>
149 *
150 * @param level The level from where to get the workflowIDs.
151 * @param userID
152 * @return An array of strings with the workflowIDs.
153 */
154 String[] getWorkflowIDs(int level, String userID) throws DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
155
156 /**
157 * Get the workflow status of all currently available workflows.
158 * Example for each workflow:
159 * <pre>
160 * "ID=hoheisel_f2968050-1d6a-11db-bacc-ad353bc1f9b1"
161 * "status=COMPLETED"
162 * "birthdayMs=1154003111126"
163 * "durationUndefinedMs=527"
164 * "durationInitiatedMs=792"
165 * "durationRunningMs=0"
166 * "durationActiveMs=0"
167 * "durationSuspendedMs=0"
168 * "durationTotalMs=1351"
169 * "endTimeMs=1154003112477"
170 * "level=MEMORY"
171 * "description=test workflow"
172 * </pre>
173 * <p/>
174 * The level denotes from where to get the workflow IDs:
175 * <code>
176 * <li><b>level = 1: workflows handled in main memory</b>
177 * <li><b>level = 2: workflows stored in workflow database</b>
178 * <li>level = 3: workflows handled in main memory AND stored in workflow database
179 * </code>
180 *
181 * @param level The level from where to get the workflowIDs.
182 * @param userID
183 * @return The current workflow status as an array of string arrays
184 */
185 String[][] getWorkflowStatusArray(int level, String userID) throws DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
186
187 /**
188 * Store a workflow in the XML workflow database.
189 * If the workflow is running or active, then the GWES first suspends the workflow, second it stores the
190 * workflow description in the database, and third it resumes the workflow.
191 * The workflow can be restored using the <code>restore</code> method.
192 *
193 * @param workflowID The unique workflow identifier.
194 * @param userID
195 * @return An identifier within the XML database where the workflow is stored
196 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
197 * @throws DatabaseException If there is a problem with the XML database
198 * @see #restore(String,String)
199 */
200 String store(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
201
202 /**
203 * Restores a workflow from the XML database.
204 * If the input is the clean workflowID (without version number), then the GWES will restore the latest available
205 * workflow snapshot.
206 * If the workflowID string contains the whole XML database collection identifier, then the GWES will
207 * restore the given workflow (e.g. <code>/db/gworkflowdl/[workflowID]/0000000221.xml</code>. The method call
208 * returns the new workflow ID of the restored workflow.
209 * <p>A restored workflow has the status INITIATED and needs to be started using the start() method.</p>
210 * <p>Workflows are stored, e.g., by using the <code>store</code> method.</p>
211 *
212 * @param workflowID The old workflow ID of the stored workflow.
213 * @param userID The user ID.
214 * @return The new workflow ID of the restored workflow.
215 * @throws NoSuchWorkflowException
216 * @throws WorkflowFormatException
217 * @see #store(String, String)
218 * @see #start(String, String)
219 */
220 String restore(String workflowID, String userID) throws NoSuchWorkflowException, WorkflowFormatException, WorkflowSecurityException, DatabaseException, StateTransitionException, LoggingException, GWESException, RemoteException;
221
222 /**
223 * Get some data that is hold inside a specific workflow and that is referenced by a data place identifier.
224 * The format of the place identifier may differ depending on the implementation of the workflow handler.
225 * An other alternative to get the data hold by the workflow is to retrieve to whole workflow description.
226 *
227 * @param workflowID The workflow identifier
228 * @param placeID The place identifier that refers to the data
229 * @param userID
230 * @return The data as an array of Strings.
231 */
232 String[] getData(String workflowID, String placeID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
233
234 /**
235 * Set the human-readable description for a specific workflow.
236 * If the description already exists it will be replaced by the new description.
237 *
238 * @param workflowID The workflow identifier
239 * @param description The human-readable description
240 * @param userID
241 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
242 * @throws DatabaseException
243 */
244 void setDescription(String workflowID, String description, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
245
246 /**
247 * Get the human-readable description for a specific workflow.
248 *
249 * @param workflowID The workflow identifier
250 * @param userID
251 * @return The human-readable description
252 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
253 * @throws DatabaseException
254 */
255 String getDescription(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
256
257 /**
258 * Set the value of a specific workflow property.
259 * If a property with the same name already exists in this worklfow, the old property value will be replaced by the
260 * new one.
261 *
262 * @param workflowID The workflow identifier
263 * @param name Name of the property
264 * @param value Value of the property
265 * @param userID
266 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
267 */
268 void setProperty(String workflowID, String name, String value, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, WorkflowFormatException, GWESException, RemoteException, WorkflowSecurityException;
269
270 /**
271 * Get the value of a specific workflow property.
272 *
273 * @param workflowID The workflow identifier
274 * @param name Name of the property
275 * @param userID
276 * @return Value of the property
277 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
278 */
279 String getProperty(String workflowID, String name, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, WorkflowFormatException, GWESException, RemoteException, WorkflowSecurityException;
280
281 /**
282 * Get all propertries of a specific workflow.
283 * The properties are encoded in a two dimensional String array containing the name and the value for each property.
284 * Example:
285 * <pre>
286 * properties = getProperties(workflowID);
287 * properties[0][0] //Name of the first workflow property
288 * properties[0][1] //Value of the first workflow property
289 * properties[1][0] //Name of the second worklfow property
290 * properties[1][1] //Value of the second workflow property
291 * </pre>
292 *
293 * @param workflowID
294 * @param userID
295 * @return
296 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
297 */
298 String[][] getProperties(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, WorkflowFormatException, GWESException, RemoteException, WorkflowSecurityException;
299
300 /**
301 * Get the path of all available checkpoints for a specific workflow.
302 *
303 * @param workflowID The workflow identifier.
304 * @param userID
305 * @return A String array containing the checkpoint paths.
306 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
307 * @throws DatabaseException
308 */
309 String[] getCheckpoints(String workflowID, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
310
311 /**
312 * Remove a specific workflow from memory, database, and/or its temporary data on the Grid nodes.
313 * The level denotes from where to remove the workflow:
314 * <code>
315 * <li><b>level = 1: main memory</b>
316 * <li><b>level = 2: workflow database</b>
317 * <li>level = 3: main memory AND workflow database
318 * <li><b>level = 4: temporary data on Grid nodes</b>
319 * <li>level = 5: main memory AND temporary data on Grid nodes
320 * <li>level = 6: workflow database AND temporary data on Grid nodes
321 * <li>level = 7: main memory AND workflow database AND temporary data on Grid nodes
322 * </code>
323 *
324 * @param workflowID The workflow identifier.
325 * @param level From where to remove the workflow data.
326 * @param userID The user ID.
327 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
328 * @throws DatabaseException
329 */
330 void remove(String workflowID, int level, String userID) throws NoSuchWorkflowException, DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
331
332 /**
333 * Get the status array of all instantiated activities of a given workflow.
334 * Example String array for one activity:
335 * <pre>
336 * ID=hoheisel_2addc790-416a-11de-97f3-9cdc141524de_0000000025
337 * status=ACTIVE
338 * activityClass=net.kwfgrid.gwes.wsgramactivity.GRAMActivity
339 * operationName=software:makeload100
340 * resourceName=hardware:quadro.first.fhrg.fraunhofer.de
341 * timeoutActive=7200000
342 * timeoutRunning=86400000
343 * birthdayMs=1242403824742
344 * durationUndefinedMs=1
345 * durationInitiatedMs=1
346 * durationRunningMs=1886
347 * durationActiveMs=0
348 * durationSuspendedMs=0
349 * durationTotalMs=0
350 * endTimeMs=0
351 </pre>
352 * @param workflowID The workflow identifier.
353 * @param userID
354 * @return The current activity status as an array of string arrays
355 * @throws NoSuchWorkflowException If the workflow identifier is unknown to this GWES.
356 */
357 public String[][] getActivityStatusArray(String workflowID, String userID) throws LoggingException, NoSuchWorkflowException, GWESException, RemoteException, WorkflowSecurityException;
358
359 /**
360 * Get a list of all available resources.
361 * The information is returned in an Array of XML Strings:
362 * Example:
363 * <pre>
364 * String[] resources = getAvailableResources("urn:dgrdl:software");
365 * resources[0]=
366 * <resource>
367 * <uri>software:cat-fhrg</uri> // Operation URI
368 * <classUri>urn:dgrdl:software:cat</classUri> // Operation Class URI (workflow: operationClass name="...")
369 * <name>cat</name> // Operation Name
370 * <description>Program that concatenates two files<description> // Operation Description
371 * </resource>
372 * </pre>
373 * @param ofClass The class which this resource should be part of. This method only checkes whether the class starts
374 * with the given ofClass parameter, e.g., "urn:dgrdl:software" would match both classes: "urn:dgrdl:software:A"
375 * as well as "urn:dgrdl:software:B". If <code>ofClass</code> is <code>null</code> then all classes of resources are
376 * returned.
377 * @param userID
378 * @return The list of resources of a certain class as array of XML strings.
379 * @throws DatabaseException
380 */
381 String[] getAvailableResources(String ofClass, String userID) throws DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
382
383 /**
384 * Get the resource description of a specific resource in D-GRDL syntax.
385 * @param resourceUri The resource URI.
386 * @param userID
387 * @return A String which contains the D-GRDL document of the resource.
388 * @throws DatabaseException
389 */
390 String getResourceDescription(String resourceUri, String userID) throws DatabaseException, LoggingException, GWESException, RemoteException, WorkflowSecurityException;
391
392 }