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