nextgrid.api.pom
Interface Process

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

AbstractProcess, AsyncProcess, ControlProcess, DoWhileProcess, IfThenElseProcess, LoopProcess, RepeatUntilProcess, SequenceProcess, Service, SplitJoinProcess, UnorderedListProcess, WhileDoProcess

public interface Process
extends java.io.Serializable, java.lang.Cloneable

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).

By design, processes must be storable in a persistent medium. By making this root interface extend Serializable, plain/XML java serialisation, and several ORM systems are supported.

Process instances must be thread-safe.

Author:

Rodrigo Ruiz

Method Summary

void	addListener(POMListener listener) Adds a listener to this process.
Process	copy() Makes a deep copy of this instance.
void	discover(ProcessEnvironment env) Discovers service implementations for this process.
ProcessController	enact(ProcessEnvironment env) Prepares the process for being enacted.
void	evaluate(ProcessEnvironment env) Evaluates this process.
Process	findProcessById(java.net.URI id) Searches through the entire workflow a Process instance with the given identifier.
Process	findRoot() Finds the workflow root process.
java.lang.String	getAttribute(javax.xml.namespace.QName name) Gets an attribute by its qualified name.
java.lang.String	getAttribute(java.lang.String name) Gets an attribute by its name.
java.lang.String	getAttribute(java.lang.String ns, java.lang.String local) Gets an attribute by its name.
java.util.Map<javax.xml.namespace.QName,java.lang.String>	getAttributes() Gets a map of attributes attached to this process instance.
java.lang.String	getDescription() Gets a short description for this process.
java.net.URI	getId() Gets the process identifier.
Reference<?>	getInput(java.lang.String name) Gets an input reference by name.
java.util.Map<java.lang.String,Reference<?>>	getInputs() Gets the map of references to input parameters.
java.lang.Class<?>	getInputType(java.lang.String name) Gets the data type for the specified input parameter.
java.lang.String	getName() Gets the process name.
Reference<?>	getOutput(java.lang.String name) Gets an output reference by name.
java.util.Map<java.lang.String,Reference<?>>	getOutputs() Gets the map of references to output parameters.
java.lang.Class<?>	getOutputType(java.lang.String name) Gets the data type for the specified output parameter.
Process	getParent() Gets the parent of this process.
java.lang.String[]	getUsedInputNames() Gets the list of inputs directly used by this process.
java.lang.String[]	getUsedOutputNames() Gets the list of outputs directly used by this process.
void	invalidate() Marks this process as not validated.
boolean	isEvaluated() Gets the evaluation state of this process.
boolean	isLazy() Gets the value of the "lazy" attribute.
boolean	isValidated() Gets the validation state of this process.
void	prioritise(ProcessEnvironment env, java.util.PriorityQueue<Process> queue) Determines the evaluation order of this process children.
void	putInput(java.lang.String key, Reference<?> input) Puts a reference into the map of input parameters for this process.
void	putOutput(java.lang.String key, Reference<?> output) Puts a reference into the map of output parameters for this process.
void	removeInput(java.lang.String key) Removes a reference from the input map.
void	removeListener(POMListener listener) Removes a listener from this process.
void	removeOutput(java.lang.String key) Removes a reference from the output map.
void	reset() Performs a clean up of the internal state of this process, and any children processes if they exist.
void	setAttribute(javax.xml.namespace.QName name, java.lang.String value) Sets an attribute value.
void	setAttribute(java.lang.String name, java.lang.String value) Sets an attribute value.
void	setDescription(java.lang.String description) Sets a short description for this process.
void	setId(java.net.URI id) Sets the process identifier.
void	setLazy(boolean lazy) Sets the value of the "lazy" attribute.
void	setName(java.lang.String name) Sets the process name.
void	setParent(Process parent) Sets the parent of this process.
void	unuseInput(java.lang.String... names) Removes the passed names from the list of needed inputs.
void	unuseOutput(java.lang.String... names) Removes the passed names from the list of needed outputs.
void	useInput(java.lang.String name, java.lang.Class<?> type) Declares that this process requires an input parameter with the specified name and type.
void	useOutput(java.lang.String name, java.lang.Class<?> type) Declares that this process uses the set of outputs specified by the passed list.
void	validate() Validates this process.

