org.apache.commons.lang.enums
Class ValuedEnum

java.lang.Object
  extended byorg.apache.commons.lang.enums.Enum
      extended byorg.apache.commons.lang.enums.ValuedEnum
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable

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 466275 2006-10-20 22:02:34Z bayard $
Author:
Apache Avalon project, Stephen Colebourne
See Also:
Serialized Form

Field Summary
 
Fields inherited from class org.apache.commons.lang.enums.Enum
iToString
 
Constructor Summary
protected ValuedEnum(java.lang.String name, int value)
          Constructor for enum item.
 
Method Summary
 int compareTo(java.lang.Object other)
          Tests for order.
protected static Enum getEnum(java.lang.Class enumClass, int value)
          Gets an Enum object by class and value.
 int getValue()
          Get value of enum item.
 java.lang.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(java.lang.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(java.lang.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 Enums 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:
java.lang.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(java.lang.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 java.lang.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:
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()

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.


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