edu.nrao.sss.util
Class EnumerationUtility

java.lang.Object
  edu.nrao.sss.util.EnumerationUtility

public class EnumerationUtility
extends Object

A class that helps clients interact with enumeration classes.

Instances of this class will be used mainly, though not exclusively, by user interface classes. This class helps with setting default values for enumerations and also with restricting the choices of enumeration values available to users.

There are two ways to use this class to help manage enumerations, and these two ways can be used together. The first is programmatic. The setDefaultValue(Class, Enum) method can be used to define a default enumeration element for an enumeration class. The addToSelectableSet(Class, Enum), removeFromSelectableSet(Class, Enum), and setSelectableSet(Class, EnumSet) methods can be used to control the elements of an enumeration class that may be chosen by a user (or another object).

The second way to manage enumerations with this class is to use properties files. The name of each properties file is simple-enumeration-class-name.properties. These files must reside on the classpath. This class understands these two properties: default and nonselectable. The first property takes a single value; the second takes a comma-separated list of values. The text of the values must be identical to the name of the element, including capitalization.

Example Properties File:
Name: DistanceUnits.properties
Contents:

 
   default = KILOMETER
   
   nonselectable = UNKNOWN, ANGSTROM, NANOMETER, MICROMETER, MILLIMETER,\
                   CENTIMETER, MILE
 

CVS Info:

$Revision: 1707 $

$Date: 2008-11-14 10:23:59 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-05-18

Author:

David M. Harland

Constructor Summary

EnumerationUtility()
Creates a new enumeration utility.

Method Summary

<E extends Enum<E>> void	addToSelectableSet(Class<E> enumType, E enumValue) Add enumValue to the set of selectable elements of class enumType.
<E extends Enum<E>> E	enumFromString(Class<E> enumType, String text) Returns an enumeration constant from enumType represented by text.
<E extends Enum<E>> E	enumFromStringOrDefault(Class<E> enumType, String text) Returns an enumeration constant from enumType based on text.
<E extends Enum<E>> String	enumToString(E element) Returns a text representation of element.
<E extends Enum<E>> String	enumToUpperString(E element) Returns a text representation of element.
<E extends Enum<E>> EnumSet<E>	getCompleteSetFor(Class<E> enumType) Returns the complete set of enumeration elements for the given class.
<E extends Enum<E>> E	getDefaultValueFor(Class<E> enumType) Returns a default element for the given enumeration type.
<E extends Enum<E>> E	getRandomValueFor(Class<E> enumType) Returns a random element for the given enumeration type.
<E extends Enum<E>> EnumSet<E>	getSelectableSetFor(Class<E> enumType) Returns the set of enumeration elements for the given class from which a specific element may be selected.
static EnumerationUtility	getSharedInstance() Returns a pre-made instance of this utility.
void	reload() Reloads all internally stored information.
<E extends Enum<E>> void	reload(Class<E> enumType) Reloads the internally stored information for the given enumeration type.
<E extends Enum<E>> void	removeFromSelectableSet(Class<E> enumType, E enumValue) Removes enumValue from the set of selectable elements of class enumType.
<E extends Enum<E>> void	setDefaultValue(Class<E> enumType, E enumValue) Sets the default value for enumType to enumValue.
<E extends Enum<E>> void	setSelectableSet(Class<E> enumType, EnumSet<E> selectableSet) Sets the collection of selectable elements for the given enumeration type.

Methods inherited from class java.lang.Object

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

Constructor Detail

EnumerationUtility

public EnumerationUtility()

Creates a new enumeration utility.

Method Detail

getSharedInstance

public static EnumerationUtility getSharedInstance()

Returns a pre-made instance of this utility. Every request to this method returns the same object.

Returns:

a pre-made instance of this utility.

getCompleteSetFor

public <E extends Enum<E>> EnumSet<E> getCompleteSetFor(Class<E> enumType)

Returns the complete set of enumeration elements for the given class.

Parameters:

enumType - an enumeration class.

Returns:

the complete set of enumeration elements for enumType.

Throws:

NullPointerException - if enumType is null.

getSelectableSetFor

public <E extends Enum<E>> EnumSet<E> getSelectableSetFor(Class<E> enumType)

Returns the set of enumeration elements for the given class from which a specific element may be selected. This set is often, but not always, the complete set of elements. Sometimes, though, an enumeration has an element such as UNKNOWN that should not be a client-selectable element. The set returned by this method will typically exclude such elements.

