public abstract class Enum
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable
Subclasses of the Enum class are the recommended, type safe way to represent a fixed set consisting of enumerable, serializable, comparable values. The Enum pattern is a variant of the Singleton Design Pattern, meaning that each value is guaranteed to have only one Enum instance per VM. No garbage is created by using Enums, and there is no possibility of users passing an invalid or out-of-range value. The == operator may be used to check equality between enumerated values.
The normal usage of Enums is to define an Enum subclass for each enumeration data type, and to define a set of public final static constants in that class which provide access to named singleton instances of the Enum's values.
Every Enum value has an associated String name and an ordinal integer. The String names are returned when toString() is invoked on an Enum value. The ordinals provide a canonical encoding of each Enum that is used to implement comparison and serialization of enumerated types; they also ensure a well-defined correspondence between old and new serialized values of the subclass if the set of values is changed. Note that Enums cannot be converted to or from these ordinals unless the Enum subclass explicitly exposes such conversion publicly. In general, a program which expects enums to correspond to specific integers should be using static final int constants, not Enums. (Conversion between Enums and their String names is, however, provided by the PropertyEditor support described below.)
The inner classes EnumEditor and LocaleEnumEditor make it very easy to define java.beans.PropertyEditor classes for an enumerated data type. This immediately makes the type usable for configurable JavaBeans and Dynamic Beans properties within Dynamo and its associated user interfaces. The getTags() methods of these editors return the set of valid textual values of the Enum type, meaning that JavaBeans-compatible UIs will automatically provide constrained widgets such as ComboBoxes to edit such properties. EnumEditor provides an unlocalized editor which can be used by Nucleus or other JavaBeans-based configurators that represent bean properties as Strings. LocaleEnumEditor provides a way to expose an Enum-type bean property for editing in a locale-dependent UI, such as the Dynamo Control Center, with a ResourceBundle controlling the UI-visible set of stringified values.
A subclass must create at least one instance as a final static constant, and its constructor must be private to prevent the generation of any instances of the class besides its known singletons.
Here is an example of an absolutely minimal subclass, such as might be used algorithmically with no visibility in Dynamo's configuration or user interface.
public class Direction extends Enum {
private Direction(String dn, int ordinal) {super(dn, ordinal);}
public final static Direction NORTH = new Direction("North", 0);
public final static Direction SOUTH = new Direction("South", 1);
public final static Direction EAST = new Direction("East", 2);
public final static Direction WEST = new Direction("West", 3);
}
The following example uses the full set of Enum features for a class that supports the configuration, viewing and editing within Dynamo of JavaBean properties of the class's type.
import java.util.Iterator;
import java.util.ResourceBundle;
import java.beans.PropertyEditorManager;
import atg.beans.LocalePropertyEditorManager;
public class Direction extends Enum {
private Direction(String dn, int ordinal) {super(dn, ordinal);}
public final static Direction NORTH = new Direction("North", 0);
public final static Direction SOUTH = new Direction("South", 1);
public final static Direction EAST = new Direction("East", 2);
public final static Direction WEST = new Direction("West", 3);
// an Iterator to iterate over all Direction objects.
public static Iterator getIterator() {return iterator(Direction.class);}
// The following defines a non-localized PropertyEditor that will
// allow Direction values to be edited as "North", "South", etc., and
// Direction-type bean properties to be configured with these values in Nucleus.
static {
PropertyEditorManager.registerEditor(Direction.class, DirectionEditor.class);
}
public static class DirectionEditor extends Enum.EnumEditor {
public Class getEnumClass() { return Direction.class; }
}
// The following defines a localized PropertyEditor that will be used
// in user interfaces to edit Direction-type bean properties in a locale-dependent
// fashion. It assumes the existence of a ResourceBundle named DirectionTags
// in the same package as this class.
static {
LocalePropertyEditorManager.registerEditor(Direction.class, LocaleDirectionEditor.class);
}
public static class LocaleDirectionEditor extends Enum.LocaleEnumEditor {
public Class getEnumClass() { return Direction.class; }
}
}
toString(),
iterator(Class),
iterator(),
Serialized Form| Modifier and Type | Class and Description |
|---|---|
static class |
Enum.EnumEditor
Utility class to allow Enum objects to be used as properties of
JavaBeans; the editor exposes tag values equal to the Enum
values' logical names.
|
static class |
Enum.LocaleEnumEditor
Utility class to allow Enum objects to be used as properties of
JavaBeans; the editor exposes tag values obtained by looking up
the Enum values' logical names in a ResourceBundle.
|
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
CLASS_VERSION |
| Modifier | Constructor and Description |
|---|---|
protected |
Enum(java.lang.String enumName,
int ordinalVal)
The subclass constructor should be private.
|
| Modifier and Type | Method and Description |
|---|---|
int |
compareTo(java.lang.Object o)
The compareTo method allows Enum objects to be
placed in ordered containers.
|
protected static atg.core.util.Enum.EnumClassInfo |
getEnumClassInfo(java.lang.Class c) |
protected int |
getOrdinal() |
java.util.Iterator |
iterator() |
static java.util.Iterator |
iterator(java.lang.Class c) |
protected static Enum |
lookup(java.lang.Class c,
int ordNum) |
protected static Enum |
lookup(java.lang.Class c,
java.lang.String name) |
protected Enum |
lookup(int ordNum) |
protected Enum |
lookup(java.lang.String name) |
protected java.lang.Object |
readResolve()
This allows us to read serialized Enum objects without
creating new instances.
|
java.lang.String |
toString() |
protected Enum(java.lang.String enumName,
int ordinalVal)
The ordinal value is used to compare (done when sorting, for example) two Enum objects and to order the objects in iterators and PropertyEditors. No two instances of a subclass should have the same ordinal value or name. To safely add new Enum subclass instances and preserve previous orderings in containers the best thing to do is to always use a new ordinal value when creating a new instance rather than changing old instance's ordinal value.
If an enum subclass instance is ever removed, there should be a comment in the file that reserves the old ordinal value so that any old serialized files don't accidentally map an old enum to a new enum.
enumName - The name of the instance that will appear in editors and toString().ordinalVal - The ordinal valuejava.lang.Error - if the subclass already has an instance name n or if the ordinal
number is already used by another instance of the same subclass.public java.lang.String toString()
toString in class java.lang.Objectprotected int getOrdinal()
public int compareTo(java.lang.Object o)
compareTo in interface java.lang.Comparableo - The object to be compared to.java.lang.ClassCastException - if o is not an Enum subclass.public static java.util.Iterator iterator(java.lang.Class c)
public java.util.Iterator iterator()
protected static Enum lookup(java.lang.Class c, int ordNum)
c - The Enum subclassname - The name of the Enum to lookup.protected Enum lookup(int ordNum)
name - The name of the Enum to lookup.protected static Enum lookup(java.lang.Class c, java.lang.String name)
c - The Enum subclassname - The name of the Enum to lookup.protected Enum lookup(java.lang.String name)
name - The Enum object's name to lookup.protected java.lang.Object readResolve()
throws java.io.ObjectStreamException
java.io.ObjectStreamExceptionprotected static atg.core.util.Enum.EnumClassInfo getEnumClassInfo(java.lang.Class c)
c - The Class object for the Enum subclass to look up.