Method Detail

getId

java.net.URI getId()

Gets the process identifier.

Returns:

The process identifier

setId

void setId(java.net.URI id)

Sets the process identifier.

Parameters:

id - The process identifier

getName

java.lang.String getName()

Gets the process name.

The name is just for the user convenience, and it is not restricted in any way (or maybe just in its max length).

Returns:

The process name

setName

void setName(java.lang.String name)

Sets the process name.

The name is just for the user convenience, and it is not restricted in any way (or maybe just in its max length).

Parameters:

name - The process name

getDescription

java.lang.String getDescription()

Gets a short description for this process.

Returns:

A short description

setDescription

void setDescription(java.lang.String description)

Sets a short description for this process.

Parameters:

description - A short description

getAttributes

java.util.Map<javax.xml.namespace.QName,java.lang.String> getAttributes()

Gets a map of attributes attached to this process instance.

The content of these attributes is arbitrary, and may be used for different purposes like semantic description, QoS specification,

Returns:

A map that gives access to the process attributes

getAttribute

java.lang.String getAttribute(javax.xml.namespace.QName name)

Gets an attribute by its qualified name.

Parameters:

name - The attribute name

Returns:

The attribute value, or null

getAttribute

java.lang.String getAttribute(java.lang.String name)

Gets an attribute by its name.

This is equivalent to the following call:

 getAttribute(new QName("", name));
 

Parameters:

name - The local part of a QName with empty name-space

Returns:

The attribute value, or null

getAttribute

java.lang.String getAttribute(java.lang.String ns,
                              java.lang.String local)

Gets an attribute by its name.

This is equivalent to the following call:

 getAttribute(new QName(ns, local));
 

Parameters:

ns - The name-space

local - The local part

Returns:

The attribute value, or null

setAttribute

void setAttribute(javax.xml.namespace.QName name,
                  java.lang.String value)

Sets an attribute value.

Parameters:

name - The attribute qualified name

value - The attribute value

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.String value)

Sets an attribute value.

Parameters:

name - The local part of a qualified name with empty name-space

value - The attribute value

copy

Process copy()

Makes a deep copy of this instance.

Returns:

A deep copy of this instance

getParent

Process getParent()

Gets the parent of this process.

Returns:

The parent

setParent

void setParent(Process parent)

Sets the parent of this process.

The parent process can only be a ControlProcess or AbstractProcess instance.

Parameters:

parent - The parent

Throws:

java.lang.IllegalArgumentException - If the passed parent process cannot have children

findRoot

Process findRoot()

Finds the workflow root process.

Returns:

The root

findProcessById

Process findProcessById(java.net.URI id)

Searches through the entire workflow a Process instance with the given identifier.

Parameters:

id - A process Id

Returns:

A Process instance, or null if no match found

getInputs

java.util.Map<java.lang.String,Reference<?>> getInputs()

Gets the map of references to input parameters.

Returns:

the input parameter reference map

getOutputs

java.util.Map<java.lang.String,Reference<?>> getOutputs()

Gets the map of references to output parameters.

Returns:

the output parameter reference map

getInput

Reference<?> getInput(java.lang.String name)

Gets an input reference by name.

Parameters:

name - The input name

Returns:

The input

getOutput

Reference<?> getOutput(java.lang.String name)

Gets an output reference by name.

Parameters:

name - The output name

Returns:

The output

putInput

void putInput(java.lang.String key,
              Reference<?> input)

Puts a reference into the map of input parameters for this process.

Parameters:

key - The parameter name

input - The parameter

putOutput

void putOutput(java.lang.String key,
               Reference<?> output)

Puts a reference into the map of output parameters for this process.

