com.dautelle.util
Class Enum

java.lang.Object
  java.lang.Number
      com.dautelle.util.Enum

All Implemented Interfaces:

java.lang.Comparable, java.io.Serializable

public abstract class Enum

extends java.lang.Number

implements java.io.Serializable, java.lang.Comparable

This class represents the base class for all enumerates; its semantic is somewhat similar to the new JDK Tiger enum base type, with some additional capabilities. In particular:

• The enumeration is extendable (if the constructor is not private). For example:

       public class Event {
           public static abstract class BaseId extends Enum {
               public static final Collection VALUES = getInstances(BaseId.class);
           }
       }
       public class MouseEvent extends Event {
           public static class Id extends BaseId {
               public static final Collection VALUES = getInstances(Id.class);
               public static final Id MOUSE_CLICKED = new Id();
               public static final Id MOUSE_PRESSED = new Id();
               public static final Id MOUSE_RELEASED = new Id();
           }
       }
       public class KeyEvent extends Event {
           public static class Id extends BaseId {
               public static final Collection VALUES = getInstances(Id.class);
               public static final Id KEY_PRESSED = new Id();
               public static final Id KEY_RELEASED = new Id();
           }
       }

• Enum's instances can be mapped to custom values (up to long) for use in switch statements, bit-wise sets (values power of 2) or look-up tables. Duplications (name or value) would result in exception thrown during initialization:

       public static final class Color extends Enum {
           public static final Collection VALUES = getInstances(Color.class);
           private Color(int value, String name)  { // Not extendable (private)
               super(value, name);
           }
           public static final int RED_VALUE = 0xFF0000;
           public static final Color RED = new Color(RED_VALUE, "red");
  
           public static final int GREEN_VALUE = 0x00FF00;
           public static final Color GREEN = new Color(GREEN_VALUE, "green");
  
           public static final int BLUE_VALUE = 0x0000FF;
           public static final Color BLUE = new Color(BLUE_VALUE, "blue");
       }
       ...
       Color color;
       switch (color.intValue()) {
           case Color.RED_VALUE:
           case Color.GREEN_VALUE:
           case Color.BLUE_VALUE:
       }
       

• Enum's hierarchies may exist, as Enum are not implicitly final. For example:

       public static class WeekDay extends Enum {
           public static final Collection VALUES = getInstances(WeekDay.class);
           public static final WeekDay SATURDAY = new WeekDay();
           public static final WeekDay SUNDAY = new WeekDay();
       }
       public static class WorkDay extends WeekDay {
           public static final Collection VALUES = getInstances(WorkDay.class);
           public static final WorkDay MONDAY = new WorkDay();
           public static final WorkDay TUESDAY = new WorkDay();
           public static final WorkDay WEDNESDAY = new WorkDay();
           public static final WorkDay THURSDAY = new WorkDay();
           public static final WorkDay FRIDAY = new WorkDay();
       }
       ...
       for (Iterator i = WorkDay.VALUES.iterator(); i.hasNext(); ) {
           // Iterates through the five workdays.
       }       
       for (Iterator i = WeekDay.VALUES.iterator(); i.hasNext(); ) {
           // Iterates through the seven weekdays.
       }

• Finally, this class does not require the latest JDK1.5+

Limitations: Unlike the JDK1.5 enum base type, instances of this class cannot be used directly in a switch statement. Although, for mapped's values (see Color example above) a switch on the enum's value is always possible. This approach is also faster as it does not require a "multiway if-statement" or "array indirection" (Ref. JDK 1.5 Enum: IV. Implementation Notes).

This class is public domain (not copyrighted).

Version:

5.3, December 10, 2003

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Constructor Summary

protected	Enum() Default constructor.
protected	Enum(long value) Creates an enumerate of specified value.
protected	Enum(long value, java.lang.String name) Creates an enumerate of specified value and specified name.
protected	Enum(java.lang.String name) Creates an enumerate of specified name.

Method Summary

protected java.lang.Object	clone() Throws CloneNotSupportedException.
int	compareTo(java.lang.Object o) Compares this enum with the specified object for order.
double	doubleValue() Returns this enum's value as a double.
float	floatValue() Returns this enum's value as a float.
protected static java.util.Collection	getInstances(java.lang.Class enumClass) Returns a read-only list of the specified enumeration.
java.lang.String	getName() Returns the unique name for this enum.
int	intValue() Returns this enum's value as a int.
long	longValue() Returns this enum's value as a long.
protected java.lang.Object	readResolve() Overrides readResolve() to support Serialization.
java.lang.String	toString() Returns a string representation of this enum.
static Enum	valueOf(java.lang.CharSequence name, java.lang.Class enumClass) Returns the enum with the specified name.
static Enum	valueOf(long value, java.lang.Class enumClass) Returns the enum with the specified value.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Enum

