gumbo.util.state
Interface StatePolicy

All Known Implementing Classes:
AbstractStatePolicy

public interface StatePolicy

An interface for imposing a policy for state value assurance and transition, with state values consisting of non-null "state flag" objects. State transition policy causes the state value to transit to a new state given the old state, a desired new state, and an input value. State assurance policy can be passive, with invalid state flag types and combinations throwing an exception, or it can be active, with invalid state values being coerced into valid ones.

Version:
$Revision: 1.2 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Method Summary
 void checkInitialState(java.util.Set newState, java.util.Set oldState)
          Called by the system to verify the new initial state value.
 void checkTransitState(java.util.Collection input, java.util.Set newState, java.util.Set oldState)
          Called by the system to transit the value of a state from its old value to a new value according to an input value.
 boolean isCompatible(StatePolicy policy)
          Called by the system to determine if some other state policy is compatible with this one, such as when adding a state value to a group of state values that should maintain a mutually consistent state.
 

Method Detail

isCompatible

public boolean isCompatible(StatePolicy policy)
Called by the system to determine if some other state policy is compatible with this one, such as when adding a state value to a group of state values that should maintain a mutually consistent state.

Parameters:
policy - Other state policy. None if null.
Returns:
True if the other policy (or the lack of a policy, if policy is null) is compatible with this one.

checkInitialState

public void checkInitialState(java.util.Set newState,
                              java.util.Set oldState)
Called by the system to verify the new initial state value. Should be called during state value construction and after any reset (re-initialization) operation. Will not be called in addition to transitState() (either the state is initializing or transiting).

Parameters:
newState - Reference to the new target state value (Object). Never null. Contains the initial state value and, upon return, the modified initial value. Must be mutable and must NOT loop back to this method.
oldState - The old state value (Object). Never null.

checkTransitState

public void checkTransitState(java.util.Collection input,
                              java.util.Set newState,
                              java.util.Set oldState)
Called by the system to transit the value of a state from its old value to a new value according to an input value. Will not be called in addition to initializeState() (either the state is initializing or transiting). Note that the transition can (but doesn't have to) be driven by the input value and the new state value.

Parameters:
input - Input value (Object). None if null (such as in a "set state" operation), which may be distinct from an empty value. If the same reference as state, may cause concurrent modification exceptions.
newState - Reference to the new target state value (Object). Contains the new state value and, upon return, the modified new value. Never null. Must be mutable and must NOT loop back to this method.
oldState - The old state value (Object). Never null.