Coverage Report

Coverage Report - nextgrid.api.pom.Process

Classes in this File

 /*
  Copyright (C) 2007 Grid Systems, S.A.
 
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.
 
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.
 
  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 */
 package nextgrid.api.pom;
 
 import java.net.URI;
 import java.util.Map;
 import java.util.PriorityQueue;
 
 import javax.xml.namespace.QName;
 
 import nextgrid.api.env.ProcessEnvironment;
 import nextgrid.api.pem.POMListener;
 
 /**
  * <p>A Process is the description of a task within a workflow. The task may be
  * atomic or composed by several subtasks. It may also be abstract or concrete,
  * depending on whether it only contains semantic information about the
  * task requirements, or it also contains a binding to a specific service (or
  * set of services).</p>
  *
  * <p>By design, processes must be storable in a persistent medium. By making
  * this root interface extend {@link java.io.Serializable}, plain/XML java
  * serialisation, and several ORM systems are supported.</p>
  *
  * <p>Process instances must be thread-safe.</p>
  *
  * @author Rodrigo Ruiz
  */
 public interface Process extends java.io.Serializable, Cloneable {
   //----------------------------------------------------------------------------
   // Local Properties Management
   //----------------------------------------------------------------------------
 
   /**
    * Gets the process identifier.
    *
    * @return The process identifier
    */
   URI getId();
 
   /**
    * Sets the process identifier.
    *
    * @param id The process identifier
    */
   void setId(URI id);
 
   /**
    * Gets the process name.
    * <p>
    * The name is just for the user convenience, and
    * it is not restricted in any way (or maybe just in its max length).
    *
    * @return The process name
    */
   String getName();
 
   /**
    * Sets the process name.
    * <p>
    * The name is just for the user convenience, and
    * it is not restricted in any way (or maybe just in its max length).
    *
    * @param name The process name
    */
   void setName(String name);
 
   /**
    * Gets a short description for this process.
    *
    * @return A short description
    */
   String getDescription();
 
   /**
    * Sets a short description for this process.
    *
    * @param description A short description
    */
   void setDescription(String description);
 
   /**
    * Gets a map of attributes attached to this process instance.
    * <p>
    * The content of these attributes is arbitrary, and may be used for
    * different purposes like semantic description, QoS specification,
    *
    * @return A map that gives access to the process attributes
    */
   Map<QName, String> getAttributes();
 
   /**
    * Gets an attribute by its qualified name.
    *
    * @param name The attribute name
    * @return The attribute value, or null
    */
   String getAttribute(QName name);
 
   /**
    * Gets an attribute by its name.
    * <p>
    * This is equivalent to the following call:
    * <pre>
    * getAttribute(new QName("", name));
    * </pre>
    *
    * @param name The local part of a QName with empty name-space
    * @return The attribute value, or null
    */
   String getAttribute(String name);
 
 
   /**
    * Gets an attribute by its name.
    * <p>
    * This is equivalent to the following call:
    * <pre>
    * getAttribute(new QName(ns, local));
    * </pre>
    *
    * @param ns    The name-space
    * @param local The local part
    * @return The attribute value, or null
    */
   String getAttribute(String ns, String local);
 
   /**
    * Sets an attribute value.
    *
    * @param name  The attribute qualified name
    * @param value The attribute value
    */
   void setAttribute(QName name, String value);
 
   /**
    * Sets an attribute value.
    *
    * @param name   The local part of a qualified name with empty name-space
    * @param value  The attribute value
    */
   void setAttribute(String name, String value);
 
   /**
    * Makes a deep copy of this instance.
    *
    * @return A deep copy of this instance
    */
   Process copy();
 
   //----------------------------------------------------------------------------
   // Process Hierarchy Management
   //----------------------------------------------------------------------------
 
   /**
    * Gets the parent of this process.
    *
    * @return The parent
    */
   Process getParent();
 
   /**
    * Sets the parent of this process.
    * <p>
    * The parent process can only be a ControlProcess or AbstractProcess
    * instance.
    *
    * @param parent The parent
    * @throws IllegalArgumentException If the passed parent process cannot
    *                                  have children
    */
   void setParent(Process parent);
 
   /**
    * Finds the workflow root process.
    *
    * @return The root
    */
   Process findRoot();
 
   /**
    * Searches through the entire workflow a Process instance with the given
    * identifier.
    *
    * @param id A process Id
    * @return A Process instance, or null if no match found
    */
   Process findProcessById(URI id);
 
   // -------------------------------------------------------------
   // Input/Output Management
   // -------------------------------------------------------------
 
   /**
    * Gets the map of references to input parameters.
    *
    * @return the input parameter reference map
    */
   Map<String, Reference<?>> getInputs();
 
   /**
    * Gets the map of references to output parameters.
    *
    * @return the output parameter reference map
    */
   Map<String, Reference<?>> getOutputs();
 
   /**
    * Gets an input reference by name.
    *
    * @param name The input name
    * @return The input
    */
   Reference<?> getInput(String name);
 
   /**
    * Gets an output reference by name.
    *
    * @param name The output name
    * @return The output
    */
   Reference<?> getOutput(String name);
 
   /**
    * Puts a reference into the map of input parameters for this process.
    *
    * @param key   The parameter name
    * @param input The parameter
    */
   void putInput(String key, Reference<?> input);
 
   /**
    * Puts a reference into the map of output parameters for this process.
    *
    * @param key    The parameter name
    * @param output The parameter
    */
   void putOutput(String key, Reference<?> output);
 
   /**
    * Removes a reference from the input map.
    *
    * @param key The name of the reference to remove
    */
   void removeInput(String key);
 
   /**
    * Removes a reference from the output map.
    *
    * @param key The name of the reference to remove
    */
   void removeOutput(String key);
 
   /**
    * Declares that this process requires an input parameter with the specified
    * name and type.
    *
    * @param name A name for the input parameter
    * @param type A type
    */
   void useInput(String name, Class<?> type);
 
   /**
    * Declares that this process uses the set of outputs specified by the
    * passed list.
    *
    * @param name A name for the input parameter
    * @param type A type
    */
   void useOutput(String name, Class<?> type);
 
   /**
    * Removes the passed names from the list of needed inputs.
    *
    * @param names The names to remove
    */
   void unuseInput(String... names);
 
   /**
    * Removes the passed names from the list of needed outputs.
    *
    * @param names The names to remove
    */
   void unuseOutput(String... names);
 
   /**
    * Gets the list of inputs directly used by this process.
    *
    * @return The names of the inputs used by this process
    */
   String[] getUsedInputNames();
 
   /**
    * Gets the list of outputs directly used by this process.
    *
    * @return The names of the outputs used by this process
    */
   String[] getUsedOutputNames();
 
   /**
    * Gets the data type for the specified input parameter.
    *
    * @param name The input name
    * @return Its type, or null if no input is found with the given name
    */
   Class<?> getInputType(String name);
 
   /**
    * Gets the data type for the specified output parameter.
    *
    * @param name The output name
    * @return Its type, or null if no output is found with the given name
    */
   Class<?> getOutputType(String name);
 
   // -------------------------------------------------------------
   // Enaction Management
   // -------------------------------------------------------------
 
   /**
    * Gets the value of the "lazy" attribute.
    * <p>
    * This attribute determines the behaviour during the evaluation phase. If
    * it is set to false, the process will be evaluated during the phase. If
    * set to true, its evaluation will be delayed until the process is actually
    * enacted, or its evaluation is "forced".
    *
    * @return The value of the lazy attribute
    */
   boolean isLazy();
 
   /**
    * Sets the value of the "lazy" attribute.
    *
    * @param lazy The new value
    */
   void setLazy(boolean lazy);
 
   /**
    * Validates this process.
    *
    * @throws ProcessException If the validation fails
    */
   void validate() throws ProcessException;
 
   /**
    * Marks this process as not validated.
    * <p>
    * An invalidation in a process must be propagated to its parent process.
    */
   void invalidate();
 
   /**
    * Gets the validation state of this process.
    *
    * @return The validation state
    */
   boolean isValidated();
 
   /**
    * Gets the evaluation state of this process.
    *
    * @return <tt>true</tt> if this process has already been evaluated
    */
   boolean isEvaluated();
 
   /**
    * Prepares the process for being enacted.
    * <p>
    * The actual enaction is started through {@link ProcessController#start()}.
    *
    * @param env The enaction context
    * @return A controller instance
    * @throws ProcessException If an error occurs
    */
   ProcessController enact(ProcessEnvironment env) throws ProcessException;
 
   /**
    * Evaluates this process.
    * <p>
    * Evaluation means the action of translating an abstract workflow into a
    * concrete one.
    *
    * @param env The enaction context
    * @throws ProcessException If an error occurs
    */
   void evaluate(ProcessEnvironment env) throws ProcessException;
 
   /**
    * Discovers service implementations for this process.
    *
    * @param env The enaction context
    * @throws ProcessException If a discovery failure occurs
    */
   void discover(ProcessEnvironment env) throws ProcessException;
 
   /**
    * Determines the evaluation order of this process children.
    * <p>
    * This method populates the specified set with all the abstract
    * processes found in this workflow, sorted by priority. This set is later
    * used for evaluating them in the correct order.
    * <p>
    * The set will include all abstract processes, except those already evaluated
    * and those with the attribute "lazy" set to true.
    *
    * @param env   The enaction context
    * @param queue A set of processes to be evaluated, sorted by their priority
    * @throws ProcessException If the prioritisation fails
    */
   void prioritise(ProcessEnvironment env, PriorityQueue<Process> queue)
     throws ProcessException;
 
   /**
    * Performs a clean up of the internal state of this process, and any
    * children processes if they exist.
    * <p>
    * This method leaves the process in a "ready" state for enaction.
    */
   void reset();
 
   // -------------------------------------------------------------
   // Listeners Management
   // -------------------------------------------------------------
 
   /**
    * Adds a listener to this process.
    * <p>
    * Different listeners will be associated to different events. It is up to
    * the implementation class to classify registered listeners appropriately for
    * efficient notification.
    *
    * @param listener The listener instance
    */
   void addListener(POMListener listener);
 
   /**
    * Removes a listener from this process.
    *
    * @param listener The listener instance
    */
   void removeListener(POMListener listener);
 }

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		}