atg.core.util
Class Enum

java.lang.Object
  atg.core.util.Enum

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

Direct Known Subclasses:

BooleanExpressionType, BooleanMode, BooleanQuoteStatus, BrowseRequest.AncestryType, BrowseRequest.DocSortOrder, BrowseRequest.RecurseDocumentsType, BrowseRequest.SetSort, BrowseRequest.Sorting, Case, CategorizeRequest.CategorizeInputMode, DiagnosticStatus, DocSortPropVal, ExpansionType, Field.Op, GearHeightEnum, GearWidthEnum, GroupingMode, InputPositionType, InputType, ItemType, KeywordType, NumOp, OptionsBase.ExpandedStemmingType, OptionsBase.Index, OptionsBase.IndexScheme, OptionsBase.SpellChecker, OptionsBase.SpellSplitWords, OpType, PaymentManagerAction, PropType, QueryRequest.DocSetSort, QueryRequest.DocSortOrder, QueryRequest.Mode, QueryRequest.RequestMode, QueryRequest.RuleMode, QueryRequest.Sorting, QueryRequest.Strategy, QueryTermsMode, RefineCountType, RefinementPropertyType, RefinementRangeType, RefinementSortOrder, RegionHeightEnum, RegionWidthEnum, RelevanceType, ResponseFormat, ResultCountType, ScheduledOrderAction, SimilarDocsRequest.DocSetSort, SimilarDocsRequest.DocSortOrder, SimilarDocsRequest.Mode, SpellingType, StringOp, StructuredQueryRequest.DocSetSort, StructuredQueryRequest.DocSortOrder, StructuredStatement.Mode, StructuredStatement.Operator, StructuredStatement.Strategy, TermCountType, TermLookupOp, TermOp, TreeQueryRequest.DocSortOrder, TypeAheadSortType, ViewDocumentRequest.Return, ViewDocumentRequest.Section

public abstract class Enum
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable

Base class for enumerated Objects.

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; }
    }
 }
 

See Also:

toString(), iterator(Class), iterator(), Serialized Form

Nested Class Summary

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.

Field Summary

static java.lang.String

CLASS_VERSION

Constructor Summary

protected

Enum(java.lang.String enumName, int ordinalVal) The subclass constructor should be private.

Method Summary

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()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Constructor Detail

Enum

protected Enum(java.lang.String enumName,
               int ordinalVal)

The subclass constructor should be private.

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.

Parameters:

enumName - The name of the instance that will appear in editors and toString().

ordinalVal - The ordinal value

Throws:

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

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

The name of this Enum

getOrdinal

protected int getOrdinal()

Returns:

The ordinal value used for sorting this Enum.

compareTo

public int compareTo(java.lang.Object o)

The compareTo method allows Enum objects to be placed in ordered containers.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - The object to be compared to.

Returns:

Positive if this object is greater than o, negative if this object is less than o, and 0 if this object is equal to o.

Throws:

java.lang.ClassCastException - if o is not an Enum subclass.

iterator

public static java.util.Iterator iterator(java.lang.Class c)

Returns:

an Iterator to iterate over all Enums in subclass

iterator

public java.util.Iterator iterator()

Returns:

an Iterator to iterate over all Enums in subclass

lookup

protected static Enum lookup(java.lang.Class c,
                             int ordNum)

Parameters:

c - The Enum subclass

name - The name of the Enum to lookup.

Returns:

The Enum with the name for the invoking object's subclass. null if name not found.

lookup

protected Enum lookup(int ordNum)

Parameters:

name - The name of the Enum to lookup.

Returns:

The Enum with the name for the invoking object's subclass. null if name not found.

lookup

protected static Enum lookup(java.lang.Class c,
                             java.lang.String name)

Parameters:

c - The Enum subclass

name - The name of the Enum to lookup.

Returns:

The Enum with the name for the invoking object's subclass. null if name not found.

lookup

protected Enum lookup(java.lang.String name)

Parameters:

name - The Enum object's name to lookup.

Returns:

The Enum with the name for the invoking object's subclass. null if name not found.

readResolve

protected java.lang.Object readResolve()
                                throws java.io.ObjectStreamException

This allows us to read serialized Enum objects without creating new instances. Otherwise == tests wouldn't work.

Throws:

java.io.ObjectStreamException

getEnumClassInfo

protected static atg.core.util.Enum.EnumClassInfo getEnumClassInfo(java.lang.Class c)

Parameters:

c - The Class object for the Enum subclass to look up.

Returns:

The EnumClassInfo object that corresponds to c. If there is no EnumClassInfo object, one will be created.