com.jbbres.lib.actions.workflow
Class Workflow

java.lang.Object
  com.jbbres.lib.actions.workflow.Workflow

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Runnable

public class Workflow
extends java.lang.Object
implements java.lang.Runnable, java.lang.Cloneable

An Action(s) workflow: a sequence of discrete tasks called Action. The workflow hooks the actions together so that "in most cases" the output of one action is the input of the subsequent action. Workflow can also use Variable objects to temporary store some data and results.

Workflow are run calling the execute() method. The execution is performed in a separate thread.

It is possible to listen to events occurring in the workflow by using instance of WorkflowListener and WorkflowDefinitionListener classes. WorkflowListener instances listen to the execution part of the workflow, for example when the workflow is started, paused, stopped etc. WorkflowDefinitionListener instances focus on the workflow definition process by notifying the addition or removal of an Action or a Variable.

Release Notes:

v1.1.0:

Added methods to set and get the next action to be executed by the workflow

Notifications management though sendNotification(WorkflowDefinitionNotification)

Bug corrections

Since:

1.0.0

Version:

1.1.0

Author:

Jean-Baptiste Bres

Constructor Summary

Workflow()
Instantiates a new workflow.

Method Summary

int	actionsCount() Returns the number of actions in the workflow.
boolean	add(Action action) Appends the specified action to the end of the workflow.
boolean	add(Action action, boolean useRecommendations) Deprecated. since 1.1.0
void	add(Action action, int index) Inserts the specified action at the specified position in this workflow.
void	add(Action action, int index, boolean useRecommendations) Deprecated. since 1.1.0
void	add(java.lang.Class<? extends Action> actionClazz, int position) Creates an instance of the Action class and add it to the workflow.
void	add(java.lang.Class<? extends Action> actionClazz, int position, boolean useRecommendations) Deprecated. since 1.1.0
boolean	add(java.lang.Class<? extends Element> elementClazz) Creates an instance of the Element class and add it to the workflow.
boolean	add(java.lang.Class<? extends Element> elementClazz, boolean useRecommendations) Deprecated. since 1.1.0
boolean	add(Element element) Adds an element (an Action or a Variable) to the workflow.
boolean	add(Element element, boolean useRecommendations) Deprecated. since 1.1.0
void	add(int index, Action action) Inserts the given action at the specified position in this workflow.
void	add(int index, Action action, boolean useRecommendations) Deprecated. since 1.1.0
boolean	add(Variable variable) Add an Variable to the workflow.
void	addWorkflowDefinitionListener(WorkflowDefinitionListener l) Adds a definition listener to this workflow.
void	addWorkflowListener(WorkflowListener l) Adds a listener to this workflow.
void	clearWorkflowDefinitionListeners() Removes all the definition listeners to this workflow.
void	clearWorkflowListeners() Removes all the listeners to this workflow.
Workflow	clone()
boolean	contains(Element e) Tests if the specified Element is a component in this workflow.
java.awt.Frame	dialogOwner() Returns the associated dialog owner.
boolean	equals(java.lang.Object obj)
void	execute() Executes the workflow: executes each action of the workflow one after the other.
void	fireActionMoved(Action action, int previousPosition) Calls the actionMoved() method of all the workflow listeners.
void	fireActionRemoved(Action action, int previousPosition) Calls the elementRemoved() method of all the workflow listeners.
void	fireElementAdded(Element element) Calls the elementAdded() method of all the workflow listeners.
void	fireElementRemoved(Element element) Calls the elementRemoved() method of all the workflow listeners.
void	fireWorkflowAskForInterruption() Calls the workflowAskForInterruption() method of all the workflow listeners.
void	fireWorkflowAskForSuspension() Calls the workflowAskForSuspension() method of all the workflow listeners.
void	fireWorkflowDefinitionNotification(WorkflowDefinitionNotification notification) Calls the notificationReceived(WorkflowDefinitionEvent) method of all the workflow definition listeners.
void	fireWorkflowEnd(int workflowStatus, java.lang.Object workflowResult) Calls the workflowEnd() method of all the workflow listeners.
void	fireWorkflowResumed() Calls the workflowResumed() method of all the workflow listeners.
void	fireWorkflowStart() Calls the workflowStart() method of all the workflow listeners.
void	fireWorkflowSuspended() Calls the workflowSuspended() method of all the workflow listeners.
Action	getAction(int index) Returns the action at the specified index.
Action[]	getActions() Returns the actions composing the workflow.
Action	getNextAction() Returns the next action to be executed by the workflow.
Action	getNextAction(Action ref) Returns the action immediatly following ref in the workflow.
Action	getPreviousAction(Action ref) Returns the action immediatly preceding ref in the workflow.
Variable	getVariable(int index) Returns the variable at the specified index.
Variable[]	getVariables() Returns the variables associated to the workflow.
WorkflowDefinitionListener[]	getWorkflowDefinitionListeners() Returns the definition listeners to this workflow.
WorkflowListener[]	getWorkflowListeners() Returns the listeners to this workflow.
int	indexOfAction(Action action) Searches for the first occurence of the given action within the workflow.
void	interrupt() Interrupts (ends) the workflow.
boolean	isRunning() Returns true if the workflow is currently running.
boolean	moveAction(Action action, int toPosition) Moves the given action to the toPosition position.
void	moveAction(int fromPosition, int toPosition) Moves the action at the fromPosition position to the toPosition position in the workflow.
void	pause() Pauses the workflow if it is running.
int	positionOf(Action action) Returns the action position in the workflow.
boolean	remove(Element element) Removes an element (an Action or an Variable) from the workflow.
Action	remove(int index) Removes the action at the specified position in this Vector.
boolean	remove(Variable variable) Removes a Variable from the workflow.
void	removeWorkflowDefinitionListener(WorkflowDefinitionListener l) Removes a definition listener to this workflow.
void	removeWorkflowListener(WorkflowListener l) Removes a listener to this workflow.
void	resume() Wakes up the workflow if it has been put on hold by invoking the pause() method.
void	run() For internal purpose only.
void	sendNotification(WorkflowDefinitionNotification notification) Send the notification to all the WorkflowDefinitionListeners.
void	setDialogOwner(java.awt.Frame frame) Sets the dialog owner.
void	setNextAction(Action nextAction) Sets the next action to be executed by the workflow.
void	step() Asks the workflow to process only the next step and then pause.
int	variablesCount() Returns the number of variables in the workflow.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Workflow

