Package org.apache.wiki.workflow

# Class Decision

java.lang.Object
org.apache.wiki.workflow.AbstractStep
org.apache.wiki.workflow.Decision

All Implemented Interfaces:
  `Serializable`, `Step`

Direct Known Subclasses:
  `SimpleDecision`, `SimpleNotification`

public abstract class Decision extends AbstractStep

AbstractStep subclass that asks an actor Principal to choose an Outcome on behalf of an owner (also a Principal). The actor "makes the decision" by calling the `decide(Outcome, Context)` method. When this method is called, it will set the Decision's Outcome to the one supplied. If the parent Workflow is in the `Workflow.WAITING` state, it will be re-started. Any checked WikiExceptions thrown by the workflow after re-start will be re-thrown to callers.

When a Decision completes, its `AbstractStep.isCompleted()` method returns `true`. It also tells its parent WorkflowManager to remove it from the list of pending tasks by calling `DecisionQueue.remove(Decision)`.

To enable actors to choose an appropriate Outcome, Decisions can store arbitrary key-value pairs called "facts." These facts can be presented by the user interface to show details the actor needs to know about. Facts are added by calling classes to the Decision, in order of expected presentation, by the `addFact(Fact)` method. They can be retrieved, in order, via `getFacts()`.

Since:
  2.5
See Also:
  - Serialized Form

## Field Summary

### Fields inherited from interface org.apache.wiki.workflow.Step

`TIME_NOT_SET`

## Constructor Summary

Constructors
Constructor
Description
`Decision(int workflowId, Map<String,Serializable> workflowContext, String messageKey, Principal actor, Outcome defaultOutcome)`
Constructs a new Decision for a required "actor" Principal, having a default Outcome.

## Method Summary

Modifier and Type
Method
Description
`final void`
`addFact(Fact fact)`
Appends a Fact to the list of Facts associated with this Decision.
`void`
`decide(Outcome outcome, Context context)`
Sets this Decision's outcome, and restarts the parent Workflow if it is in the `Workflow.WAITING` state and this Decision is its currently active Step.
`Outcome`
`execute(Context context)`
Default implementation that always returns `Outcome.STEP_CONTINUE` if the current Outcome isn't a completion (which will be true if the `decide(Outcome, Context)` method hasn't been executed yet.
`final Principal`
`getActor()`
The Principal responsible for completing this Step, such as a system user or actor assigned to a Decision.
`Outcome`
`getDefaultOutcome()`
Returns the default or suggested outcome, which must be one of those returned by `AbstractStep.getAvailableOutcomes()`.
`final List<Fact>`
`getFacts()`
Returns the Facts associated with this Decision, in the order in which they were added.
`final int`
`getId()`
Returns the unique identifier for this Decision.
`boolean`
`isReassignable()`
Returns `true` if the Decision can be reassigned to another actor.
`final void`
`reassign(Principal actor)`
Reassigns the Decision to a new actor (that is, provide an outcome).
`final void`
`setId(int id)`
Sets the unique identfier for this Decision.

### Methods inherited from class org.apache.wiki.workflow.AbstractStep

`addError, addSuccessor, getAvailableOutcomes, getEndTime, getErrors, getMessageKey, getOutcome, getStartTime, getSuccessor, getWorkflowContext, getWorkflowId, isCompleted, isStarted, setOutcome, setWorkflow, start`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### Decision

public Decision(int workflowId, Map<String,Serializable> workflowContext, String messageKey, Principal actor, Outcome defaultOutcome)
Constructs a new Decision for a required "actor" Principal, having a default Outcome.

Parameters:
  `workflowId` - the parent workflow id to set
  `workflowContext` - the parent workflow context to set
  `messageKey` - the i18n message key that represents the message the actor will see
  `actor` - the Principal (e.g., a WikiPrincipal, Role, GroupPrincipal) who is required to select an appropriate Outcome
  `defaultOutcome` - the Outcome that the user interface will recommend as the default choice

## Method Details

### addFact

public final void addFact(Fact fact)
Appends a Fact to the list of Facts associated with this Decision.

Parameters:
  `fact` - the new fact to add

### decide

public void decide(Outcome outcome, Context context) throws WikiException

Sets this Decision's outcome, and restarts the parent Workflow if it is in the `Workflow.WAITING` state and this Decision is its currently active Step. Any checked WikiExceptions thrown by the workflow after re-start will be re-thrown to callers.

This method cannot be invoked if the Decision is not the current Workflow step; all other invocations will throw an IllegalStateException. If the Outcome supplied to this method is one one of the Outcomes returned by `AbstractStep.getAvailableOutcomes()`, an IllegalArgumentException will be thrown.

Parameters:
  `outcome` - the Outcome of the Decision
  `context` - wiki context of the Decision
Throws:
  `WikiException` - if the act of restarting the Workflow throws an exception

### execute

public Outcome execute(Context context) throws WikiException
Default implementation that always returns `Outcome.STEP_CONTINUE` if the current Outcome isn't a completion (which will be true if the `decide(Outcome, Context)` method hasn't been executed yet. This method will also add the Decision to the associated DecisionQueue.

Specified by:
  `execute` in interface `Step`
Specified by:
  `execute` in class `AbstractStep`
Parameters:
  `context` - executing wiki context.
Returns:
  the Outcome of the execution
Throws:
  `WikiException` - never

### getActor

public final Principal getActor()
The Principal responsible for completing this Step, such as a system user or actor assigned to a Decision.

Specified by:
  `getActor` in interface `Step`
Specified by:
  `getActor` in class `AbstractStep`
Returns:
  the responsible Principal

### getDefaultOutcome

public Outcome getDefaultOutcome()
Returns the default or suggested outcome, which must be one of those returned by `AbstractStep.getAvailableOutcomes()`. This method is guaranteed to return a non-`null` Outcome.

Returns:
  the default outcome.

### getFacts

public final List<Fact> getFacts()
Returns the Facts associated with this Decision, in the order in which they were added.

Returns:
  the list of Facts

### getId

public final int getId()
Returns the unique identifier for this Decision. Normally, this ID is programmatically assigned when the Decision is added to the DecisionQueue.

Returns:
  the identifier

### isReassignable

public boolean isReassignable()
Returns `true` if the Decision can be reassigned to another actor. This implementation always returns `true`.

Returns:
  the result

### reassign

public final void reassign(Principal actor)
Reassigns the Decision to a new actor (that is, provide an outcome). If the Decision is not reassignable, this method throws an IllegalArgumentException.

Parameters:
  `actor` - the actor to reassign the Decision to

### setId

public final void setId(int id)
Sets the unique identfier for this Decision.

Parameters:
  `id` - the identifier