net.lucidviews.util
Class EnumValue

java.lang.Object
  net.lucidviews.util.EnumValue

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Properties.EnumParamMustExist, Strings.EnumValueMustBeValid

public abstract class EnumValue

extends java.lang.Object

implements java.io.Serializable

Base-class for defining an enumeration type.

To define an enumeration extend this class, implementing the getEnumeration method, and create instances for each value in your enumeration.
For example:
public class DistanceUnit extends EnumValue
{
// create a list for the enumeration values
public static final Enumeration ENUMERATION = new Enumeration();

// provide the EnumValue base class with access to the enumeration
public Enumeration getEnumeration()
{
return ENUMERATION;
}

// define the enumeration values
public static final DistanceUnit METRE = new DistanceUnit();
public static final DistanceUnit YARD = new DistanceUnit();
public static final DistanceUnit KILOMETRE = new DistanceUnit();
public static final DistanceUnit MILE = new DistanceUnit();

// make the constructor private to protect this enum
private DistanceUnit()
{
}
}
It is essential that all constructors of the class are protected or private so that no other instances can be created, which would extend your enumeration with values that you did not define. This includes the default constructor, which must be declared protected or private if you define no other constructor.
However, it is recommended that you assign a user-friendly text string to each of your enumeration values. To do this you will need to define a constructor in your enum class like this:
...
// define the enumeration values
public static final DistanceUnit METRE = new DistanceUnit( "metre" );
public static final DistanceUnit YARD = new DistanceUnit( "yard" );
public static final DistanceUnit KILOMETRE = new DistanceUnit( "kilometre" );
public static final DistanceUnit MILE = new DistanceUnit( "mile" );

// make the constructor private to protect this enum
private DistanceUnit( String unitName )
{
super( unitName );
}
...

The enumeration type is now ready to use. Using the enumeration type makes the source code more readable and ensures the compiler performs some type checking on parameter values.
For example, the method:
public void setDistanceUnit( int distanceUnit )
would become
public void setDistanceUnit( DistanceUnit newValue )
The primary advantage is that the newValue must be one of the constants defined by the DistanceUnit class - in the first interface, the distanceUnit could be any int value and the method would need to perform some range checks first and throw an exception. With enumerations the checks are done at compile time and no exception needs to be caught.

Enumeration values can be taken from the exported constants in the EnumValue sub class or derived from their index or user-friendly name.
For example, if a string value "mile" is read from a configuration file, the enumeration value can be looked-up:
String distanceUnitName = ...;
EnumValue distanceUnit = DistanceUnit.ENUMERATION.lookupValue( distanceUnitName );

IMPORTANT: use the == operator, not the equals method to evaluate or compare EnumValues.
The equals method performs an internal representation comparision and is provided so that string and integer values will match the text-value and index of an enumeration value.
Each enumeration value is a new, unique constant and should be compared directly. For example:
String distanceUnitName = ...;
EnumValue distanceUnit = DistanceUnit.ENUMERATION.lookupValue( distanceUnitName );
if (distanceUnit == DistanceUnit.MILE)
{
...
}

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.3 $

Author:

Stephen Battey

See Also:

Enumeration, Serialized Form

Field Summary

protected int	_index The index of this value within the enumeration.
protected boolean	_isCaseSensitive A flag indicating if the text value is case sensitive.
protected java.lang.String	_textValue The user-friendly name associated with this enumeration value.
protected static int	UNDEFINED_INDEX A value assigned to the index variable before the index of the enum value is known.

Constructor Summary

protected	EnumValue() Create an enumeration value with no user-friendly name.
protected	EnumValue(java.lang.String textValue) Create an enumeration value that can be identified by the given text.
protected	EnumValue(java.lang.String textValue, boolean isCaseSensitive) Create an enumeration value that can be identified by the given text.

Method Summary

boolean	equals(java.lang.Object obj)
abstract Enumeration	getEnumeration() Obtain the enumeration this value belongs to.
int	hashCode()
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

UNDEFINED_INDEX

protected static int UNDEFINED_INDEX

A value assigned to the index variable before the index of the enum value is known.

_textValue

protected java.lang.String _textValue

The user-friendly name associated with this enumeration value.

_isCaseSensitive

protected boolean _isCaseSensitive

A flag indicating if the text value is case sensitive.

_index

protected int _index

The index of this value within the enumeration.

Constructor Detail

EnumValue

protected EnumValue(java.lang.String textValue,
                    boolean isCaseSensitive)

Create an enumeration value that can be identified by the given text.

Parameters:

textValue - the String that is associated with this enum value

isCaseSensitive - indicates if a String should be associated with this enum value only if the case matches that in the text value

EnumValue

protected EnumValue(java.lang.String textValue)

Create an enumeration value that can be identified by the given text.
The text will not be treated as case sensitive.

Parameters:

textValue - the String that is associated with this enum value

EnumValue

protected EnumValue()

Create an enumeration value with no user-friendly name.
The value can then only be cross-referenced by its index.

Method Detail

getEnumeration

public abstract Enumeration getEnumeration()

Obtain the enumeration this value belongs to.
See the class JavaDoc, at the top of this page, for information on how to implement this method correctly.

Returns:

a list of enumeration values that this value is part of

toString

public java.lang.String toString()

hashCode

public int hashCode()

equals

public boolean equals(java.lang.Object obj)