gumbo.util.state
Class AbstractStateSet

java.lang.Object
  |
  +--gumbo.util.state.AbstractStateSet
All Implemented Interfaces:
java.util.Collection, java.util.Set, StateSet
Direct Known Subclasses:
AbstractInteractorState

public class AbstractStateSet
extends java.lang.Object
implements StateSet

A full implementation of the StateSet interface. Uses the decorator pattern to optionally wrap a target set.

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

Constructor Summary
AbstractStateSet()
          Creates an instance, with an empty HashSet and no state policy.
AbstractStateSet(java.util.Collection init)
          Creates an instance, with an initialized HashSet and no state policy.
AbstractStateSet(java.util.Collection init, StatePolicy policy)
          Creates an instance, with an initialized HashSet, as allowed by the policy, and a state policy.
AbstractStateSet(java.util.Collection init, StatePolicy policy, java.util.Set target)
          Creates an instance, with an external target set and a state policy.
 
Method Summary
 boolean add(java.lang.Object o)
           
 boolean addAll(java.util.Collection c)
           
 boolean change(java.lang.Object remove, java.lang.Object add)
          Removes then adds the specified state flags, as allowed by the state policy.
 boolean change(StateSet changes)
          Performs a "masked change" by imposing a target's state set changes (deltas) on this state set, as allowed by the state policy, with the union of the target's old and new states acting as the mask.
 boolean changeAll(java.util.Collection remove, java.util.Collection add)
          Removes then adds the specified state flags, as allowed by the state policy.
 void clear()
           
 boolean contains(java.lang.Object o)
           
 boolean containsAll(java.util.Collection c)
           
 boolean equals(java.lang.Object obj)
           
 java.util.Set getOldState()
          Gets a singleton immutable view of this set's old state value, which was the state value prior to the last transit, or the same state value as the current one after a reset.
 StatePolicy getStatePolicy()
          Gets the state policy for this state set, which assures that the state value contains valid combinations and types of state flags following state initialization and transition.
 StateSet getStateSet()
          Gets a singleton immutable view of this set, which is the current state value, resulting from the last reset or transit.
 int hashCode()
           
 boolean isEmpty()
           
 java.util.Iterator iterator()
          Returns an immutable iterator.
 boolean remove(java.lang.Object o)
           
 boolean removeAll(java.util.Collection c)
           
 boolean reset(java.util.Collection state)
          Resets (re-initializes) this state set's value to a new state, as allowed by the state policy.
 boolean retainAll(java.util.Collection c)
           
 boolean set(java.util.Collection state)
          Sets this state set's value to a new state, as allowed by the state policy.
 int size()
           
protected  void stateReset()
          Called by the system after this state value is reset, even if the value did not change.
protected  void stateTransit()
          Called by the system after this state value is transited, even if the value did not change.
 java.lang.Object[] toArray()
           
 java.lang.Object[] toArray(java.lang.Object[] a)
           
 java.lang.String toString()
           
 boolean transit(java.util.Collection input)
          Causes this state set's value to transit from one state to another (possibly with no change in value) according to an input value.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractStateSet

public AbstractStateSet()
Creates an instance, with an empty HashSet and no state policy.


AbstractStateSet

public AbstractStateSet(java.util.Collection init)
Creates an instance, with an initialized HashSet and no state policy.

Parameters:
init - Initial state value. None if null.

AbstractStateSet

public AbstractStateSet(java.util.Collection init,
                        StatePolicy policy)
Creates an instance, with an initialized HashSet, as allowed by the policy, and a state policy.

Parameters:
init - Initial state value. None if null.
policy - The state policy for this state set. None if null.

AbstractStateSet

public AbstractStateSet(java.util.Collection init,
                        StatePolicy policy,
                        java.util.Set target)
Creates an instance, with an external target set and a state policy. If init is non-null, the target will be initialized with it. If init is null and target is not, the target initial value is used. In any case, the initial value will be subject to the state policy. Master constructor.

Parameters:
init - Initial state value. None if null.
policy - The state policy for this state set. None if null.
target - The target of this wrapper. If null, defaults to an internal HashSet.
Method Detail

stateReset

protected void stateReset()
Called by the system after this state value is reset, even if the value did not change. Default implementation does nothing.


stateTransit

protected void stateTransit()
Called by the system after this state value is transited, even if the value did not change. Default implementation does nothing.


