Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang.enum
Class Enum

    java.lang.Object
      org.apache.commons.lang.enum.Enum

All Implemented Interfaces:
  java.lang.Comparable, java.io.Serializable

Direct Known Subclasses:
  ValuedEnum

Deprecated. Replaced by `org.apache.commons.lang.enums.Enum` and will be removed in version 3.0. All classes in this package are deprecated and repackaged to `org.apache.commons.lang.enums` since `enum` is a Java 1.5 keyword.

public abstract class Enum
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

Abstract superclass for type-safe enums.

One feature of the C programming language lacking in Java is enumerations. The C implementation based on ints was poor and open to abuse. The original Java recommendation and most of the JDK also uses int constants. It has been recognised however that a more robust type-safe class-based solution can be designed. This class follows the basic Java type-safe enumeration pattern.

NOTE:Due to the way in which Java ClassLoaders work, comparing Enum objects should always be done using `equals()`, not `==`. The equals() method will try == first so in most cases the effect is the same.

Of course, if you actually want (or don't mind) Enums in different class loaders being non-equal, then you can use `==`.

#### Simple Enums

To use this class, it must be subclassed. For example:

     public final class ColorEnum extends Enum {
       public static final ColorEnum RED = new ColorEnum("Red");
       public static final ColorEnum GREEN = new ColorEnum("Green");
       public static final ColorEnum BLUE = new ColorEnum("Blue");

       private ColorEnum(String color) {
         super(color);
       }

       public static ColorEnum getEnum(String color) {
         return (ColorEnum) getEnum(ColorEnum.class, color);
       }

       public static Map getEnumMap() {
         return getEnumMap(ColorEnum.class);
       }

       public static List getEnumList() {
         return getEnumList(ColorEnum.class);
       }

       public static Iterator iterator() {
         return iterator(ColorEnum.class);
       }
     }

As shown, each enum has a name. This can be accessed using `getName`.

The `getEnum` and `iterator` methods are recommended. Unfortunately, Java restrictions require these to be coded as shown in each subclass. An alternative choice is to use the `EnumUtils` class.

#### Subclassed Enums

A hierarchy of Enum classes can be built. In this case, the superclass is unaffected by the addition of subclasses (as per normal Java). The subclasses may add additional Enum constants of the type of the superclass. The query methods on the subclass will return all of the Enum constants from the superclass and subclass.

     public final class ExtraColorEnum extends ColorEnum {
       // NOTE: Color enum declared above is final, change that to get this
       // example to compile.
       public static final ColorEnum YELLOW = new ExtraColorEnum("Yellow");

       private ExtraColorEnum(String color) {
         super(color);
       }

       public static ColorEnum getEnum(String color) {
         return (ColorEnum) getEnum(ExtraColorEnum.class, color);
       }

       public static Map getEnumMap() {
         return getEnumMap(ExtraColorEnum.class);
       }

       public static List getEnumList() {
         return getEnumList(ExtraColorEnum.class);
       }

       public static Iterator iterator() {
         return iterator(ExtraColorEnum.class);
       }
     }

This example will return RED, GREEN, BLUE, YELLOW from the List and iterator methods in that order. The RED, GREEN and BLUE instances will be the same (==) as those from the superclass ColorEnum. Note that YELLOW is declared as a ColorEnum and not an ExtraColorEnum.

#### Functional Enums

The enums can have functionality by defining subclasses and overriding the `getEnumClass()` method:

       public static final OperationEnum PLUS = new PlusOperation();
       private static final class PlusOperation extends OperationEnum {
         private PlusOperation() {
           super("Plus");
         }
         public int eval(int a, int b) {
           return a + b;
         }
       }
       public static final OperationEnum MINUS = new MinusOperation();
       private static final class MinusOperation extends OperationEnum {
         private MinusOperation() {
           super("Minus");
         }
         public int eval(int a, int b) {
           return a - b;
         }
       }

       private OperationEnum(String color) {
         super(color);
       }

       public final Class getEnumClass() {     // NOTE: new method!
         return OperationEnum.class;
       }

       public abstract double eval(double a, double b);

       public static OperationEnum getEnum(String name) {
         return (OperationEnum) getEnum(OperationEnum.class, name);
       }

       public static Map getEnumMap() {
         return getEnumMap(OperationEnum.class);
       }

       public static List getEnumList() {
         return getEnumList(OperationEnum.class);
       }

       public static Iterator iterator() {
         return iterator(OperationEnum.class);
       }
     }

