Java Doc for Workflow.java in  » Wiki-Engine » JSPWiki » com » ecyrd » jspwiki » workflow » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Sequence of Step objects linked together. Workflows are always initialized with a message key that denotes the name of the Workflow, and a Principal that represents its owner.

Workflow lifecycle

• Workflow.CREATED : after the Workflow has been instantiated, but before it has been started using the Workflow.start() method.
• Workflow.RUNNING : after the Workflow has been started using the Workflow.start() method, but before it has finished processing all Steps. Note that a Workflow can only be started once; attempting to start it again results in an IllegalStateException. Callers can place the Workflow into the WAITING state by calling Workflow.waitstate() .
• Workflow.WAITING : when the Workflow has temporarily paused, for example because of a pending Decision. Once the responsible actor decides what to do, the caller can change the Workflow back to the RUNNING state by calling the Workflow.restart() method (this is done automatically by the Decision class, for instance, when the Decision.decide(Outcome) method is invoked)
• Workflow.COMPLETED : after the Workflow has finished processing all Steps, without errors.
• Workflow.ABORTED : if a Step has elected to abort the Workflow.

Steps and processing algorithm

Workflow Step objects can be of type Decision , Task or other Step subclasses. Decisions require user input, while Tasks do not. See the Step class for more details.

After instantiating a new Workflow (but before telling it to Workflow.start() ), calling classes should specify the first Step by executing the Workflow.setFirstStep(Step) method. Additional Steps can be chained by invoking the first step's Step.addSuccessor(OutcomeStep) method.

When a Workflow's start method is invoked, the Workflow retrieves the first Step and processes it. This Step, and subsequent ones, are processed as follows:

• The Step's Step.start method executes, which sets the start time.
• The Step's Step.execute method is called to begin processing, which will return an Outcome to indicate completion, continuation or errors:
• Outcome.STEP_COMPLETE indicates that the execution method ran without errors, and that the Step should be considered "completed."
• Outcome.STEP_CONTINUE indicates that the execution method ran without errors, but that the Step is not "complete" and should be put into the WAITING state.
• Outcome.STEP_ABORT indicates that the execution method encountered errors, and should abort the Step and the Workflow as a whole. When this happens, the Workflow will set the current Step's Outcome to Outcome.STEP_ABORT and invoke the Workflow's Workflow.abort() method. The Step's processing errors, if any, can be retrieved by Step.getErrors .
• The Outcome of the execute method also affects what happens next. Depending on the result (and assuming the Step did not abort), the Workflow will either move on to the next Step or put the Workflow into the Workflow.WAITING state:
• If the Outcome denoted "completion" (i.e., its Step.isCompleted method returns true) then the Step is considered complete; the Workflow looks up the next Step by calling the current Step's Step.getSuccessor(Outcome) method. If successor() returns a non-null Step, the return value is marked as the current Step and added to the Workflow's Step history. If successor() returns null, then the Workflow has no more Steps and it enters the Workflow.COMPLETED state.
• If the Outcome did not denote "completion" (i.e., its Step.isCompleted method returns false), then the Step still has further work to do. The Workflow enters the Workflow.WAITING state and stops further processing until a caller restarts it.

The currently executing Step can be obtained by Workflow.getCurrentStep() . The actor for the current Step is returned by Workflow.getCurrentActor() .

To provide flexibility for specific implementations, the Workflow class provides two additional features that enable Workflow participants (i.e., Workflow subclasses and Step/Task/Decision subclasses) to share context and state information. These two features are named attributes and message arguments:

• Named attributes are simple key-value pairs that Workflow participants can get or set. Keys are Strings; values can be any Object. Named attributes are set with Workflow.setAttribute(String,Object) and retrieved with Workflow.getAttribute(String) .
• Message arguments are used in combination with JSPWiki's com.ecyrd.jspwiki.i18n.InternationalizationManager to create language-independent user interface messages. The message argument array is retrieved via Workflow.getMessageArguments() ; the first two array elements will always be these: a String representing work flow owner's name, and a String representing the current actor's name. Workflow participants can add to this array by invoking Workflow.addMessageArgument(Object) .

Example

Workflow Steps can be very powerful when linked together. JSPWiki provides two abstract subclasses classes that you can use to build your own Workflows: Tasks and Decisions. As noted, Tasks are Steps that execute without user intervention, while Decisions require actors (aka Principals) to take action. Decisions and Tasks can be mixed freely to produce some highly elaborate branching structures.

Here is a simple case. For example, suppose you would like to create a Workflow that (a) executes a initialization Task, (b) pauses to obtain an approval Decision from a user in the Admin group, and if approved, (c) executes a "finish" Task. Here's sample code that illustrates how to do it:

 // Create workflow; owner is current user
 1  Workflow workflow = new Workflow("workflow.myworkflow", context.getCurrentUser());
 // Create custom initialization task
 2  Step initTask = new InitTask(this);
 // Create finish task
 3  Step finishTask = new FinishTask(this);
 // Create an intermediate decision step
 4  Principal actor = new GroupPrincipal("Admin");
 5  Step decision = new SimpleDecision(this, "decision.AdminDecision", actor);
 // Hook the steps together
 6  initTask.addSuccessor(Outcome.STEP_COMPLETE, decision);
 7  decision.addSuccessor(Outcome.DECISION_APPROVE, finishTask);
 // Set workflow's first step
 8  workflow.setFirstStep(initTask);
 

Some comments on the source code:

• Line 1 instantiates the workflow with a sample message key and designated owner Principal, in this case the current wiki user
• Lines 2 and 3 instantiate the custom Task subclasses, which contain the business logic
• Line 4 creates the relevant GroupPrincipal for the Admin group, who will be the actor in the Decision step
• Line 5 creates the Decision step, passing the Workflow, sample message key, and actor in the constructor
• Line 6 specifies that if the InitTask's Outcome signifies "normal completion" (STEP_COMPLETE), the SimpleDecision step should be invoked next
• Line 7 specifies that if the actor (anyone possessing the Admin GroupPrincipal) selects DECISION_APPROVE, the FinishTask step should be invoked
• Line 8 adds the InitTask (and all of its successor Steps, nicely wired together) to the workflow

Returns an array of message arguments, used by java.text.MessageFormat to create localized messages.

Returns an array of message arguments, used by java.text.MessageFormat to create localized messages. The first two array elements will always be these:

• String representing the name of the workflow owner (i.e., Workflow.getOwner() )
• String representing the name of the current actor (i.e., Workflow.getCurrentActor() ). If the current step is null because the workflow hasn't started or has already finished, the value of this argument will be a dash character (-)

Workflow and Step subclasses are free to append items to this collection with Workflow.addMessageArgument(Object) .