gumbo.util.state
Interface StateSet

All Superinterfaces:

java.util.Collection, java.util.Set

All Known Subinterfaces:

InteractorState

All Known Implementing Classes:

AbstractInteractorState, AbstractStateSet, Interactors.ImmutableInteractorState, States.ImmutableStateSet

public interface StateSet

extends java.util.Set

A set representing a state value containing none or more non-null "state flag" objects. The contents of the set (flag types and combinations) and its state transitions are ruled by a state policy. State set mutators work as expected, clearing, adding, and removing elements from this set, but as mediated by the state policy for state transit, if any. Also, null elements are not allowed in the set. Mutators with a null object parameter should perform a state transition but silently ignore the null element (do not add or remove it from the set). If the state policy implements a classic finite state machine, with transitions driven only by current state and inputs, implementations should consider throwing UnsupportedOperationException for all mutators except reset() and transit().

The identity (equals(), hashCode()) of a state set is that of a Set. This may be unsatisfactory in situations requiring equality of the state sets's current and old state, in which case both states must be tested for equality.

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Method Summary

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.
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.
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	set(java.util.Collection state) Sets this state set's value to a new state, as allowed by the state policy.
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 interface java.util.Set

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

getStatePolicy

public 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.

Returns:

The policy. Null if none.

reset

public boolean reset(java.util.Collection state)

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.

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)

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.

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)

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.

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)

Removes then adds the specified state flags, as allowed by the state policy. Effectively a remove() then add(), as a single operation.

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)

Removes then adds the specified state flags, as allowed by the state policy. Effectively a removeAll() then addAll(), as a single operation.

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)

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.

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()).

getStateSet

public StateSet getStateSet()

Gets a singleton immutable view of this set, which is the current state value, resulting from the last reset or transit.

Returns:

The view (Object). Never null.

getOldState

public 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.

Returns:

The view (Object). Never null.