The code above will work on JDK 1.2. If JDK1.3 and later is used, the subclasses may be defined as anonymous.

#### Nested class Enums

Care must be taken with class loading when defining a static nested class for enums. The static nested class can be loaded without the surrounding outer class being loaded. This can result in an empty list/map/iterator being returned. One solution is to define a static block that references the outer class where the constants are defined. For example:

     public final class Outer {
       public static final BWEnum BLACK = new BWEnum("Black");
       public static final BWEnum WHITE = new BWEnum("White");

       // static nested enum class
       public static final class BWEnum extends Enum {

         static {
           // explicitly reference BWEnum class to force constants to load
           Object obj = Outer.BLACK;
         }

         // ... other methods omitted
       }
     }

Although the above solves the problem, it is not recommended. The best solution is to define the constants in the enum class, and hold references in the outer class:

     public final class Outer {
       public static final BWEnum BLACK = BWEnum.BLACK;
       public static final BWEnum WHITE = BWEnum.WHITE;

       // static nested enum class
       public static final class BWEnum extends Enum {
         // only define constants in enum classes - private if desired
         private static final BWEnum BLACK = new BWEnum("Black");
         private static final BWEnum WHITE = new BWEnum("White");

         // ... other methods omitted
       }
     }

For more details, see the 'Nested' test cases.

Since:
  1.0
Version:
  $Id: Enum.java 637362 2008-03-15 06:09:41Z bayard $
Author:
  Apache Avalon project, Stephen Colebourne, Chris Webb, Mike Bowler
See Also:
  `Enum`, Serialized Form

Field Summary
`protected java.lang.String` | `iToString` Deprecated. The toString representation of the Enum.

Constructor Summary
`protected` | `Enum(java.lang.String name)` Deprecated. Constructor to add a new named item to the enumeration.

Method Summary
`int` | `compareTo(java.lang.Object other)` Deprecated. Tests for order.
`boolean` | `equals(java.lang.Object other)` Deprecated. Tests for equality.
`protected static Enum` | `getEnum(java.lang.Class enumClass, java.lang.String name)` Deprecated. Gets an `Enum` object by class and name.
`java.lang.Class` | `getEnumClass()` Deprecated. Retrieves the Class of this Enum item, set in the constructor.
`protected static java.util.List` | `getEnumList(java.lang.Class enumClass)` Deprecated. Gets the `List` of `Enum` objects using the `Enum` class.
`protected static java.util.Map` | `getEnumMap(java.lang.Class enumClass)` Deprecated. Gets the `Map` of `Enum` objects by name using the `Enum` class.
`java.lang.String` | `getName()` Deprecated. Retrieve the name of this Enum item, set in the constructor.
`int` | `hashCode()` Deprecated. Returns a suitable hashCode for the enumeration.
`protected static java.util.Iterator` | `iterator(java.lang.Class enumClass)` Deprecated. Gets an `Iterator` over the `Enum` objects in an `Enum` class.
`protected java.lang.Object` | `readResolve()` Deprecated. Handle the deserialization of the class to ensure that multiple copies are not wastefully created, or illegal enum types created.
`java.lang.String` | `toString()` Deprecated. Human readable description of this Enum item.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### iToString

    protected transient java.lang.String iToString

  Deprecated.
  The toString representation of the Enum.

  Since:
    2.0

Constructor Detail

### Enum

    protected Enum(java.lang.String name)

  Deprecated.

  Constructor to add a new named item to the enumeration.

Parameters:
  `name` - the name of the enum object, must not be empty or `null`
Throws:
  `java.lang.IllegalArgumentException` - if the name is `null` or an empty string
  `java.lang.IllegalArgumentException` - if the getEnumClass() method returns a null or invalid Class

Method Detail

### readResolve

    protected java.lang.Object readResolve()

  Deprecated.

  Handle the deserialization of the class to ensure that multiple copies are not wastefully created, or illegal enum types created.

  Returns:
    the resolved object

