net.lucidviews.util
Class Enumeration

java.lang.Object
  net.lucidviews.util.Enumeration

public class Enumeration

extends Object

An enumerated list of values.
An enumeration is a finite set of distinct values.
Each value in an Enumeration is an instance of an EnumValue. Creating an enumeration simply requires you to create a sub-class of EnumValue - see the documentation of that class for more information.

Note: Java version 1.5 contains support for enum types. These classes (Enumeration and EnumValue) are provided to give backwards compatibiity with previous versions of Java.

Since:

1.0

Version:

$Revision: 1.6 $

Author:

Stephen Battey

See Also:

EnumValue

Field Summary

protected Class	_enumType The type of enumeration values.
protected Enumeration	_superEnumeration The super enumeration - this enumeration is a sub-list within the super enumeration.
protected ArrayList	_values The values in this enumeration.
protected static Enumeration	NO_SUPER_ENUMERATION Value assigned to the _superEnumeration variable when there is no super enumeration.
protected static Class	TYPE_NOT_DEFINED Value assigned to the __enumType variable when the type of value held in this enumeration has not yet been defined.

Constructor Summary

Enumeration()
Create an enumeration.

Enumeration(Enumeration superEnumeration)
Create an enumeration.

Enumeration(Enumeration superEnumeration, int initialCapacity)
Create an enumeration, specifying the number of values so that the enumeration list can be sized at creation, thereby improving performance.

Enumeration(int initialCapacity)
Create an enumeration, specifying the number of values so that the enumeration list can be sized at creation, thereby improving performance.

Method Summary

(package private) int	addValue(EnumValue value) Add a value to this enumeration.
boolean	equals(Object obj)
Class	getType() Returns the type of enum value being stored in this enumeration.
int	hashCode()
boolean	isEmpty() Tests if this enumeration has no values.
ListIterator	listIterator() Returns an iterator of the values in this enumeration (in proper sequence).
EnumValue	lookupValue(Object value) Lookup a value in this enumeration.
int	size() Returns the number of values in this enumeration.
Object[]	toArray() Returns an array containing all of the values in this enumeration in the correct order.
String	toString()
static EnumValue	valueOf(Class enumType, String name) Returns the EnumValue of the specified enumeration type with the specified name.
EnumValue	valueOf(String name) Lookup a value in this enumeration using its name.
EnumValue[]	values() Get the values of this enumeration.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NO_SUPER_ENUMERATION

protected static final Enumeration NO_SUPER_ENUMERATION

Value assigned to the _superEnumeration variable when there is no super enumeration.

TYPE_NOT_DEFINED

protected static final Class TYPE_NOT_DEFINED

Value assigned to the __enumType variable when the type of value held in this enumeration has not yet been defined.

_superEnumeration

protected Enumeration _superEnumeration

The super enumeration - this enumeration is a sub-list within the super enumeration. This variable is set to null if there is no super enumeration.

Since:

1.2

_values

protected ArrayList _values

The values in this enumeration.

_enumType

protected Class _enumType

The type of enumeration values.

Constructor Detail

Enumeration

public Enumeration(int initialCapacity)

Create an enumeration, specifying the number of values so that the enumeration list can be sized at creation, thereby improving performance.

Parameters:

initialCapacity - the expected number of values in this enumeration

Enumeration

public Enumeration()

Create an enumeration.

Enumeration

public Enumeration(Enumeration superEnumeration,
                   int initialCapacity)

Create an enumeration, specifying the number of values so that the enumeration list can be sized at creation, thereby improving performance.

Parameters:

superEnumeration - the enumeration this enumeration is a sub-list of

initialCapacity - the expected number of values in this enumeration

Since:

1.2

Enumeration

public Enumeration(Enumeration superEnumeration)

Create an enumeration.

Parameters:

superEnumeration - the enumeration this enumeration is a sub-list of

Since:

1.2

Method Detail

addValue

int addValue(EnumValue value)
       throws IllegalStateException

Add a value to this enumeration.
An enumeration may only hold values that are of the same type - i.e. instances of the same EnumValue class. Attempting to add a different type of value to the enumeration will result in an exception.
All values must be unique. Attempting to add a duplicate value will also result in an exception.

Enumerations are not editable once they have been created. This method should only be called from within the EnumValue class while the list of enumeration values is being built. Therefore this method has been given package scope to prevent the list being changed after it has been created.

Parameters:

value - enumeration value to be added to this list

Returns:

the index of where the value is stored in the enumeration list

Throws:

IllegalStateException - invalid value for this list

lookupValue

public EnumValue lookupValue(Object value)
                      throws NoSuchElementException

Lookup a value in this enumeration.
The value parameter can be any Object. The return value is always an EnumValue that is considered equal (using the equals method to compare values) to the specified value.
Thus, if the Enumeration contains an EnumValue with id 6 and string-value "yard":
lookupValue( "yard" );
lookupValue( new Integer( 6 ) );
will both return the EnumValue instance.

Parameters:

value - the value to find

Returns:

the matching enumeration value

Throws:

NoSuchElementException - the value could not be found

getType

public Class getType()

Returns the type of enum value being stored in this enumeration.
This will return null if no values have been added to this enumeration list.

Returns:

the type of this enumeration

size

public int size()

Returns the number of values in this enumeration.

Returns:

the number of values in this enumeration

isEmpty

public boolean isEmpty()

Tests if this enumeration has no values.

Returns:

true if no values have been defined in this enuemration; false otherwise

toArray

public Object[] toArray()

Returns an array containing all of the values in this enumeration in the correct order.

Returns:

an array containing all of the elements in this list in the correct order

listIterator

public ListIterator listIterator()

Returns an iterator of the values in this enumeration (in proper sequence).

Returns:

an iterator of the enumeration values (EnumValues)

See Also:

EnumValue

values

public EnumValue[] values()

Get the values of this enumeration.

Returns:

an array of enumeration values

Since:

1.2

valueOf

public EnumValue valueOf(String name)
                  throws IllegalArgumentException

Lookup a value in this enumeration using its name.

Parameters:

name - the name of the enumeration value

Returns:

the enumeration value with the given name

Throws:

IllegalArgumentException - if there is no value with the specified name

Since:

1.2

valueOf

public static EnumValue valueOf(Class enumType,
                                String name)
                         throws IllegalArgumentException

Returns the EnumValue of the specified enumeration type with the specified name. The name must match with the text value of the enum value. (Extraneous whitespace characters are not permitted.)

Parameters:

enumType - the Class object of the EnumValue from which to return a constant

name - the text value of the enum value to return

Returns:

the EnumValue from the specified enumeration type with the specified name

Throws:

IllegalArgumentException - if the specified enumeration class has no constant with the specified name, or the specified class does not represent an enum type

NullPointerException - if enumType or name is null

Since:

1.2

toString

public String toString()

hashCode

public int hashCode()

equals

public boolean equals(Object obj)