bb.util
Class State

java.lang.Object
  extended by bb.util.State

public class State
extends Object

This class is meant to represent named states. An instance is constructed with an array of all possible states that it can be in, and it can be assigned any state in this array by various method calls. It is useful for writing simple software state machines.

This class is multithread safe: all public methods are synchronized.

Author:
Brent Boyer

Field Summary
protected  int index
           
protected  String[] states
          Contract: is never null, zero length, contains a blank element, or contains duplicate elements.
 
Constructor Summary
State(String[] states)
           
State(String[] states, int index)
           
 
Method Summary
 void decrement()
          Moves to the previous state (wrapping around to the end of the states array if are currently at beginning).
protected  int findIndex(String state)
          Returns the index of the element within states which equals state, else returns -1 if no such element exists.
 String get()
          Returns the current state.
 String[] getStates()
          Returns a clone of all the potential states of this State instance.
 void increment()
          Moves to the next state (wrapping around to the beginning of the states array if are currently at end).
 boolean is(String state)
          Returns whether or not state equals this instance's current state.
 boolean knows(String state)
          Returns whether or not this instance knows of state as a valid state that it can reach.
 void set(int indexNew)
          Adjusts the internal index to the specified index, which changes the state to the one at that index.
 void set(String state)
          Moves to the specified state.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

states

protected final String[] states
Contract: is never null, zero length, contains a blank element, or contains duplicate elements.


index

protected int index
Constructor Detail

State

public State(String[] states)
      throws IllegalArgumentException
Throws:
IllegalArgumentException

State

public State(String[] states,
             int index)
      throws IllegalArgumentException
Throws:
IllegalArgumentException
Method Detail

toString

public String toString()
Overrides:
toString in class Object

knows

public boolean knows(String state)
Returns whether or not this instance knows of state as a valid state that it can reach.


is

public boolean is(String state)
Returns whether or not state equals this instance's current state.


get

public String get()
Returns the current state.


getStates

public String[] getStates()
Returns a clone of all the potential states of this State instance.


set

public void set(int indexNew)
         throws IllegalArgumentException
Adjusts the internal index to the specified index, which changes the state to the one at that index.

This is the fundamental state changing method. Subclasses may override in order to enforce custom state transition rules.

Throws:
IllegalArgumentException - if indexNew is not a valid value

set

public void set(String state)
         throws IllegalArgumentException
Moves to the specified state.

Throws:
IllegalArgumentException - if state is not a valid state for this State instance

increment

public void increment()
Moves to the next state (wrapping around to the beginning of the states array if are currently at end).


decrement

public void decrement()
Moves to the previous state (wrapping around to the end of the states array if are currently at beginning).


findIndex

protected int findIndex(String state)
Returns the index of the element within states which equals state, else returns -1 if no such element exists.