org.josef.util

Class CEnumeration

java.lang.Object

org.josef.util.CEnumeration

@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public final class CEnumeration
extends Object

Utility class for enumerations.
The most important task of this class is aiding in localization. For an enumeration to be localized, two options exist.

1. Implement LocalizableEnumeration
   Possibly use a properties file. Checkout the Month enum for an example where localization is performed without a backing properties file and Planet for an example where a backing properties file is used.
2. Simply use a properties file without implementing LocalizableEnumeration. It is assumed that the enum class is backed by a properties files with the same name as the enum class.

Version:

1.0 $Revision: 6483 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
static <T extends Enum<T> & LocalizableEnumeration> T	enumFromCode(Class<T> localizableEnumeration, Object code) Gets the localizable enumerated constant of type T with the supplied code.
static <T extends Enum<T>> T	enumFromOrdinal(Class<T> enumeration, int ordinal) Gets the enumerated constant of type T with the supplied ordinal.
static <T extends Enum<T> & LocalizableEnumeration> CodeDescription	getCodeDescription(T localizableEnumeratedConstant, Locale locale) Gets the CodeDescription of the supplied localizableEnumeratedConstant.
static <T extends Enum<T> & LocalizableEnumeration> List<CodeDescription>	getCodeDescriptions(Class<T> localizableEnumeration, Locale locale) Gets CodeDescriptions for all the localizable enumerated constants of the supplied localizableEnumeration.
static <T extends Enum<T>> List<CodeDescription>	getCodeDescriptionsUsingEnumNameAsCode(Class<T> enumeration, Locale locale) Gets CodeDescriptions for all the enumerated constants of the supplied enumeration, using the names of the enumerated constants as the code for the different CodeDescriptions.
static <T extends Enum<T>> CodeDescription	getCodeDescriptionUsingEnumNameAsCode(T enumeratedConstant, Locale locale) Gets the CodeDescription of the supplied enumeratedConstant, using the name of the supplied enumerated constant as the code for the returned CodeDescription.
static String	getDescription(Class<? extends Enum<?>> enumeration, Locale locale) Gets the description of the enumeration as a whole.
static String	getDescription(Enum<?> enumeratedConstant, Locale locale) Gets the description of the supplied enumeratedConstant.
static String	getDescription(Enum<?> enumeratedConstant, String key, Locale locale) Gets the description of the supplied enumeratedConstant using the supplied key as the key to the resource bundle..
static <T extends Enum<T> & LocalizableEnumeration> String	getDescriptionOfLocalizableEnum(T enumeratedConstant, Locale locale) Gets the description of the supplied enumeratedConstant using the name of the enumerated constant as the key to the resouce bundle.

Methods inherited from class java.lang.Object

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

Method Detail

getDescription

public static String getDescription(Class<? extends Enum<?>> enumeration,
                                    Locale locale)

Gets the description of the enumeration as a whole.
This method uses the simple class name of the supplied enumeration, as the key to the resource bundle file to get the description.
Note: Even though a ResourceBundle is used, a MissingResourceException is never thrown. Instead a warning is logged and the simple class name of the supplied enumeration is returned.

Parameters:

enumeration - The enumeration to get the description for.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

Localized description of the supplied enumeration.

Throws:

NullPointerException - When the supplied enumeration is null.

getDescription

public static String getDescription(Enum<?> enumeratedConstant,
                                    Locale locale)

Gets the description of the supplied enumeratedConstant.
This method uses the name of the enumeratedConstant as a key to the resource bundle file to get the description. When this key does not exist and the supplied enumeratedConstant implements LocalizableEnumeration, this method will, as a convenience, try to get the description, using LocalizableEnumeration.getCode() as the key to the resource bundle file. Note that for a LocalizableEnumeration, you normally call its getDescription() method. However, lots of these methods are implemented by calling this method, causing infinite recursion, so here the code is used as the resource bundle key. Naturally, this will fail for enumerations that are not backed by a properties file.
Note: Even though a ResourceBundle is used, a MissingResourceException is never thrown. Instead a warning is logged and the String representation of the supplied enumeratedConstant is returned.

Parameters:

enumeratedConstant - The enumerated constant to get the description for.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

Localized description of the supplied enumeratedConstant.

Throws:

NullPointerException - When the supplied enumeratedConstant is null.

getDescription

public static String getDescription(Enum<?> enumeratedConstant,
                                    String key,
                                    Locale locale)

Gets the description of the supplied enumeratedConstant using the supplied key as the key to the resource bundle..

Parameters:

enumeratedConstant - The enumerated constant to get the description for.

key - The key to the resource bundle.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

Localized description of the supplied enumeratedConstant.

Throws:

NullPointerException - When either the supplied enumeratedConstant or key is null.

IllegalArgumentException - When the supplied key is empty.

