org.apache.commons.lang.enum
Class Enum

java.lang.Object
  |
  +--org.apache.commons.lang.enum.Enum

All Implemented Interfaces:

Comparable, Serializable

Direct Known Subclasses:

ValuedEnum

public abstract class Enum

extends Object

implements Comparable, 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 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 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.

NOTE: This class originated in the Jakarta Avalon project.

Version:

$Id: Enum.java,v 1.2.2.1 2002/11/22 20:07:53 bayard Exp $

Author:

Stephen Colebourne

See Also:

Serialized Form

Nested Class Summary

private static class

Enum.Entry Enable the iterator to retain the source code order

Field Summary

private static Map	cEnumClasses Map, key of class name, value of Entry.
private static Map	EMPTY_MAP An empty map, as JDK1.2 didn't have an empty map
private String	iName The string representation of the Enum.

Constructor Summary

protected

Enum(String name) Constructor to add a new named item to the enumeration.

Method Summary

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

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_MAP

private static final Map EMPTY_MAP

An empty map, as JDK1.2 didn't have an empty map

cEnumClasses

private static final Map cEnumClasses

Map, key of class name, value of Entry.

iName

private final String iName

The string representation of the Enum.

Constructor Detail

Enum

protected Enum(String name)

Constructor to add a new named item to the enumeration.

Parameters:

name - the name of the enum object

Throws:

IllegalArgumentException - if the name is null or a blank string

Method Detail

readResolve

protected Object readResolve()

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(Class enumClass,
                              String name)

Gets an Enum object by class and name.

Parameters:

enumClass - the class of the Enum to get

name - the name of the Enum to get, may be null

Returns:

the enum object, or null if the enum does not exist

Throws:

IllegalArgumentException - if the enum class is null

getEnumMap

protected static Map getEnumMap(Class enumClass)

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

Returns:

the enum object Map

Throws:

IllegalArgumentException - if the enum class is null

IllegalArgumentException - if the enum class is not a subclass of Enum

getEnumList

protected static List getEnumList(Class enumClass)

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

Returns:

the enum object Map

Throws:

IllegalArgumentException - if the enum class is null

IllegalArgumentException - if the enum class is not a subclass of Enum

iterator

protected static Iterator iterator(Class enumClass)

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

Returns:

an iterator of the Enum objects

Throws:

IllegalArgumentException - if the enum class is null

IllegalArgumentException - if the enum class is not a subclass of Enum

getName

public final String getName()

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

Returns:

the String name of this Enum item

equals

public final boolean equals(Object other)

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.

Overrides:

equals in class Object

Parameters:

other - the other object to compare for equality

Returns:

true if the Enums are equal

hashCode

public final int hashCode()

Returns a suitable hashCode for the enumeration.

Overrides:

hashCode in class Object

Returns:

a hashcode based on the name

compareTo

public int compareTo(Object other)

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

Specified by:

compareTo in interface 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:

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. For use when debugging.

Overrides:

toString in class Object

Returns:

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