public Workflow()

Instantiates a new workflow.

Method Detail

getVariables

public Variable[] getVariables()

Returns the variables associated to the workflow.

Returns:

the variables associated to the workflow

See Also:

getVariable(int), variablesCount()

getVariable

public Variable getVariable(int index)

Returns the variable at the specified index.

Variable order is not important within the workflow. This method is provided for conveniance only.

Parameters:

index - - the inde

Returns:

the variable at the specified index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is negative or not less than the current number of variables in the workflow.

See Also:

getVariables(), variablesCount()

variablesCount

public int variablesCount()

Returns the number of variables in the workflow.

Returns:

the number of variables in the workflow.

See Also:

getVariables(), getVariable(int)

getPreviousAction

public Action getPreviousAction(Action ref)

Returns the action immediatly preceding ref in the workflow.

Parameters:

ref - - the action used as a reference.

Returns:

the action immediatly preceding ref in the workflow.

See Also:

getNextAction(Action), getActions()

getNextAction

public Action getNextAction(Action ref)

Returns the action immediatly following ref in the workflow.

Parameters:

ref - - the action used as a reference.

Returns:

the action immediatly following ref in the workflow.

See Also:

getPreviousAction(Action), getActions()

getActions

public Action[] getActions()

Returns the actions composing the workflow.

Returns:

the actions composing the workflow.

See Also:

getAction(int), actionsCount()

getAction

public Action getAction(int index)

Returns the action at the specified index.

Parameters:

index - - the index

Returns:

the action at the specified index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is negative or not less than the current number of actions in the workflow.

See Also:

getActions(), actionsCount()

indexOfAction

public int indexOfAction(Action action)

Searches for the first occurence of the given action within the workflow.

Parameters:

action - - an action

Returns:

the index of the first occurrence of the action in this workflow; returns -1 if the action is not found.

actionsCount

public int actionsCount()

Returns the number of actions in the workflow.

Returns:

the number of actions in the workflow.

See Also:

getActions(), getAction(int)

add

public boolean add(java.lang.Class<? extends Element> elementClazz)
            throws java.lang.IllegalArgumentException,
                   java.lang.SecurityException,
                   java.lang.InstantiationException,
                   java.lang.IllegalAccessException,
                   java.lang.reflect.InvocationTargetException,
                   java.lang.NoSuchMethodException

Creates an instance of the Element class and add it to the workflow.

Parameters:

elementClazz - - Element class

Returns:

true if the addition is successfull.

Throws:

java.lang.IllegalArgumentException - cannot create an instance of the given class.

