The Carbon Java Framework  

The Carbon Utilities Subsystem

Enumerations Design

Author: Greg Hinkle (ghinkle at sapient.com)
Version: $Revision: 1.2 $($Author: ghinkl $ / $Date: 2003/03/18 02:45:22 $)
Created: January 2002

Introduction

The core BaseEnum provides a base class implementation of enumerated types with a type-safe interface. The base class acts as a static singleton to aggregate all enumerations in the system and ensure that there is only a single set of instances of each enumerated type. This design feature simplifies the use of enumerated types and makes them quick and easy to use.

The BaseEnum has two constructors with no default constructor. In this manner and subclass of BaseEnum must call super passing in an appropriate set of information. The design is such that during the construction of a particular instance of an Enumerated Type, it will be added to the system-wide EnumTypeCatalogue for that type. This ensures that there is only a single set of types and simplifies the storage and retrieval by providing lookup and iterator methods in the base class.

Each subclass of enumeration, properly implemented, can provide for serialization support by appropriately implementing the readResolve method as in the template and examples. This provides that even during deserialization, only a single instance of one value of an enumerated type will exist in the system.

The BaseEnum constructors provide two mechanisms to create new enumerated type instances. In the first, the ordinal or numeric value of an enumeration is automatically determined during construction. This is done in such a manner as to create consecutive ordinals with the first starting at "0". The second way is to pass the desired ordinal into the constructor and have it manually set.

Note: Mixing automatically and manually set ordinals on a single type can and will result in unusable enuemerations. This should never be done.

Requirements

Type-safe access
Each class of an enumerated type should provide type-safe access to retrieve an value via either ordinal or name.
Simple to build
Each class of an enumerated type should be very simple to create and require a minimum amount of code to provide the desired functionality. This can be provided through the use of a base class.
Type-neutral access
A generalized interface for retrieving any enumerated type value through a static base interface will allow functionality such as standard enumation handling at system interface points. (e.g. The EnumeratedTypeFormatter used to provide enumeration values from a users web form input.)
Speed
Access to enumeration types should be fast, but the most important performance feature should be quick comparisons. This will allow enumerations to be used in many parts of the system at core functionality points.
Serialization
Enumerations must support serialization for the types that will be passed between tiers of an enterprise system. This should be handled by providing a proper readResolve templated implementation.


Copyright © 2001-2003, Sapient Corporation