net.lucidviews.util
Class Enumeration<V extends EnumValue>

java.lang.Object
  net.lucidviews.util.Enumeration<V>

Type Parameters:

V - the type of value (EnumValue) stored in this enumeration

public class Enumeration<V extends EnumValue>
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.
These classes also provide the ability to define sub-lists. An EnumValue class can extend where one enumeration is an extension of another.

Since:

1.0

Version:

$Revision: 1.5.2.1 $

Author:

Stephen Battey

See Also:

EnumValue

Field Summary

protected Enumeration<? super V>	_superEnumeration The super enumeration - this enumeration is a sub-list within the super enumeration.
protected List<V>	_values The values in this enumeration.
protected static Enumeration	NO_SUPER_ENUMERATION Value assigned to the _superEnumeration variable when there is no super enumeration.

Constructor Summary

Enumeration()
Create an enumeration.

Enumeration(Enumeration<? super V> superEnumeration)
Create an enumeration.

Enumeration(Enumeration<? super V> 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(V value) Add a value to this enumeration.
boolean	equals(Object obj)
Class<V>	getType() Returns the type of enum value being stored in this enumeration.
protected String	getTypeString() Get the name of the type of object held in this enumeration.
int	hashCode()
boolean	isEmpty() Tests if this enumeration has no values.
ListIterator<? extends V>	listIterator() Returns an iterator of the values in this enumeration (in proper sequence).
V	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<? extends EnumValue<?>> enumType, String name) Returns the EnumValue of the specified enumeration type with the specified name.
V	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.

_superEnumeration

protected Enumeration<? super V extends EnumValue> _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 List<V extends EnumValue> _values

The values in this enumeration.

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<? super V> 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<? super V> superEnumeration)

Create an enumeration.

Parameters:

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

Since:

1.2

Method Detail

addValue

int addValue(V value)
       throws IllegalArgumentException,
              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:

IllegalArgumentException - invalid value for this enumeration

IllegalStateException - invalid value for this enumeration

lookupValue

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

getTypeString

protected String getTypeString()

Get the name of the type of object held in this enumeration.
This is an internal method used to construct debug/error messages. If handles the case where the type has not been defined (i.e. if getType() returns null).

Returns:

the type of object held in this enumeration

Since:

1.2

getType

public Class<V> 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<? extends V> 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 V 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<? extends EnumValue<?>> enumType,
                                   String name)
                            throws IllegalArgumentException,
                                   NullPointerException

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

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object