### getEnum

    protected static Enum getEnum(java.lang.Class enumClass,
                                  java.lang.String name)

  Deprecated.

  Gets an `Enum` object by class and name.

  Parameters:
    `enumClass` - the class of the Enum to get, must not be `null`
    `name` - the name of the `Enum` to get, may be `null`
  Returns:
    the enum object, or `null` if the enum does not exist
  Throws:
    `java.lang.IllegalArgumentException` - if the enum class is `null`

### getEnumMap

    protected static java.util.Map getEnumMap(java.lang.Class enumClass)

  Deprecated.

  Gets the `Map` of `Enum` objects by name using the `Enum` class.

  If the requested class has no enum objects an empty `Map` is returned.

  Parameters:
    `enumClass` - the class of the `Enum` to get, must not be `null`
  Returns:
    the enum object Map
  Throws:
    `java.lang.IllegalArgumentException` - if the enum class is `null`
    `java.lang.IllegalArgumentException` - if the enum class is not a subclass of Enum

### getEnumList

    protected static java.util.List getEnumList(java.lang.Class enumClass)

  Deprecated.

  Gets the `List` of `Enum` objects using the `Enum` class.

  The list is in the order that the objects were created (source code order). If the requested class has no enum objects an empty `List` is returned.

  Parameters:
    `enumClass` - the class of the `Enum` to get, must not be `null`
  Returns:
    the enum object Map
  Throws:
    `java.lang.IllegalArgumentException` - if the enum class is `null`
    `java.lang.IllegalArgumentException` - if the enum class is not a subclass of Enum

### iterator

    protected static java.util.Iterator iterator(java.lang.Class enumClass)

  Deprecated.

  Gets an `Iterator` over the `Enum` objects in an `Enum` class.

  The `Iterator` is in the order that the objects were created (source code order). If the requested class has no enum objects an empty `Iterator` is returned.

  Parameters:
    `enumClass` - the class of the `Enum` to get, must not be `null`
  Returns:
    an iterator of the Enum objects
  Throws:
    `java.lang.IllegalArgumentException` - if the enum class is `null`
    `java.lang.IllegalArgumentException` - if the enum class is not a subclass of Enum

### getName

    public final java.lang.String getName()

  Deprecated.

  Retrieve the name of this Enum item, set in the constructor.

  Returns:
    the `String` name of this Enum item

### getEnumClass

    public java.lang.Class getEnumClass()

  Deprecated.

  Retrieves the Class of this Enum item, set in the constructor.

  This is normally the same as `getClass()`, but for advanced Enums may be different. If overridden, it must return a constant value.

  Returns:
    the `Class` of the enum
  Since:
    2.0

### equals

    public final boolean equals(java.lang.Object other)

  Deprecated.

  Tests for equality.

  Two Enum objects are considered equal if they have the same class names and the same names. Identity is tested for first, so this method usually runs fast.

  If the parameter is in a different class loader than this instance, reflection is used to compare the names.

  Parameters:
    `other` - the other object to compare for equality
  Returns:
    `true` if the Enums are equal

### hashCode

    public final int hashCode()

  Deprecated.

  Returns a suitable hashCode for the enumeration.

  Returns:
    a hashcode based on the name

### compareTo

    public int compareTo(java.lang.Object other)

  Deprecated.

  Tests for order.

  The default ordering is alphabetic by name, but this can be overridden by subclasses.

  If the parameter is in a different class loader than this instance, reflection is used to compare the names.

  Specified by:
    `compareTo` in interface `java.lang.Comparable`
  Parameters:
    `other` - the other object to compare to
  Returns:
    -ve if this is less than the other object, +ve if greater than, `0` of equal
  Throws:
    `java.lang.ClassCastException` - if other is not an Enum
    `java.lang.NullPointerException` - if other is `null`
  See Also:
    `Comparable.compareTo(Object)`

### toString

    public java.lang.String toString()

  Deprecated.

  Human readable description of this Enum item.

  Returns:
    String in the form `type[name]`, for example: `Color[Red]`. Note that the package name is stripped from the type name.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.