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.enums
Class ValuedEnum

    java.lang.Object
      org.apache.commons.lang.enums.Enum
          org.apache.commons.lang.enums.ValuedEnum

All Implemented Interfaces:
  Serializable, Comparable

    public abstract class ValuedEnum

extends Enum

Abstract superclass for type-safe enums with integer values suitable for use in `switch` statements.

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

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

     public final class JavaVersionEnum extends ValuedEnum {
       //standard enums for version of JVM
       public static final int  JAVA1_0_VALUE  = 100;
       public static final int  JAVA1_1_VALUE  = 110;
       public static final int  JAVA1_2_VALUE  = 120;
       public static final int  JAVA1_3_VALUE  = 130;
       public static final JavaVersionEnum  JAVA1_0  = new JavaVersionEnum( "Java 1.0", JAVA1_0_VALUE );
       public static final JavaVersionEnum  JAVA1_1  = new JavaVersionEnum( "Java 1.1", JAVA1_1_VALUE );
       public static final JavaVersionEnum  JAVA1_2  = new JavaVersionEnum( "Java 1.2", JAVA1_2_VALUE );
       public static final JavaVersionEnum  JAVA1_3  = new JavaVersionEnum( "Java 1.3", JAVA1_3_VALUE );

       private JavaVersionEnum(String name, int value) {
         super( name, value );
       }

       public static JavaVersionEnum getEnum(String javaVersion) {
         return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
       }

       public static JavaVersionEnum getEnum(int javaVersion) {
         return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
       }

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

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

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

NOTE:These are declared `final`, so compilers may inline the code. Ensure you recompile everything when using final.

The above class could then be used as follows:

     public void doSomething(JavaVersionEnum ver) {
       switch (ver.getValue()) {
         case JAVA1_0_VALUE:
           // ...
           break;
         case JAVA1_1_VALUE:
           // ...
           break;
         //...
       }
     }

As shown, each enum has a name and a value. These can be accessed using `getName` and `getValue`.

NOTE: Because the switch is ultimately sitting on top of an int, the example above is not type-safe. That is, there is nothing that checks that JAVA1_0_VALUE is a legal constant for JavaVersionEnum.

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.

Since:
  2.1 (class existed in enum package from v1.0)
Version:
  $Id: ValuedEnum.java 905636 2010-02-02 14:03:32Z niallp $
Author:
  Apache Avalon project, Apache Software Foundation
See Also:
  Serialized Form

Field Summary

Fields inherited from class org.apache.commons.lang.enums.Enum
`iToString`

Constructor Summary
`protected` | `ValuedEnum(String name, int value)` Constructor for enum item.

Method Summary
`int` | `compareTo(Object other)` Tests for order.
`protected static Enum` | `getEnum(Class enumClass, int value)` Gets an `Enum` object by class and value.
`int` | `getValue()` Get value of enum item.
`String` | `toString()` Human readable description of this `Enum` item.

Methods inherited from class org.apache.commons.lang.enums.Enum
`equals, getEnum, getEnumClass, getEnumList, getEnumMap, getName, hashCode, iterator, readResolve`

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

Constructor Detail

### ValuedEnum

    protected ValuedEnum(String name,
                         int value)

  Constructor for enum item.

  Parameters:
    `name` - the name of enum item
    `value` - the value of enum item

Method Detail

### getEnum

    protected static Enum getEnum(Class enumClass,
                                  int value)

  Gets an `Enum` object by class and value.

  This method loops through the list of `Enum`, thus if there are many `Enum`s this will be slow.

  Parameters:
    `enumClass` - the class of the `Enum` to get
    `value` - the value of the `Enum` to get
  Returns:
    the enum object, or null if the enum does not exist
  Throws:
    `IllegalArgumentException` - if the enum class is `null`

### getValue

    public final int getValue()

  Get value of enum item.

  Returns:
    the enum item's value.

### compareTo

    public int compareTo(Object other)

  Tests for order.

  The default ordering is numeric by value, but this can be overridden by subclasses.

  NOTE: From v2.2 the enums must be of the same type. If the parameter is in a different class loader than this instance, reflection is used to compare the values.

  Specified by:
    `compareTo` in interface `Comparable`
  Overrides:
    `compareTo` in class `Enum`
  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:
    `ClassCastException` - if other is not an `Enum`
    `NullPointerException` - if other is `null`
  See Also:
    `Comparable.compareTo(Object)`

### toString

    public String toString()

  Human readable description of this `Enum` item.

  Overrides:
    `toString` in class `Enum`
  Returns:
    String in the form `type[name=value]`, for example: `JavaVersion[Java 1.0=100]`. 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-2011 The Apache Software Foundation. All Rights Reserved.