Class  Tree  Index 
Amazing Mazes
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

Class Direction

java.lang.Object
  |
  +--Direction
public class Direction
extends java.lang.Object
implements java.io.Serializable

The Direction class simply encapsulates the enumerated states of valid directions (i.e. North, South, East, West, Retreat). Enumeration classes (like this one) are used throughout the code-base, even for a bi-state representation (that could alternatively be represented with a boolean). The reason for this is two fold:

  1. These classes are self-documenting. For example, you no longer have a method or constructor being invoked with a series of true/false values, lacking contextual description of what each boolean means.

  2. These classes easily support expansion to additional state values.

Symbolic constants are defined that enumerate the two states. For your convenience, each enumeration state has a pre-constructed object instance that you can use (this is possible because this class is immutable).

Direction objects are immutable, and support a partial canonical form ... namely equals() and toString(). Because of this, you may treat objects of this type in a very similar way that you treat atomic types.

All Direction constructors are private, supporting a controlled instantiation through the getInstance() static method. Because Direction objects are immutable, the pre-constructed instances can simply be re-used, representing an optimization ... limiting the number of Direction objects created to the number of possible states.

NOTE: Because the majority of this enumerator's behavior (API) is either constructors, static methods, or canoninacal methods, we conform to the API through policy only, not through an interface (out of 9 method, we could have only defined an interface which conformed to 3). It is really not possible (OR NECESSARY) to work with an enumerator in the abstract.

Version:
1.0 09/02/2000
Author:
Kevin Bridges ... Copyright (c) 2001
See Also:
Serialized Form

Field Summary
private static Direction[] allInstances_
          Inclusive list of all Direction instances (indexed by one of the constants defined in self).
private static Direction[] clockWiseDir_
          This array provides a translation to a clockwise direction.
private static Direction[] counterClockWiseDir_
          This array provides a translation to a counter-clockwise direction.
static Direction East
          Convenient pre-constructed East.
static int EAST
          Defined constant indicating "EAST".