java.lang.SecurityException - if a security exception occurs.

java.lang.InstantiationException - cannot create an instance of the given class.

java.lang.IllegalAccessException - cannot create an instance of the given class.

java.lang.reflect.InvocationTargetException - cannot create an instance of the given class.

java.lang.NoSuchMethodException - cannot create an instance of the given class.

See Also:

remove(Element), add(Element), add(Action), add(Variable)

add

public boolean add(Element element)

Adds an element (an Action or a Variable) to the workflow.

Parameters:

element - - element to be added

Returns:

true if the addition is successfull.

See Also:

remove(Element), add(Action), add(Variable)

add

public boolean add(Variable variable)

Add an Variable to the workflow.

Parameters:

variable - - variable to be added

Returns:

true if the addition is successful.

See Also:

remove(Variable), add(Element)

add

public void add(java.lang.Class<? extends Action> actionClazz,
                int position)
         throws java.lang.IllegalArgumentException,
                java.lang.SecurityException,
                java.lang.InstantiationException,
                java.lang.IllegalAccessException,
                java.lang.reflect.InvocationTargetException,
                java.lang.NoSuchMethodException

Creates an instance of the Action class and add it to the workflow.

Parameters:

actionClazz - - Action class

position - - the position in the workflow

Throws:

java.lang.IllegalArgumentException - cannot create an instance of the given class.

java.lang.SecurityException - if a security exception occurs.

java.lang.InstantiationException - cannot create an instance of the given class.

java.lang.IllegalAccessException - cannot create an instance of the given class.

java.lang.reflect.InvocationTargetException - cannot create an instance of the given class.

java.lang.NoSuchMethodException - cannot create an instance of the given class.

Since:

1.1.0

See Also:

remove(Element), add(Element, boolean), add(Action, int, boolean)

add

public boolean add(Action action)

Appends the specified action to the end of the workflow.

Parameters:

action - the action

Returns:

true if the addition is successful.

See Also:

remove(Element), add(Action, int), add(Element)

add

public void add(int index,
                Action action)

Inserts the given action at the specified position in this workflow. Shifts the action currently at that position (if any) and any subsequent elements to the bottom (adds one to their indices).

Parameters:

index - - the index

action - - the action

See Also:

remove(int), add(Action, int)

add

public void add(Action action,
                int index)

Inserts the specified action at the specified position in this workflow. This method is similar to add(int, Action).

Parameters:

action - - action to be added

index - - position

See Also:

remove(int), add(int, Action)

sendNotification

public void sendNotification(WorkflowDefinitionNotification notification)

Send the notification to all the WorkflowDefinitionListeners.

Notifications can be used to provide information to the user while he/she is creating a workflow. Notifications are displayed at the top of the workflow panel.

Parameters:

notification - the notification

Since:

1.1.0

remove

public boolean remove(Element element)

Removes an element (an Action or an Variable) from the workflow.

Parameters:

element - - element to be removed

Returns:

true, if the removal is successful

See Also:

add(Element), remove(int), remove(Variable)

remove

public boolean remove(Variable variable)

Removes a Variable from the workflow.

Parameters:

variable - - variable to be removed

Returns:

true, if the removal is successful

See Also:

add(Variable), remove(Element)

remove

public Action remove(int index)

Removes the action at the specified position in this Vector. Shifts any subsequent actions to the left (subtracts one from their indices). Returns the action that was removed from the Vector.

This function is overridden for internal purpose.

Parameters:

index - - the index

Returns:

the removed action

See Also:

remove(Element), add(Action, int)

moveAction

public void moveAction(int fromPosition,
                       int toPosition)

Moves the action at the fromPosition position to the toPosition position in the workflow.

Parameters:

fromPosition - - initial position

toPosition - - destination

See Also:

moveAction(Action, int)

moveAction

public boolean moveAction(Action action,
                          int toPosition)

Moves the given action to the toPosition position.

Parameters:

action - - action to be moved

toPosition - - destination

Returns:

true if the function succeed, false otherwise.

See Also:

moveAction(int, int)

contains

public boolean contains(Element e)

Tests if the specified Element is a component in this workflow.

Parameters:

e - - an Element.

Returns:

true if and only if the specified Element is the same as a component in this workflow; false otherwise.

See Also:

add(Element)

positionOf

public int positionOf(Action action)

Returns the action position in the workflow.

Parameters:

action - - action

Returns:

the action position in the workflow

execute

public void execute()

Executes the workflow: executes each action of the workflow one after the other. The result of each action is used as the input of the next one.