Parameters:

key - The parameter name

output - The parameter

removeInput

void removeInput(java.lang.String key)

Removes a reference from the input map.

Parameters:

key - The name of the reference to remove

removeOutput

void removeOutput(java.lang.String key)

Removes a reference from the output map.

Parameters:

key - The name of the reference to remove

useInput

void useInput(java.lang.String name,
              java.lang.Class<?> type)

Declares that this process requires an input parameter with the specified name and type.

Parameters:

name - A name for the input parameter

type - A type

useOutput

void useOutput(java.lang.String name,
               java.lang.Class<?> type)

Declares that this process uses the set of outputs specified by the passed list.

Parameters:

name - A name for the input parameter

type - A type

unuseInput

void unuseInput(java.lang.String... names)

Removes the passed names from the list of needed inputs.

Parameters:

names - The names to remove

unuseOutput

void unuseOutput(java.lang.String... names)

Removes the passed names from the list of needed outputs.

Parameters:

names - The names to remove

getUsedInputNames

java.lang.String[] getUsedInputNames()

Gets the list of inputs directly used by this process.

Returns:

The names of the inputs used by this process

getUsedOutputNames

java.lang.String[] getUsedOutputNames()

Gets the list of outputs directly used by this process.

Returns:

The names of the outputs used by this process

getInputType

java.lang.Class<?> getInputType(java.lang.String name)

Gets the data type for the specified input parameter.

Parameters:

name - The input name

Returns:

Its type, or null if no input is found with the given name

getOutputType

java.lang.Class<?> getOutputType(java.lang.String name)

Gets the data type for the specified output parameter.

Parameters:

name - The output name

Returns:

Its type, or null if no output is found with the given name

isLazy

boolean isLazy()

Gets the value of the "lazy" attribute.

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".

Returns:

The value of the lazy attribute

setLazy

void setLazy(boolean lazy)

Sets the value of the "lazy" attribute.

Parameters:

lazy - The new value

validate

void validate()
              throws ProcessException

Validates this process.

Throws:

ProcessException - If the validation fails

invalidate

void invalidate()

Marks this process as not validated.

An invalidation in a process must be propagated to its parent process.

isValidated

boolean isValidated()

Gets the validation state of this process.

Returns:

The validation state

isEvaluated

boolean isEvaluated()

Gets the evaluation state of this process.

Returns:

true if this process has already been evaluated

enact

ProcessController enact(ProcessEnvironment env)
                        throws ProcessException

Prepares the process for being enacted.

The actual enaction is started through ProcessController.start().

Parameters:

env - The enaction context

Returns:

A controller instance

Throws:

ProcessException - If an error occurs

evaluate

void evaluate(ProcessEnvironment env)
              throws ProcessException

Evaluates this process.

Evaluation means the action of translating an abstract workflow into a concrete one.

Parameters:

env - The enaction context

Throws:

ProcessException - If an error occurs

discover

void discover(ProcessEnvironment env)
              throws ProcessException

Discovers service implementations for this process.

Parameters:

env - The enaction context

Throws:

ProcessException - If a discovery failure occurs

prioritise

void prioritise(ProcessEnvironment env,
                java.util.PriorityQueue<Process> queue)
                throws ProcessException

Determines the evaluation order of this process children.

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.

The set will include all abstract processes, except those already evaluated and those with the attribute "lazy" set to true.

Parameters:

env - The enaction context

queue - A set of processes to be evaluated, sorted by their priority

Throws:

ProcessException - If the prioritisation fails

reset

void reset()

Performs a clean up of the internal state of this process, and any children processes if they exist.

This method leaves the process in a "ready" state for enaction.

addListener

void addListener(POMListener listener)

Adds a listener to this process.

Different listeners will be associated to different events. It is up to the implementation class to classify registered listeners appropriately for efficient notification.

Parameters:

listener - The listener instance

removeListener

void removeListener(POMListener listener)

Removes a listener from this process.

Parameters:

listener - The listener instance