Package 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 $
See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class org.apache.commons.lang.enums.Enum

`iToString`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`ValuedEnum(String name, int value)`
Constructor for enum item.

## Method Summary

Modifier and Type
Method
Description
`int`
`compareTo(Object other)`
Tests for order.
`protected static Enum`
`getEnum(Class enumClass, int value)`
Gets an `Enum` object by class and value.
`final 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 Details

### 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 Details

### 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.