The execution takes place in a separate Thread.

See Also:

pause(), resume(), interrupt(), step()

isRunning

public boolean isRunning()

Returns true if the workflow is currently running. false otherwise.

Returns:

true if the workflow is currently running. false otherwise.

See Also:

execute()

pause

public void pause()

Pauses the workflow if it is running.

The workflow is stopped until the resume() method is called.
Do not call this method within the ActionService.execute(Object, Parameters) method except if you call it from a another thread than the default one, as it might result for the workflow to be blocked indefinitely.

See Also:

execute(), resume(), interrupt()

resume

public void resume()

Wakes up the workflow if it has been put on hold by invoking the pause() method.

See Also:

pause(), execute(), interrupt()

step

public void step()

Asks the workflow to process only the next step and then pause.

See Also:

pause(), resume(), interrupt(), execute()

interrupt

public void interrupt()

Interrupts (ends) the workflow.

See Also:

execute(), pause(), resume()

setNextAction

public void setNextAction(Action nextAction)

Sets the next action to be executed by the workflow. By default, the actions are executed one after the others. However an action might want to "break" the workflow by defining what will be the next step.

nextAction must be either one of the actions of the workflow, either null. If not, the method will fail and the next action will not be changed.

Passing null to this method will stop the workflow once the current action is processed.

Parameters:

nextAction - the new next action to be executed by the workflow.

Since:

1.1.0

getNextAction

public Action getNextAction()

Returns the next action to be executed by the workflow. If the current action is the last action to be executed by the workflow, this method returns null.

Returns:

the next action to be executed by the workflow.

Since:

1.1.0

run

public final void run()

For internal purpose only. Do not call this method as it will be executed in the current thread when it should be executed in a separate thread.
Use the execute() method instead.

When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread. The general contract of the method run is that it may take any action whatsoever.

Specified by:

run in interface java.lang.Runnable

See Also:

execute()

clone

public Workflow clone()

Overrides:

clone in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

dialogOwner

public java.awt.Frame dialogOwner()

Returns the associated dialog owner.

If an action required to display a JDialog or a JFrame, it can use the result of this function as owner:
JDialog dialog = new JDialog(action.getWorkflow().dialogOwner());

Returns:

the frame

setDialogOwner

public final void setDialogOwner(java.awt.Frame frame)

Sets the dialog owner. This method should not be called as the dialog owner is not supposed to be changed.

Parameters:

frame - the frame

addWorkflowListener

public void addWorkflowListener(WorkflowListener l)

Adds a listener to this workflow.

Parameters:

l - - new listener

removeWorkflowListener

public void removeWorkflowListener(WorkflowListener l)

Removes a listener to this workflow.

Parameters:

l - - the listener to be removed

getWorkflowListeners

public WorkflowListener[] getWorkflowListeners()

Returns the listeners to this workflow.

Returns:

- The listeners

clearWorkflowListeners

public void clearWorkflowListeners()

Removes all the listeners to this workflow.

fireWorkflowStart

public void fireWorkflowStart()

Calls the workflowStart() method of all the workflow listeners.

fireWorkflowSuspended

public void fireWorkflowSuspended()

Calls the workflowSuspended() method of all the workflow listeners.

fireWorkflowResumed

public void fireWorkflowResumed()

Calls the workflowResumed() method of all the workflow listeners.

fireWorkflowEnd

public void fireWorkflowEnd(int workflowStatus,
                            java.lang.Object workflowResult)

Calls the workflowEnd() method of all the workflow listeners.

Parameters:

workflowStatus - the workflow status

workflowResult - the workflow result

fireWorkflowAskForSuspension

public void fireWorkflowAskForSuspension()

Calls the workflowAskForSuspension() method of all the workflow listeners.

fireWorkflowAskForInterruption

public void fireWorkflowAskForInterruption()

Calls the workflowAskForInterruption() method of all the workflow listeners.

addWorkflowDefinitionListener

public void addWorkflowDefinitionListener(WorkflowDefinitionListener l)

Adds a definition listener to this workflow.

Parameters:

l - - new listener

removeWorkflowDefinitionListener

public void removeWorkflowDefinitionListener(WorkflowDefinitionListener l)

Removes a definition listener to this workflow.

Parameters:

l - - the listener to be removed

getWorkflowDefinitionListeners

public WorkflowDefinitionListener[] getWorkflowDefinitionListeners()

Returns the definition listeners to this workflow.

Returns:

- The listeners

clearWorkflowDefinitionListeners

public void clearWorkflowDefinitionListeners()

