1 /*
2 Copyright (C) 2007 Grid Systems, S.A.
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with this library; if not, write to the Free Software
16 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18 package nextgrid.api.pom;
19
20 import java.net.URI;
21 import java.util.Map;
22 import java.util.PriorityQueue;
23
24 import javax.xml.namespace.QName;
25
26 import nextgrid.api.env.ProcessEnvironment;
27 import nextgrid.api.pem.POMListener;
28
29 /**
30 * <p>A Process is the description of a task within a workflow. The task may be
31 * atomic or composed by several subtasks. It may also be abstract or concrete,
32 * depending on whether it only contains semantic information about the
33 * task requirements, or it also contains a binding to a specific service (or
34 * set of services).</p>
35 *
36 * <p>By design, processes must be storable in a persistent medium. By making
37 * this root interface extend {@link java.io.Serializable}, plain/XML java
38 * serialisation, and several ORM systems are supported.</p>
39 *
40 * <p>Process instances must be thread-safe.</p>
41 *
42 * @author Rodrigo Ruiz
43 */
44 public interface Process extends java.io.Serializable, Cloneable {
45 //----------------------------------------------------------------------------
46 // Local Properties Management
47 //----------------------------------------------------------------------------
48
49 /**
50 * Gets the process identifier.
51 *
52 * @return The process identifier
53 */
54 URI getId();
55
56 /**
57 * Sets the process identifier.
58 *
59 * @param id The process identifier
60 */
61 void setId(URI id);
62
63 /**
64 * Gets the process name.
65 * <p>
66 * The name is just for the user convenience, and
67 * it is not restricted in any way (or maybe just in its max length).
68 *
69 * @return The process name
70 */
71 String getName();
72
73 /**
74 * Sets the process name.
75 * <p>
76 * The name is just for the user convenience, and
77 * it is not restricted in any way (or maybe just in its max length).
78 *
79 * @param name The process name
80 */
81 void setName(String name);
82
83 /**
84 * Gets a short description for this process.
85 *
86 * @return A short description
87 */
88 String getDescription();
89
90 /**
91 * Sets a short description for this process.
92 *
93 * @param description A short description
94 */
95 void setDescription(String description);
96
97 /**
98 * Gets a map of attributes attached to this process instance.
99 * <p>
100 * The content of these attributes is arbitrary, and may be used for
101 * different purposes like semantic description, QoS specification,
102 *
103 * @return A map that gives access to the process attributes
104 */
105 Map<QName, String> getAttributes();
106
107 /**
108 * Gets an attribute by its qualified name.
109 *
110 * @param name The attribute name
111 * @return The attribute value, or null
112 */
113 String getAttribute(QName name);
114
115 /**
116 * Gets an attribute by its name.
117 * <p>
118 * This is equivalent to the following call:
119 * <pre>
120 * getAttribute(new QName("", name));
121 * </pre>
122 *
123 * @param name The local part of a QName with empty name-space
124 * @return The attribute value, or null
125 */
126 String getAttribute(String name);
127
128
129 /**
130 * Gets an attribute by its name.
131 * <p>
132 * This is equivalent to the following call:
133 * <pre>
134 * getAttribute(new QName(ns, local));
135 * </pre>
136 *
137 * @param ns The name-space
138 * @param local The local part
139 * @return The attribute value, or null
140 */
141 String getAttribute(String ns, String local);
142
143 /**
144 * Sets an attribute value.
145 *
146 * @param name The attribute qualified name
147 * @param value The attribute value
148 */
149 void setAttribute(QName name, String value);
150
151 /**
152 * Sets an attribute value.
153 *
154 * @param name The local part of a qualified name with empty name-space
155 * @param value The attribute value
156 */
157 void setAttribute(String name, String value);
158
159 /**
160 * Makes a deep copy of this instance.
161 *
162 * @return A deep copy of this instance
163 */
164 Process copy();
165
166 //----------------------------------------------------------------------------
167 // Process Hierarchy Management
168 //----------------------------------------------------------------------------
169
170 /**
171 * Gets the parent of this process.
172 *
173 * @return The parent
174 */
175 Process getParent();
176
177 /**
178 * Sets the parent of this process.
179 * <p>
180 * The parent process can only be a ControlProcess or AbstractProcess
181 * instance.
182 *
183 * @param parent The parent
184 * @throws IllegalArgumentException If the passed parent process cannot
185 * have children
186 */
187 void setParent(Process parent);
188
189 /**
190 * Finds the workflow root process.
191 *
192 * @return The root
193 */
194 Process findRoot();
195
196 /**
197 * Searches through the entire workflow a Process instance with the given
198 * identifier.
199 *
200 * @param id A process Id
201 * @return A Process instance, or null if no match found
202 */
203 Process findProcessById(URI id);
204
205 // -------------------------------------------------------------
206 // Input/Output Management
207 // -------------------------------------------------------------
208
209 /**
210 * Gets the map of references to input parameters.
211 *
212 * @return the input parameter reference map
213 */
214 Map<String, Reference<?>> getInputs();
215
216 /**
217 * Gets the map of references to output parameters.
218 *
219 * @return the output parameter reference map
220 */
221 Map<String, Reference<?>> getOutputs();
222
223 /**
224 * Gets an input reference by name.
225 *
226 * @param name The input name
227 * @return The input
228 */
229 Reference<?> getInput(String name);
230
231 /**
232 * Gets an output reference by name.
233 *
234 * @param name The output name
235 * @return The output
236 */
237 Reference<?> getOutput(String name);
238
239 /**
240 * Puts a reference into the map of input parameters for this process.
241 *
242 * @param key The parameter name
243 * @param input The parameter
244 */
245 void putInput(String key, Reference<?> input);
246
247 /**
248 * Puts a reference into the map of output parameters for this process.
249 *
250 * @param key The parameter name
251 * @param output The parameter
252 */
253 void putOutput(String key, Reference<?> output);
254
255 /**
256 * Removes a reference from the input map.
257 *
258 * @param key The name of the reference to remove
259 */
260 void removeInput(String key);
261
262 /**
263 * Removes a reference from the output map.
264 *
265 * @param key The name of the reference to remove
266 */
267 void removeOutput(String key);
268
269 /**
270 * Declares that this process requires an input parameter with the specified
271 * name and type.
272 *
273 * @param name A name for the input parameter
274 * @param type A type
275 */
276 void useInput(String name, Class<?> type);
277
278 /**
279 * Declares that this process uses the set of outputs specified by the
280 * passed list.
281 *
282 * @param name A name for the input parameter
283 * @param type A type
284 */
285 void useOutput(String name, Class<?> type);
286
287 /**
288 * Removes the passed names from the list of needed inputs.
289 *
290 * @param names The names to remove
291 */
292 void unuseInput(String... names);
293
294 /**
295 * Removes the passed names from the list of needed outputs.
296 *
297 * @param names The names to remove
298 */
299 void unuseOutput(String... names);
300
301 /**
302 * Gets the list of inputs directly used by this process.
303 *
304 * @return The names of the inputs used by this process
305 */
306 String[] getUsedInputNames();
307
308 /**
309 * Gets the list of outputs directly used by this process.
310 *
311 * @return The names of the outputs used by this process
312 */
313 String[] getUsedOutputNames();
314
315 /**
316 * Gets the data type for the specified input parameter.
317 *
318 * @param name The input name
319 * @return Its type, or null if no input is found with the given name
320 */
321 Class<?> getInputType(String name);
322
323 /**
324 * Gets the data type for the specified output parameter.
325 *
326 * @param name The output name
327 * @return Its type, or null if no output is found with the given name
328 */
329 Class<?> getOutputType(String name);
330
331 // -------------------------------------------------------------
332 // Enaction Management
333 // -------------------------------------------------------------
334
335 /**
336 * Gets the value of the "lazy" attribute.
337 * <p>
338 * This attribute determines the behaviour during the evaluation phase. If
339 * it is set to false, the process will be evaluated during the phase. If
340 * set to true, its evaluation will be delayed until the process is actually
341 * enacted, or its evaluation is "forced".
342 *
343 * @return The value of the lazy attribute
344 */
345 boolean isLazy();
346
347 /**
348 * Sets the value of the "lazy" attribute.
349 *
350 * @param lazy The new value
351 */
352 void setLazy(boolean lazy);
353
354 /**
355 * Validates this process.
356 *
357 * @throws ProcessException If the validation fails
358 */
359 void validate() throws ProcessException;
360
361 /**
362 * Marks this process as not validated.
363 * <p>
364 * An invalidation in a process must be propagated to its parent process.
365 */
366 void invalidate();
367
368 /**
369 * Gets the validation state of this process.
370 *
371 * @return The validation state
372 */
373 boolean isValidated();
374
375 /**
376 * Gets the evaluation state of this process.
377 *
378 * @return <tt>true</tt> if this process has already been evaluated
379 */
380 boolean isEvaluated();
381
382 /**
383 * Prepares the process for being enacted.
384 * <p>
385 * The actual enaction is started through {@link ProcessController#start()}.
386 *
387 * @param env The enaction context
388 * @return A controller instance
389 * @throws ProcessException If an error occurs
390 */
391 ProcessController enact(ProcessEnvironment env) throws ProcessException;
392
393 /**
394 * Evaluates this process.
395 * <p>
396 * Evaluation means the action of translating an abstract workflow into a
397 * concrete one.
398 *
399 * @param env The enaction context
400 * @throws ProcessException If an error occurs
401 */
402 void evaluate(ProcessEnvironment env) throws ProcessException;
403
404 /**
405 * Discovers service implementations for this process.
406 *
407 * @param env The enaction context
408 * @throws ProcessException If a discovery failure occurs
409 */
410 void discover(ProcessEnvironment env) throws ProcessException;
411
412 /**
413 * Determines the evaluation order of this process children.
414 * <p>
415 * This method populates the specified set with all the abstract
416 * processes found in this workflow, sorted by priority. This set is later
417 * used for evaluating them in the correct order.
418 * <p>
419 * The set will include all abstract processes, except those already evaluated
420 * and those with the attribute "lazy" set to true.
421 *
422 * @param env The enaction context
423 * @param queue A set of processes to be evaluated, sorted by their priority
424 * @throws ProcessException If the prioritisation fails
425 */
426 void prioritise(ProcessEnvironment env, PriorityQueue<Process> queue)
427 throws ProcessException;
428
429 /**
430 * Performs a clean up of the internal state of this process, and any
431 * children processes if they exist.
432 * <p>
433 * This method leaves the process in a "ready" state for enaction.
434 */
435 void reset();
436
437 // -------------------------------------------------------------
438 // Listeners Management
439 // -------------------------------------------------------------
440
441 /**
442 * Adds a listener to this process.
443 * <p>
444 * Different listeners will be associated to different events. It is up to
445 * the implementation class to classify registered listeners appropriately for
446 * efficient notification.
447 *
448 * @param listener The listener instance
449 */
450 void addListener(POMListener listener);
451
452 /**
453 * Removes a listener from this process.
454 *
455 * @param listener The listener instance
456 */
457 void removeListener(POMListener listener);
458 }