Interface Step
-
- All Superinterfaces:
java.io.Serializable
- All Known Implementing Classes:
AbstractStep
,Decision
,PreSaveWikiPageTask
,SaveUserProfileTask
,SaveWikiPageTask
,SimpleDecision
,SimpleNotification
,Task
public interface Step extends java.io.Serializable
Discrete unit of work in a Workflow, such as a
Decision
or aTask
. Decisions require user input, while Tasks do not. All Steps, however, possess these properties:- actor: the Principal responsible for executing the Step; returned by
getActor()
. - availableOutcomes: a collection of possible "outcomes," such as "approve decision" (
Outcome.DECISION_APPROVE
), "reassign decision" (Outcome.DECISION_REASSIGN
), "abort step" (Outcome.STEP_ABORT
) and others. The range of possible Outcomes for the Step is returned bygetAvailableOutcomes()
; see the Outcome class for more details. - errors: an collection of Strings indicating errors returned by the Step. These values are returned by
getErrors()
. - started and completed: whether the Step has started/finished. These values are returned by
isStarted()
andisCompleted()
. - startTime and endTime: the time when the Step started and finished. These values are returned by
getStartTime()
andgetEndTime()
, respectively. - workflow: the parent Workflow.
Steps contain a
getMessageKey()
method that returns a key that can be used with theInternationalizationManager
. See alsoWorkflow.getMessageArguments()
, which is a convenience method that returns message arguments.- Since:
- 2.5
-
-
Field Summary
Fields Modifier and Type Field Description static java.util.Date
TIME_NOT_SET
Time value: the start or end time has not been set.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addSuccessor(Outcome outcome, Step step)
Adds a successor Step to this one, which will be triggered by a supplied Outcome.Outcome
execute(Context ctx)
Executes the processing for this Step and returns an Outcome indicating if it succeeded (Outcome.STEP_COMPLETE
orOutcome.STEP_ABORT
).java.security.Principal
getActor()
The Principal responsible for completing this Step, such as a system user or actor assigned to a Decision.java.util.Collection<Outcome>
getAvailableOutcomes()
Returns a Collection of available outcomes, such as "approve", "deny" or "reassign", in the order in which they were added viaaddSuccessor(Outcome, Step)
.java.util.Date
getEndTime()
The end time for this Step.java.util.List<java.lang.String>
getErrors()
Returns a List of error strings generated by this Step.java.lang.String
getMessageKey()
Message key for human-friendly name of this Step, including any parameter substitutions.Outcome
getOutcome()
Returns the Outcome of this Step's processing; by default,Outcome.STEP_CONTINUE
.java.util.Date
getStartTime()
The start time for this Step.Step
getSuccessor(Outcome outcome)
Identifies the next Step for a particular Outcome; if there is no next Step for this Outcome, this method returnsnull
.boolean
isCompleted()
Determines whether the Step is completed; if not, it is by definition awaiting action by the owner or in process.boolean
isStarted()
Determines whether the Step has started.void
setOutcome(Outcome outcome)
Sets the current Outcome for the step.void
setWorkflow(int workflowId, java.util.Map<java.lang.String,java.io.Serializable> workflowContext)
Sets the parent Workflow post-construction.void
start()
Starts the Step, and sets the start time to the moment when this method is first invoked.
-
-
-
Field Detail
-
TIME_NOT_SET
static final java.util.Date TIME_NOT_SET
Time value: the start or end time has not been set.
-
-
Method Detail
-
addSuccessor
void addSuccessor(Outcome outcome, Step step)
Adds a successor Step to this one, which will be triggered by a supplied Outcome. Implementations should respect the order in which Outcomes are added;getAvailableOutcomes()
should return them in the same order they were added.- Parameters:
outcome
- the Outcome triggering a particular successor Stepstep
- the Step to associated with this Outcomes (null
denotes no Steps)
-
getAvailableOutcomes
java.util.Collection<Outcome> getAvailableOutcomes()
Returns a Collection of available outcomes, such as "approve", "deny" or "reassign", in the order in which they were added viaaddSuccessor(Outcome, Step)
. Concrete implementations should always return a defensive copy of the outcomes, not the original backing collection.- Returns:
- the set of outcomes
-
getErrors
java.util.List<java.lang.String> getErrors()
Returns a List of error strings generated by this Step. If this Step generated no errors, this method returns a zero-length array.- Returns:
- the errors
-
execute
Outcome execute(Context ctx) throws WikiException
Executes the processing for this Step and returns an Outcome indicating if it succeeded (
Outcome.STEP_COMPLETE
orOutcome.STEP_ABORT
). Processing instructions can do just about anything, such as executing custom business logic or changing the Step's final outcome viasetOutcome(Outcome)
. A return value ofSTEP_COMPLETE
indicates that the instructions executed completely, without errors;STEP_ABORT
indicates that the Step and its parent Workflow should be aborted (that is, fail silently without error). If the execution step encounters any errors, it should throw a WikiException or a subclass.Note that successful execution of this methods does not necessarily mean that the Step is considered "complete"; rather, it just means that it has executed. Therefore, it is possible that
execute
could run multiple times.- Parameters:
ctx
- executing wiki context.- Returns:
- the result of the Step, expressed as an Outcome
- Throws:
WikiException
- if the step encounters errors while executing
-
getActor
java.security.Principal getActor()
The Principal responsible for completing this Step, such as a system user or actor assigned to a Decision.- Returns:
- the responsible Principal
-
getEndTime
java.util.Date getEndTime()
The end time for this Step. This value should be set when the step completes. ReturnsTIME_NOT_SET
if not completed yet.- Returns:
- the end time
-
getMessageKey
java.lang.String getMessageKey()
Message key for human-friendly name of this Step, including any parameter substitutions. By convention, the message prefix should be a lower-case version of the Step's type, plus a period (e.g.,task.
anddecision.
).- Returns:
- the message key for this Step.
-
getOutcome
Outcome getOutcome()
Returns the Outcome of this Step's processing; by default,Outcome.STEP_CONTINUE
.- Returns:
- the outcome
-
getStartTime
java.util.Date getStartTime()
The start time for this Step. ReturnsTIME_NOT_SET
if not started yet.- Returns:
- the start time
-
isCompleted
boolean isCompleted()
Determines whether the Step is completed; if not, it is by definition awaiting action by the owner or in process. If a Step has completed, it must also return a non-null
result forgetOutcome()
.- Returns:
true
if the Step has completed;false
if not.
-
isStarted
boolean isStarted()
Determines whether the Step has started.- Returns:
true
if the Step has started;false
if not.
-
start
void start() throws WikiException
Starts the Step, and sets the start time to the moment when this method is first invoked. If this Step has already been started, this method throws an IllegalStateException. If the Step cannot be started because the underlying implementation encounters an error, it the implementation should throw a WikiException.- Throws:
WikiException
- if the step encounters errors while starting
-
setOutcome
void setOutcome(Outcome outcome)
Sets the current Outcome for the step. If the Outcome is a "completion" Outcome, it should also sets the completon time and mark the Step as complete. Once a Step has been marked complete, this method cannot be called again. If the supplied Outcome is not in the set returned bygetAvailableOutcomes()
, or is notOutcome.STEP_CONTINUE
orOutcome.STEP_ABORT
, this method returns an IllegalArgumentException. If the caller attempts to set an Outcome and the Step has already completed, this method throws an IllegalStateException.- Parameters:
outcome
- whether the step should be considered completed
-
getSuccessor
Step getSuccessor(Outcome outcome)
Identifies the next Step for a particular Outcome; if there is no next Step for this Outcome, this method returnsnull
.- Parameters:
outcome
- the outcome- Returns:
- the next step
-
setWorkflow
void setWorkflow(int workflowId, java.util.Map<java.lang.String,java.io.Serializable> workflowContext)
Sets the parent Workflow post-construction. Should be called after building aStep
.- Parameters:
workflowId
- the parent workflow id to setworkflowContext
- the parent workflow context to set
-
-