MissingResourceException - When the description could not be retrieved from the resource bundle.

getDescriptionOfLocalizableEnum

public static <T extends Enum<T> & LocalizableEnumeration> String getDescriptionOfLocalizableEnum(T enumeratedConstant,
                                                                                                  Locale locale)

Gets the description of the supplied enumeratedConstant using the name of the enumerated constant as the key to the resouce bundle.

Type Parameters:

T - The enumerated type.

Parameters:

enumeratedConstant - The enumerated constant to get the description for.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

Localized description of the supplied enumeratedConstant.

Throws:

NullPointerException - When the supplied enumeratedConstant is null.

MissingResourceException - When the description could not be retrieved from the resource bundle.

getCodeDescriptions

public static <T extends Enum<T> & LocalizableEnumeration> List<CodeDescription> getCodeDescriptions(Class<T> localizableEnumeration,
                                                                                                     Locale locale)

Gets CodeDescriptions for all the localizable enumerated constants of the supplied localizableEnumeration.

Type Parameters:

T - Type of the localizable enumeration.

Parameters:

localizableEnumeration - The localizable enumeration to get the CodeDescription objects for.

locale - Locale used to localize the descriptions.
When null is supplied the default locale is used.

Returns:

CodeDescriptions for the localizable enumerated constants of the supplied localizableEnumeration.

Throws:

NullPointerException - When the supplied localizableEnumeration is null.

getCodeDescription

public static <T extends Enum<T> & LocalizableEnumeration> CodeDescription getCodeDescription(T localizableEnumeratedConstant,
                                                                                              Locale locale)

Gets the CodeDescription of the supplied localizableEnumeratedConstant.

Type Parameters:

T - The type of the localizable enumerated constant.

Parameters:

localizableEnumeratedConstant - The localizable enumerated constant to get the CodeDescription for.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

The localized CodedDescription of the supplied localizableEnumeratedConstant.
The code in the returned object is determined by the result of localizableEnumeratedConstant.getCode().

Throws:

NullPointerException - When the supplied localizableEnumeratedConstant is null.

getCodeDescriptionsUsingEnumNameAsCode

public static <T extends Enum<T>> List<CodeDescription> getCodeDescriptionsUsingEnumNameAsCode(Class<T> enumeration,
                                                                                               Locale locale)

Gets CodeDescriptions for all the enumerated constants of the supplied enumeration, using the names of the enumerated constants as the code for the different CodeDescriptions.

Type Parameters:

T - The type of the enumeration.

Parameters:

enumeration - The enumeration to get the CodeDescription objects for.

locale - Locale used to localize the descriptions.
When null is supplied the default locale is used.

Returns:

CodeDescriptions for the enumerated constants of the supplied enumeration.

Throws:

NullPointerException - When the supplied enumeration is null.

getCodeDescriptionUsingEnumNameAsCode

public static <T extends Enum<T>> CodeDescription getCodeDescriptionUsingEnumNameAsCode(T enumeratedConstant,
                                                                                        Locale locale)

Gets the CodeDescription of the supplied enumeratedConstant, using the name of the supplied enumerated constant as the code for the returned CodeDescription.

Type Parameters:

T - The type of the enumerated constant.

Parameters:

enumeratedConstant - The enumerated constant to get the CodeDescription for.

locale - Locale used to localize the description.
When null is supplied the default locale is used.

Returns:

The localized CodedDescription of the supplied enumeratedConstant.
The code in the returned object is determined by the result of enumeratedConstant.name().

Throws:

NullPointerException - When the supplied enumeratedConstant is null.

enumFromOrdinal

public static <T extends Enum<T>> T enumFromOrdinal(Class<T> enumeration,
                                                    int ordinal)

Gets the enumerated constant of type T with the supplied ordinal.

Type Parameters:

T - The type of the enumeration.

Parameters:

enumeration - The enumeration containing the enumerated constants.

ordinal - Ordinal of the enumerated constant.

Returns:

The enumerated constant of type T with the supplied ordinal.

Throws:

IllegalArgumentException - When the supplied ordinal is out of range.

NullPointerException - When the supplied enumeration is null.

enumFromCode

public static <T extends Enum<T> & LocalizableEnumeration> T enumFromCode(Class<T> localizableEnumeration,
                                                                          Object code)

Gets the localizable enumerated constant of type T with the supplied code.
This method has linear performance and on average needs to perform N / 2 code comparisons, where N is the number of enumerated constants.

Type Parameters:

T - The type of the enumeration.

Parameters:

localizableEnumeration - The localizable enumeration containing the enumerated constants.

code - The code of the enumerated constant.

Returns:

The localizable enumerated constant of type T with the supplied code.

Throws:

IllegalArgumentException - When no enumerated constant has the supplied code.

NullPointerException - When either the supplied localizableEnumeration or code is null.