protected Enum()

Default constructor. The value of this enum is one more than the previous enum (starting at 0). This constructor is typically used for anonymous extendable enumerations (with value automatically assigned).

Throws:

java.lang.IllegalStateException - if an enum with same value already exists.

Enum

protected Enum(java.lang.String name)

Creates an enumerate of specified name. The value of this enum is one more than the previous enum (starting at 0). This constructor is typically used for extendable named enumerations (with value automatically assigned).

Parameters:

name - the name for this enum.

Throws:

java.lang.IllegalStateException - if an enum with same name or same value already exists.

Enum

protected Enum(long value)

Creates an enumerate of specified value. This constructor is typically used for non-extendable anonymous enumerations (e.g. masks with value power of 2).

Parameters:

value - the value for this enum.

Throws:

java.lang.IllegalStateException - if an enum with same value already exists.

Enum

protected Enum(long value,
               java.lang.String name)

Creates an enumerate of specified value and specified name. This constructor is typically used for enumeration usable in switch statements (e.g. state machine) with values being defined by public final static int/long constants.

Parameters:

value - the value for this enum.

name - the name for this enum.

Throws:

java.lang.IllegalStateException - if an enum with same name or same value already exists.

Method Detail

compareTo

public int compareTo(java.lang.Object o)

Compares this enum with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - the object to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this object.

getInstances

protected static java.util.Collection getInstances(java.lang.Class enumClass)

Returns a read-only list of the specified enumeration. The collection returned is backed by the actual collection of enums -- so it grows as more enums are defined. The iteration order of the collection returned is always the declarative order of the Enum regardless of their actual values. This method is typically used to export the constant VALUES as in

 public static Color extends Enum {
     public static final Collection VALUES = getInstances(Color.class);
     ... 
 }

Parameters:

enumClass - the enum class.

Returns:

an unmodifiable view of the enum collection.

valueOf

public static Enum valueOf(long value,
                           java.lang.Class enumClass)

Returns the enum with the specified value. This method also ensures that the specified class has been initialized.

Parameters:

value - the value of the enum to search for.

enumClass - the class of the enum to return.

Returns:

the enum with the specified value or null if not found.

valueOf

public static Enum valueOf(java.lang.CharSequence name,
                           java.lang.Class enumClass)

Returns the enum with the specified name. This method also ensures that the specified class has been initialized.

Parameters:

name - the name of the enum to search for.

enumClass - the class of the enum to return.

Returns:

the enum such as name.equals(enum.getName()) or null if not found.

intValue

public final int intValue()

Returns this enum's value as a int. This may involve rounding or truncation.

Returns:

the numeric value represented by this enum after conversion to type int.

longValue

public final long longValue()

Returns this enum's value as a long.

Returns:

the numeric value represented by this enum after conversion to type long.

floatValue

public final float floatValue()

Returns this enum's value as a float. This may involve rounding.

Returns:

the numeric value represented by this enum after conversion to type float.

doubleValue

public final double doubleValue()

Returns this enum's value as a double. This may involve rounding.

Returns:

the numeric value represented by this enum after conversion to type double.

getName

public final java.lang.String getName()

Returns the unique name for this enum. For anonymous enum, the name is constructed from the enum class and the declarative order of the enum within its class (e.g. Color#0 for the first declared color in the Color class).

Returns:

the name specified at construction or an unique name derived from the enum class name and its declarative order.

toString

public java.lang.String toString()

Returns a string representation of this enum.

Returns:

getName()

readResolve

protected java.lang.Object readResolve()
                                throws java.io.ObjectStreamException

Overrides readResolve() to support Serialization. Enum are uniquely identified by their name (independantly of their values to avoid class loading dependencies).

Returns:

the unique enum identified by the serialized name.

Throws:

java.io.ObjectStreamException - if the enum is not found.

See Also:

getName()

clone

protected final java.lang.Object clone()
                                throws java.lang.CloneNotSupportedException

Throws CloneNotSupportedException. This guarantees that enums are never cloned, which is necessary to preserve their "singleton" status.

Returns:

(never returns)

Throws:

java.lang.CloneNotSupportedException