public class WorkflowState
extends java.lang.Object
Represents an activity's current state. The set of possible activity states is open-ended
with a few predefined and recognized by the framework states. States are defined as
symbolic constants through the makeStateConstant
. A state constant is defined
simply by giving it a name. Only one state constant is bound a given name and this is
ensured by this class. To obtain the state constant corresponding to a given name
use the toStateConstant
method. To obtain a mutable state instance (usually
associated with an activity), use the makeState
.
State constants are implemented by the derived WorkflowStateConstant
class
which is intended to be used in Java final
declarations only. Attempt to modify
a state constant will result in an exception.
It is possible to track changes in a mutable state instance by registering a StateListener
with it. Whenever the state changes, all listeners are invoked in the order in which they were
added and all attempts to change the state are blocked while the listeners are being executed. So,
a state listener can safely assume that the state remains constant while the listener is executing.
Predefined state constants must be used in implementations with the following defined semantics:
Limbo
: this is the initial state for newly created activities before they
have been initiated. An activity can have this state only at the peer that originally created it
and before it was actually initiated through the activity manager. It is impossible to explicitly
put an activity into this state.Started
: indicates that the activity has been initiated and is currently running.Completed
: indicates that an activity completed successfully, without exceptions.
Once an activity reaches this state, it is impossible to change it.Failed
: indicates that an activity failed with an exception.
Once an activity reaches this state, it is impossible to change it.Canceled
: indicates that an activity was explicitly canceled by the application.
Once an activity reaches this state, it is impossible to change it.Modifier and Type | Field and Description |
---|---|
static WorkflowStateConstant |
Canceled |
static WorkflowStateConstant |
Completed |
static WorkflowStateConstant |
Failed |
static WorkflowStateConstant |
Limbo |
protected java.util.List<StateListener> |
listeners |
protected java.util.concurrent.atomic.AtomicReference<java.lang.String> |
name |
static WorkflowStateConstant |
Started |
Modifier | Constructor and Description |
---|---|
protected |
WorkflowState(java.lang.String name) |
Modifier and Type | Method and Description |
---|---|
void |
addListener(StateListener l)
Add a state change listener.
|
void |
assign(WorkflowStateConstant newState)
Set a new state value.
|
boolean |
compareAndAssign(WorkflowStateConstant oldState,
WorkflowStateConstant newState)
Moves to a new state (newState) if the current state is equal to a given
state (oldState)
|
boolean |
equals(java.lang.Object x) |
WorkflowStateConstant |
getConst()
Return the state constant corresponding to the current state.
|
java.util.concurrent.Future<WorkflowStateConstant> |
getFuture(WorkflowStateConstant expected)
Return a
Future representing the task of this state reaching an expected
value. |
int |
hashCode() |
boolean |
isCanceled()
Return
true iff this object represents a Canceled
state. |
boolean |
isCompleted()
Return
true iff this object represents a Completed
state. |
boolean |
isFailed()
Return
true iff this object represents a Failed
state. |
boolean |
isFinished()
Finished means it is either completed, failed or canceled.
|
boolean |
isInLimbo()
Return
true iff this object represents a Limbo
state. |
boolean |
isStarted()
Return
true iff this object represents a Started
state - that is, it is neither in limbo nor finished. |
static WorkflowState |
makeState()
Return a new state initialized to
Limbo . |
static WorkflowState |
makeState(WorkflowStateConstant stateConstant)
Return a new state initialized from the passed in state constant.
|
static WorkflowStateConstant |
makeStateConstant(java.lang.String name)
Create a new custom state constant.
|
void |
removeListener(StateListener l)
Remove a previously added state change listener.
|
void |
setCanceled()
Assign the Canceled state constant to this object.
|
void |
setCompleted()
Assign the Completed state constant to this object.
|
void |
setFailed()
Assign the Failed state constant to this object.
|
void |
setStarted()
Assign the Started state constant to this object.
|
static WorkflowStateConstant |
toStateConstant(java.lang.String name)
Return the state constant with the given name.
|
java.lang.String |
toString() |
public static final WorkflowStateConstant Limbo
public static final WorkflowStateConstant Started
public static final WorkflowStateConstant Completed
public static final WorkflowStateConstant Failed
public static final WorkflowStateConstant Canceled
protected java.util.concurrent.atomic.AtomicReference<java.lang.String> name
protected java.util.List<StateListener> listeners
public static WorkflowStateConstant makeStateConstant(java.lang.String name)
Create a new custom state constant. The constants defined in this class represent states recognized by the framework and implementation are required to use them following their semantics. Additional intermediary states that an activity implementation may need however should be first declared as state constants through this method. State constants are maintained in a static constant pool where only one state constant with a given name may exist. This is unproblematic since states have only symbolic value and independently developed activities can safely share the same constant instances from the pool.
public static WorkflowStateConstant toStateConstant(java.lang.String name)
Return the state constant with the given name. The method will throw an exception if there's no such constant.
public static WorkflowState makeState(WorkflowStateConstant stateConstant)
Return a new state initialized from the passed in state constant.
public static WorkflowState makeState()
Return a new state initialized to Limbo
.
public WorkflowStateConstant getConst()
Return the state constant corresponding to the current state.
public boolean compareAndAssign(WorkflowStateConstant oldState, WorkflowStateConstant newState)
Moves to a new state (newState) if the current state is equal to a given state (oldState)
oldState
- The presumed current state.newState
- The new state.true
if the change was made and false
otherwise.an
- exception if this is a state constant.public void assign(WorkflowStateConstant newState)
Set a new state value.
newState
- an
- exception if this is a state constant.public java.util.concurrent.Future<WorkflowStateConstant> getFuture(WorkflowStateConstant expected)
Return a Future
representing the task of this state reaching an expected
value. The future will complete as soon as the state changes to the expected
parameter. One can use such a Future
to explicitly block and wait until
a certain state is reached.
expected
- The expected state.public void addListener(StateListener l)
Add a state change listener.
l
- A non null listener.public void removeListener(StateListener l)
Remove a previously added state change listener.
l
- A non null listener.public boolean isInLimbo()
Return true
iff this object represents a Limbo
state.
public boolean isStarted()
Return true
iff this object represents a Started
state - that is, it is neither in limbo nor finished.
public void setStarted()
Assign the Started state constant to this object.
public boolean isCompleted()
Return true
iff this object represents a Completed
state.
public void setCompleted()
Assign the Completed state constant to this object.
public boolean isFailed()
Return true
iff this object represents a Failed
state.
public void setFailed()
Assign the Failed state constant to this object.
public boolean isCanceled()
Return true
iff this object represents a Canceled
state.
public void setCanceled()
Assign the Canceled state constant to this object.
public boolean isFinished()
Finished means it is either completed, failed or canceled.
public int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object x)
equals
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object