Removes all the definition listeners to this workflow.

fireElementAdded

public void fireElementAdded(Element element)

Calls the elementAdded() method of all the workflow listeners.

Parameters:

element - - added element

fireActionRemoved

public void fireActionRemoved(Action action,
                              int previousPosition)

Calls the elementRemoved() method of all the workflow listeners.

Parameters:

action - - removed action

previousPosition - the previous position

fireElementRemoved

public void fireElementRemoved(Element element)

Calls the elementRemoved() method of all the workflow listeners.

Parameters:

element - - removed element

fireActionMoved

public void fireActionMoved(Action action,
                            int previousPosition)

Calls the actionMoved() method of all the workflow listeners.

Parameters:

action - - added action

previousPosition - the previous position

fireWorkflowDefinitionNotification

public void fireWorkflowDefinitionNotification(WorkflowDefinitionNotification notification)

Calls the notificationReceived(WorkflowDefinitionEvent) method of all the workflow definition listeners.

Parameters:

notification - the notification

Since:

1.1.0

add

@Deprecated
public void add(int index,
                           Action action,
                           boolean useRecommendations)

Deprecated. since 1.1.0

Inserts the given action at the specified position in this workflow. Shifts the action currently at that position (if any) and any subsequent elements to the bottom (adds one to their indices).

Parameters:

index - - the index

action - - the action

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

See Also:

remove(int), add(Action, int)

add

@Deprecated
public void add(Action action,
                           int index,
                           boolean useRecommendations)

Deprecated. since 1.1.0

Inserts the specified action at the specified position in this workflow. This method is similar to add(int, Action).

Parameters:

action - - action to be added

index - - position

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

See Also:

remove(int), add(int, Action)

add

@Deprecated
public void add(java.lang.Class<? extends Action> actionClazz,
                           int position,
                           boolean useRecommendations)
         throws java.lang.IllegalArgumentException,
                java.lang.SecurityException,
                java.lang.InstantiationException,
                java.lang.IllegalAccessException,
                java.lang.reflect.InvocationTargetException,
                java.lang.NoSuchMethodException

Deprecated. since 1.1.0

Creates an instance of the Action class and add it to the workflow.

Parameters:

actionClazz - - Action class

position - - the position in the workflow

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

Throws:

java.lang.IllegalArgumentException - cannot create an instance of the given class.

java.lang.SecurityException - if a security exception occurs.

java.lang.InstantiationException - cannot create an instance of the given class.

java.lang.IllegalAccessException - cannot create an instance of the given class.

java.lang.reflect.InvocationTargetException - cannot create an instance of the given class.

java.lang.NoSuchMethodException - cannot create an instance of the given class.

See Also:

remove(Element), add(Element, boolean), add(Action, int, boolean)

add

@Deprecated
public boolean add(Element element,
                              boolean useRecommendations)

Deprecated. since 1.1.0

Adds an element (an Action or a Variable) to the workflow.

Parameters:

element - - element to be added

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

Returns:

true if the addition is successfull.

See Also:

remove(Element), add(Action, boolean), add(Variable)

add

@Deprecated
public boolean add(java.lang.Class<? extends Element> elementClazz,
                              boolean useRecommendations)
            throws java.lang.IllegalArgumentException,
                   java.lang.SecurityException,
                   java.lang.InstantiationException,
                   java.lang.IllegalAccessException,
                   java.lang.reflect.InvocationTargetException,
                   java.lang.NoSuchMethodException

Deprecated. since 1.1.0

Creates an instance of the Element class and add it to the workflow.

Parameters:

elementClazz - - Element class

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

Returns:

true if the addition is successfull.

Throws:

java.lang.IllegalArgumentException - cannot create an instance of the given class.

java.lang.SecurityException - if a security exception occurs.

java.lang.InstantiationException - cannot create an instance of the given class.

java.lang.IllegalAccessException - cannot create an instance of the given class.

java.lang.reflect.InvocationTargetException - cannot create an instance of the given class.

java.lang.NoSuchMethodException - cannot create an instance of the given class.

See Also:

remove(Element), add(Element, boolean), add(Action), add(Variable)

add

@Deprecated
public boolean add(Action action,
                              boolean useRecommendations)

Deprecated. since 1.1.0

Appends the specified action to the end of the workflow.

Parameters:

action - the action

useRecommendations - - defines if the warning messages associated to the element (if any) should be displayed.

Returns:

true if the addition is successful.

See Also:

remove(Element), add(Action, int, boolean), add(Element)