Parameters:

enumType - an enumeration class.

Returns:

a set of selectable elements of type E.

Throws:

NullPointerException - if enumType is null.

getDefaultValueFor

public <E extends Enum<E>> E getDefaultValueFor(Class<E> enumType)

Returns a default element for the given enumeration type. A common use of this method is to initialize a user interface component to a default value.

Parameters:

enumType - an enumeration class.

Returns:

a default element for enumType.

Throws:

NullPointerException - if enumType is null.

getRandomValueFor

public <E extends Enum<E>> E getRandomValueFor(Class<E> enumType)

Returns a random element for the given enumeration type.

Parameters:

enumType - an enumeration class.

Returns:

a random element for the given enumeration type.

setSelectableSet

public <E extends Enum<E>> void setSelectableSet(Class<E> enumType,
                                                 EnumSet<E> selectableSet)

Sets the collection of selectable elements for the given enumeration type.

Parameters:

enumType - an enumeration class.

selectableSet - a set of selectable elements of type E.

Throws:

NullPointerException - if either parameter is null.

addToSelectableSet

public <E extends Enum<E>> void addToSelectableSet(Class<E> enumType,
                                                   E enumValue)

Add enumValue to the set of selectable elements of class enumType. If enumType is null, this method does nothing.

Parameters:

enumType - an enumeration class.

enumValue - a selectable element.

Throws:

NullPointerException - if enumType is null.

removeFromSelectableSet

public <E extends Enum<E>> void removeFromSelectableSet(Class<E> enumType,
                                                        E enumValue)

Removes enumValue from the set of selectable elements of class enumType.

Parameters:

enumType - an enumeration class.

enumValue - an element that is not selectable.

Throws:

NullPointerException - if enumType is null.

setDefaultValue

public <E extends Enum<E>> void setDefaultValue(Class<E> enumType,
                                                E enumValue)

Sets the default value for enumType to enumValue.

Parameters:

enumType - an enumeration class.

enumValue - a default value for enumType.

reload

public <E extends Enum<E>> void reload(Class<E> enumType)

Reloads the internally stored information for the given enumeration type. This is useful if the client knows that a change has been made to an external properties file. Unless forced to do so, this utility will not detect such external changes.

Parameters:

enumType - an enumeration class.

reload

public void reload()

Reloads all internally stored information. See reload(Class) for details.

enumToString

public <E extends Enum<E>> String enumToString(E element)

Returns a text representation of element.

The returned string will be in lower case, except that the first letter of each word will be in upper case. The string is based on the name of the element (as returned by element.name()). Any underscores in the name are replaced with spaces.

The main users of this method will be the enumeration classes themselves.

Parameters:

element - a member of an enumeration class.

Returns:

a text representation of element. If element is null, the empty string ("") is returned.

enumToUpperString

public <E extends Enum<E>> String enumToUpperString(E element)

Returns a text representation of element.

The returned string will be in Upper case. The string is based on the name of the element (as returned by element.name()). Any underscores in the name are replaced with spaces.

The main users of this method will be the enumeration classes themselves.

Parameters:

element - a member of an enumeration class.

Returns:

a text representation of element. If element is null, the empty string ("") is returned.

enumFromString

public <E extends Enum<E>> E enumFromString(Class<E> enumType,
                                            String text)

Returns an enumeration constant from enumType represented by text.

Leading and trailing whitespace is first stripped from text. A case-insensitive comparison against the name and toString methods of each constant in the enumeration is then performed. If the enumeration class has a getSymbol method, it is also used in the comparison. If no match is found, null is returned.

Parameters:

enumType - an enumeration class.

text - a text representation of a constant in enumType.

Returns:

an enumeration constant from enumType.

See Also:

enumFromStringOrDefault(Class, String)

enumFromStringOrDefault

public <E extends Enum<E>> E enumFromStringOrDefault(Class<E> enumType,
                                                     String text)

Returns an enumeration constant from enumType based on text.

This method is similar to enumFromString(Class, String), except that if no match is found, a default constant from enumType is returned.

If enumType

1. is non-null,
2. is an enumeration class, and
3. has at least one constant

then the return value is guaranteed to be non-null.

Parameters:

enumType - an enumeration class.

text - a text representation of a constant in enumType.

Returns:

an enumeration constant from enumType.

See Also:

enumFromString(Class, String), getDefaultValueFor(Class)