getStatePolicy

public StatePolicy getStatePolicy()
Description copied from interface: StateSet
Gets the state policy for this state set, which assures that the state value contains valid combinations and types of state flags following state initialization and transition.

Specified by:
getStatePolicy in interface StateSet
Returns:
The policy. Null if none.

reset

public boolean reset(java.util.Collection state)
Description copied from interface: StateSet
Resets (re-initializes) this state set's value to a new state, as allowed by the state policy. Unlike other mutators, the old state will be left equal to the new state. If there is no policy, this state set will be effectively cleared and the new state added. If reset is not allowed, should throw UnsupportedOperationException.

Specified by:
reset in interface StateSet
Parameters:
state - The new state value (Object). Never null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

set

public boolean set(java.util.Collection state)
Description copied from interface: StateSet
Sets this state set's value to a new state, as allowed by the state policy. Effectively a clear() then addAll(), as a single operation.

Specified by:
set in interface StateSet
Parameters:
state - The new state value (Object). Never null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

change

public boolean change(StateSet changes)
Description copied from interface: StateSet
Performs a "masked change" by imposing a target's state set changes (deltas) on this state set, as allowed by the state policy, with the union of the target's old and new states acting as the mask. Effectively a removeAll() of the target's old state, then an addAll() of its new state, as a single operation.

Specified by:
change in interface StateSet
Parameters:
changes - The state value changes. Never null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

change

public boolean change(java.lang.Object remove,
                      java.lang.Object add)
Description copied from interface: StateSet
Removes then adds the specified state flags, as allowed by the state policy. Effectively a remove() then add(), as a single operation.

Specified by:
change in interface StateSet
Parameters:
remove - Flag to be removed. None if null.
add - Flag to be added. None if null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

changeAll

public boolean changeAll(java.util.Collection remove,
                         java.util.Collection add)
Description copied from interface: StateSet
Removes then adds the specified state flags, as allowed by the state policy. Effectively a removeAll() then addAll(), as a single operation.

Specified by:
changeAll in interface StateSet
Parameters:
remove - Flags to be removed. Never null.
add - Flags to be added. Never null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

transit

public boolean transit(java.util.Collection input)
Description copied from interface: StateSet
Causes this state set's value to transit from one state to another (possibly with no change in value) according to an input value. If there is no policy nothing happens.

Specified by:
transit in interface StateSet
Parameters:
input - The input value (Object). Never null.
Returns:
True if the contents of this set changed (same as for Set.add() and Set.remove()).

getOldState

public java.util.Set getOldState()
Description copied from interface: StateSet
Gets a singleton immutable view of this set's old state value, which was the state value prior to the last transit, or the same state value as the current one after a reset.

Specified by:
getOldState in interface StateSet
Returns:
The view (Object). Never null.

getStateSet

public StateSet getStateSet()
Description copied from interface: StateSet
Gets a singleton immutable view of this set, which is the current state value, resulting from the last reset or transit.

Specified by:
getStateSet in interface StateSet
Returns:
The view (Object). Never null.

add

public boolean add(java.lang.Object o)
Specified by:
add in interface java.util.Set

remove

public boolean remove(java.lang.Object o)
Specified by:
remove in interface java.util.Set

addAll

public boolean addAll(java.util.Collection c)
Specified by:
addAll in interface java.util.Set

removeAll

public boolean removeAll(java.util.Collection c)
Specified by:
removeAll in interface java.util.Set

clear

public void clear()
Specified by:
clear in interface java.util.Set

retainAll

public boolean retainAll(java.util.Collection c)
Specified by:
retainAll in interface java.util.Set

iterator

public java.util.Iterator iterator()
Returns an immutable iterator.

Specified by:
iterator in interface java.util.Set

size

public int size()
Specified by:
size in interface java.util.Set

contains

public boolean contains(java.lang.Object o)
Specified by:
contains in interface java.util.Set

containsAll

public boolean containsAll(java.util.Collection c)
Specified by:
containsAll in interface java.util.Set

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface java.util.Set

toArray

public java.lang.Object[] toArray()
Specified by:
toArray in interface java.util.Set

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)
Specified by:
toArray in interface java.util.Set

equals

public boolean equals(java.lang.Object obj)
Specified by:
equals in interface java.util.Set
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Specified by:
hashCode in interface java.util.Set
Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object