static Direction Invalid
          Convenient pre-constructed Invalid object (i.e.
static int INVALID
          Defined constant indicating "INVALID" (i.e.
private  java.lang.String invalidState_
          The illegal value that was used, which ultimatly created an invalid enumeration instance (i.e.
static Direction North
          Convenient pre-constructed North.
static int NORTH
          Defined constant indicating "NORTH".
private static Direction[] oppositeDir_
          This array provides a translation to the opposite direction.
static Direction Retreat
          Convenient pre-constructed Retreat.
static int RETREAT
          Defined constant indicating "RETREAT" (i.e.
static Direction South
          Convenient pre-constructed South.
static int SOUTH
          Defined constant indicating "SOUTH".
private  int state_
          Self's direction indicator enumeration state.
private static java.lang.String[] stateDesc_
          Human readable inclusive list of all direction indicators (indexed by one of the constants defined in self).
static Direction Undefined
          Convenient pre-constructed Undefined object.
static int UNDEFINED
          Defined constant indicating "UNDEFINED", meaning that it was never initialized.
static Direction West
          Convenient pre-constructed West.
static int WEST
          Defined constant indicating "WEST".
 
Constructor Summary
private Direction(int state)
          Construct a "valid" Direction instance, initialized from the supplied state parameter.
private Direction(java.lang.String invalidState)
          Construct an "invalid" Direction instance, retaining the supplied unacceptable state.
 
Method Summary
(package private) static void ()
           
(package private) static void ()
           
(package private) static void ()
           
static Direction clockWiseDir(Direction direction)
          This static method will return the direction clockwise to the supplied parameter.
static Direction counterClockWiseDir(Direction direction)
          This static method will return the direction counter- clockwise to the supplied parameter.
 boolean equals(java.lang.Object obj)
          Compares two Objects for equality.
static Direction getInstance(int state)
          This static method will return the well-known pre-constructed Direction instance, initialized from the supplied integer state parameter.
static Direction getInstance(java.lang.String state)
          This static method will return the well-known pre-constructed Direction instance, initialized from the supplied integer state parameter.
static int getNumberOfStates()
          Return the total number of states defined in self.
 int getState()
          Return self's direction atomic enumeration state.
 java.lang.String getStateAsString()
          Return self's direction atomic enumeration state as a string.
static Direction oppositeDir(Direction direction)
          This static method will return the opposite direction of the supplied parameter.
 java.lang.String toString()
          Provide symbolic representation of self, supporting stream overloading.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait
 

Field Detail

INVALID

public static final int INVALID
Defined constant indicating "INVALID" (i.e. illegal). This indicates that an attempt was made to access an enumeration instance using an unacceptable state. This could represent a "hacker" attack, or a programing error. Any enumerator instance with an INVALID state_ will also have it's invalidState_ data member defined, retaining the unacceptable value.

UNDEFINED

public static final int UNDEFINED
Defined constant indicating "UNDEFINED", meaning that it was never initialized.

NORTH

public static final int NORTH
Defined constant indicating "NORTH".

SOUTH

public static final int SOUTH
Defined constant indicating "SOUTH".

EAST

public static final int EAST
Defined constant indicating "EAST".

WEST

public static final int WEST
Defined constant indicating "WEST".

RETREAT

public static final int RETREAT
Defined constant indicating "RETREAT" (i.e. go back).

stateDesc_

private static final java.lang.String[] stateDesc_
Human readable inclusive list of all direction indicators (indexed by one of the constants defined in self).

Invalid

public static final Direction Invalid
Convenient pre-constructed Invalid object (i.e. illegal). This indicates that an attempt was made to access an enumeration instance using an unacceptable state. This could represent a "hacker" attack, or a programing error. Because Invalid values utilize new instances, this instance is never really used, but simply serves as an array place-holder.

Undefined

public static final Direction Undefined
Convenient pre-constructed Undefined object. This indicates that the this enumeration was never initialized.

North

public static final Direction North
Convenient pre-constructed North.

South

public static final Direction South
Convenient pre-constructed South.

East

public static final Direction East
Convenient pre-constructed East.

West

public static final Direction West
Convenient pre-constructed West.

Retreat

public static final Direction Retreat
Convenient pre-constructed Retreat.

allInstances_

private static final Direction[] allInstances_
Inclusive list of all Direction instances (indexed by one of the constants defined in self).

state_

private int state_
Self's direction indicator enumeration state.

invalidState_

private java.lang.String invalidState_
The illegal value that was used, which ultimatly created an invalid enumeration instance (i.e. state_ of INVALID). This will be null, if state_ is not INVALID.

oppositeDir_

private static final Direction[] oppositeDir_
This array provides a translation to the opposite direction.

clockWiseDir_

private static final Direction[] clockWiseDir_
This array provides a translation to a clockwise direction.

counterClockWiseDir_

private static final Direction[] counterClockWiseDir_
This array provides a translation to a counter-clockwise direction.
Constructor Detail

Direction

private Direction(int state)
           throws java.lang.IllegalArgumentException
Construct a "valid" Direction instance, initialized from the supplied state parameter.

Note that all Direction constructors are private, supporting a controlled instantiation through the getInstance() static method. Because Direction objects are immutable, we can simply re-use the well known pre-constructed instances. 

 Logic Flow:
   1. Give control to our base class constructor.
   2. Validate that the supplied state parameter is acceptable.
   3. Retain the supplied state in self.
   Processing End (Direction(int))
Parameters:
state - the direction enumeration (use one of the constants defined in self).
Throws:
java.lang.IllegalArgumentException - an illegal state parameter was supplied ... you must use one of the constants defined in self.

Direction

private Direction(java.lang.String invalidState)
Construct an "invalid" Direction instance, retaining the supplied unacceptable state.

Note that all Direction constructors are private, supporting a controlled instantiation through the getInstance() static method.

Because the original invalid state must be retained for further evaluation, "invalid" objects are not re-used, but rather new ones created for each illegal attempt. 

 Logic Flow:
   1. Invoke our overloaded constructor, using an INVALID state.
   2. Retain our invalid state in self.
   Processing End (Direction(String))
Parameters:
invalidState - the illegal state that was attempted to be used in accessing a direction enumeration.
Method Detail

getInstance

public static Direction getInstance(int state)
This static method will return the well-known pre-constructed Direction instance, initialized from the supplied integer state parameter. Direction objects can be re-used because they are immutable. This method represents an optimization, limiting the number of Direction objects created to the number of possible states.

 Logic Flow:
   1. Return the pre-constructed Direction instance by
      indexing the supplied state parameter into the array of all
      well-known instances.
      NOTE: ArrayIndexOutOfBounds exceptions are interpreted as an
            invalid state parameter.
   Processing End (getInstance(int))
Parameters:
state - the direction enumeration (use one of the constants defined in self).
Returns:
the well-known pre-constructed Direction instance, initialized from the supplied state parameter.

getInstance

public static Direction getInstance(java.lang.String state)
This static method will return the well-known pre-constructed Direction instance, initialized from the supplied integer state parameter. Direction objects can be re-used because they are immutable. This method represents an optimization, limiting the number of Direction objects created to the number of possible states.

 Logic Flow:
   1. Special case, interpreting null strings or null references as
      Undefined.
   2. Return the pre-constructed Direction instance by interpreting
      the supplied state as an integer, and propogating this
      request to our overloaded method.
      NOTE: NumberFormatException exceptions are interpreted as an
            invalid state parameter, returning a new object instance
            with an INVALID state (retaining the unacceptable state).
   Processing End (getInstance(String))
Parameters:
state - a string representation of the direction enumeration.
Returns:
the well-known pre-constructed Direction instance, initialized from the supplied state parameter.

getState

public int getState()
Return self's direction atomic enumeration state.
Returns:
self's direction atomic enumeration state.

getStateAsString

public java.lang.String getStateAsString()
Return self's direction atomic enumeration state as a string. If self represents an invalid state, return that invalid state.
Returns:
self's direction atomic enumeration state as a string, or it's invalid state.

getNumberOfStates

public static int getNumberOfStates()
Return the total number of states defined in self. This can be used to pre-allocate a translation array, with the proper number of elements.
Returns:
the total number of states defined in self.

equals

public boolean equals(java.lang.Object obj)
Compares two Objects for equality. Returns a boolean that indicates whether self is equivalent to obj. 

 Logic Flow:
   1. If supplied object is not the correct type, we know it is not equal.
   2. Typecast the supplied obj, and compare it's internals to self.
   Processing End (equals)
Overrides:
equals in class java.lang.Object
Parameters:
obj - The Object to compare self with.
Returns:
true if obj is equivalent to self, otherwise false.

oppositeDir

public static Direction oppositeDir(Direction direction)
This static method will return the opposite direction of the supplied parameter.
Parameters:
direction - the direction to which to calculate it's opposite.
Returns:
the opposite direction of the supplied paramter.

clockWiseDir

public static Direction clockWiseDir(Direction direction)
This static method will return the direction clockwise to the supplied parameter.
Parameters:
direction - the direction from which to calculate a clockwise direction.
Returns:
the clockwise direction of the supplied paramter.

counterClockWiseDir

public static Direction counterClockWiseDir(Direction direction)
This static method will return the direction counter- clockwise to the supplied parameter.
Parameters:
direction - the direction from which to calculate a counter-clockwise direction.
Returns:
the counter-clockwise direction of the supplied paramter.

toString

public java.lang.String toString()
Provide symbolic representation of self, supporting stream overloading.
Overrides:
toString in class java.lang.Object
Returns:
string representation of self (example: "Direction(0:BUY)").

static void ()

static void ()

static void ()
 Class  Tree  Index 
Author: Andrew Bridges
Copyright © 2001
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD