net.sf.mmm.util.lang.api

Interface EnumProvider

All Superinterfaces:

Iterable<EnumDefinition<?,?>>

All Known Implementing Classes:

AbstractEnumProvider, AbstractEnumProviderAsynchronous, AbstractEnumProviderSynchronous, SimpleEnumProvider

@ComponentSpecification
public interface EnumProvider
extends Iterable<EnumDefinition<?,?>>

This is the interface for a generic provider of enumerations. The major goal of this component is generic support for enumerations of any kind. This may e.g. be used for user-interfaces in radio-groups, drop-downs, combo-boxes, or the like. More advanced cases are implementations that dynamically load the enum values from a file, database or a service. Within mmm-util-core you will only find simple implementations of this interface. Dynamic enumerations are provided by higher-level components of the project.

Since:

3.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
void	clear(EnumDefinition<?,?> enumDefinition) This method clears the (potentially) cached enum values of the given EnumDefinition.
<TYPE> EnumDefinition<TYPE,?>	getEnumDefinition(Class<TYPE> enumType) This method gets the EnumDefinition with the given enumType.
EnumDefinition<?,?>	getEnumDefinition(String key) This method gets the EnumDefinition with the given key.
Iterator<EnumDefinition<?,?>>	getEnumDefinitions() This method gets an (unmodifiable) Iterator with all existing EnumDefinitions.
<CATEGORY,ENUM extends EnumTypeWithCategory<?,CATEGORY>> EnumDefinition<ENUM,CATEGORY>	getEnumDefinitionWithCategory(Class<? extends ENUM> enumType) This method gets the EnumDefinition with the given enumType.
<ENUM> ENUM	getEnumValue(Class<ENUM> enumType, String value, boolean required) This method gets the EnumType-instance of the given EnumDefinition identified by the given value.
<ENUM> ENUM	getEnumValue(EnumDefinition<ENUM,?> enumDefinition, String value, boolean required) This method gets the EnumType-instance of the given EnumDefinition identified by the given value.
<ENUM> List<ENUM>	getEnumValues(EnumDefinition<ENUM,?> enumDefinition) This method gets the List of EnumType-instances that represent the values of the given EnumDefinition.
<CATEGORY,ENUM extends EnumTypeWithCategory<?,CATEGORY>> List<ENUM>	getEnumValues(EnumDefinition<ENUM,CATEGORY> enumDefinition, CATEGORY... categories) This method gets the List of enum values filtered by the given categories.
boolean	isAvailable(EnumDefinition<?,?> enumDefinition) This method determines if the given EnumDefinition is available, so it is ensured that the enum values can be retrieved.
Iterator<EnumDefinition<?,?>>	iterator() The same as getEnumDefinitions().
void	require(EnumDefinition<?,?>... enumDefinitions) This method triggers that the given EnumDefinitions are available.
void	require(Runnable callback, EnumDefinition<?,?>... enumDefinitions) This method triggers that the given EnumDefinitions are available.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

iterator

Iterator<EnumDefinition<?,?>> iterator()

The same as getEnumDefinitions().

Specified by:

iterator in interface Iterable<EnumDefinition<?,?>>

getEnumDefinitions

Iterator<EnumDefinition<?,?>> getEnumDefinitions()

This method gets an (unmodifiable) Iterator with all existing EnumDefinitions. In most cases this is a static list, however it may also be dynamic.

Returns:

the Iterator with all existing EnumDefinitions.

See Also:

iterator()

getEnumDefinition

EnumDefinition<?,?> getEnumDefinition(String key)
                               throws ObjectNotFoundException

This method gets the EnumDefinition with the given key. To get the default EnumDefinition for a particular enum type you should use getEnumDefinition(Class) instead. However, for the same enum type multiple EnumDefinitions can exists. The default definition should have the qualified name of the enum type while additional definitions should have more specific keys that do not clash with others (e.g. "java.lang.Boolean_All_None").

Parameters:

key - is the key of the requested definition.

Returns:

the requested EnumDefinition.

Throws:

ObjectNotFoundException - if no such EnumDefinition exists.

getEnumDefinition

<TYPE> EnumDefinition<TYPE,?> getEnumDefinition(Class<TYPE> enumType)
                                         throws ObjectNotFoundException

This method gets the EnumDefinition with the given enumType.

Type Parameters:

TYPE - is the generic for the enum type.

Parameters:

enumType - is the enum type of the requested definition.

Returns:

the requested EnumDefinition.

Throws:

ObjectNotFoundException - if no such EnumDefinition exists.

getEnumDefinitionWithCategory

<CATEGORY,ENUM extends EnumTypeWithCategory<?,CATEGORY>> EnumDefinition<ENUM,CATEGORY> getEnumDefinitionWithCategory(Class<? extends ENUM> enumType)
                                                                                                              throws ObjectNotFoundException

This method gets the EnumDefinition with the given enumType.

Type Parameters:

CATEGORY - is the generic for the category.

ENUM - is the generic for the enum type.

Parameters:

enumType - is the enum type of the requested definition.

Returns:

the requested EnumDefinition.

Throws:

ObjectNotFoundException - if no such EnumDefinition exists.

isAvailable

boolean isAvailable(EnumDefinition<?,?> enumDefinition)

This method determines if the given EnumDefinition is available, so it is ensured that the enum values can be retrieved.

Parameters:

enumDefinition - is the EnumDefinition to check.

Returns:

true if the enum values for the given EnumDefinition are available (already loaded / in cache), false otherwise.

require

void require(EnumDefinition<?,?>... enumDefinitions)

This method triggers that the given EnumDefinitions are available.

Parameters:

enumDefinitions - are the EnumDefinitions of the required enumerations.

require

void require(Runnable callback,
             EnumDefinition<?,?>... enumDefinitions)

This method triggers that the given EnumDefinitions are available. In advanced to require(EnumDefinition...) it allows to specify a callback that gets invoked after the required EnumDefinitions are available. This is useful in asynchronous environments (e.g. in client applications that have to receive the values (asynchronously) from the server).

Parameters:

callback - is a Runnable that will be called after all given EnumDefinitions are available.

enumDefinitions - are the EnumDefinitions of the required enumerations.

getEnumValues

<ENUM> List<ENUM> getEnumValues(EnumDefinition<ENUM,?> enumDefinition)

This method gets the List of EnumType-instances that represent the values of the given EnumDefinition. In case the enum type implements AttributeReadDeprecated the deprecated enum values will be excluded from the returned List.

Type Parameters:

ENUM - is the generic for the enum type.

Parameters:

enumDefinition - is the EnumDefinition for which the values are requested.

Returns:

the List of EnumTypes.

getEnumValue

<ENUM> ENUM getEnumValue(EnumDefinition<ENUM,?> enumDefinition,
                         String value,
                         boolean required)
                  throws IllegalCaseException

This method gets the EnumType-instance of the given EnumDefinition identified by the given value.

Type Parameters:

ENUM - is the generic for the enum type.

Parameters:

enumDefinition - is the EnumDefinition for which the value is requested.

value - is the string representation of the requested EnumType instance based on EnumDefinition.getFormatter().

required - - true if the requested EnumType-instance is required, false otherwise.

Returns:

the EnumType-instance. Will be null if value is null or if required is false and no such EnumType instance exists.

Throws:

IllegalCaseException - if required is true and no such EnumType instance exists.

getEnumValue

<ENUM> ENUM getEnumValue(Class<ENUM> enumType,
                         String value,
                         boolean required)
                  throws IllegalCaseException

This method gets the EnumType-instance of the given EnumDefinition identified by the given value.

Type Parameters:

ENUM - is the generic for the enum type.

Parameters:

enumType - is the EnumType for which the value is requested.

value - is the string representation of the requested EnumType instance based on EnumDefinition.getFormatter().

required - - true if the requested EnumType-instance is required, false otherwise.

Returns:

the EnumType-instance. Will be null if value is null or if required is false and no such EnumType instance exists.

Throws:

IllegalCaseException - if required is true and no such EnumType instance exists.

getEnumValues

<CATEGORY,ENUM extends EnumTypeWithCategory<?,CATEGORY>> List<ENUM> getEnumValues(EnumDefinition<ENUM,CATEGORY> enumDefinition,
                                                                                  CATEGORY... categories)

This method gets the List of enum values filtered by the given categories. So only these enum values are returned that have a category

Type Parameters:

CATEGORY - is the generic type of the category type.

ENUM - is the generic for the enum type.

Parameters:

enumDefinition - is the EnumDefinition for which the values are requested.

categories - are the categories.

Returns:

the List of matching EnumTypes.

clear

void clear(EnumDefinition<?,?> enumDefinition)

This method clears the (potentially) cached enum values of the given EnumDefinition. If the enum is dynamic it is NOT available (anymore) after this operation.

Parameters:

enumDefinition - is the EnumDefinition to clear.