org.microbean.configuration

Class Configurations

java.lang.Object

org.microbean.configuration.api.Configurations

org.microbean.configuration.Configurations

public class Configurations
extends Configurations

An implementation of the Configurations class that serves as a single source for configuration values suitable for an application.

Author:

Laird Nelson

See Also:

Configuration

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIGURATION_COORDINATES The name of the configuration property whose value is a Map of configuration coordinates for the current application.

Fields inherited from class org.microbean.configuration.api.Configurations

logger

Constructor Summary

Constructors

Constructor and Description
Configurations() Creates a new Configurations.
Configurations(Collection<? extends Configuration> configurations) Creates a new Configurations.
Configurations(Collection<? extends Configuration> configurations, Collection<? extends Converter<?>> converters, Collection<? extends Arbiter> arbiters) Creates a new Configurations.

Method Summary

Modifier and Type	Method and Description
Map<String,String>	getConfigurationCoordinates() Returns a Map of configuration coordinates—aspects and their values that define a location within which requests for configuration values may take place.
Set<Type>	getConversionTypes() Returns a non-null, immutable Set of Types representing all the types to which String configuration values may be converted by the Converters loaded by this Configurations object.
Set<String>	getNames() Returns a Set of names of ConfigurationValues that might be returned by this Configurations instance.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Converter<T> converter) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, as converted by the supplied Converter.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Converter<T> converter, String defaultValue) Returns an object that is the value for the configuration request represented by the supplied configurationCoordinates, name and defaultValue parameters, as converted by the supplied Converter.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Type type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied type.
<T> T	getValue(String name, Converter<T> converter) Returns a configuration value corresponding to the configuration property suitable for the supplied name, as converted by the supplied Converter.
protected void	handleMalformedConfigurationValues(Collection<ConfigurationValue> badValues) Handles any badly formed ConfigurationValue instances received from Configuration instances during the execution of a configuration value request.
String	interpolate(String value) Interpolates any expressions occurring within the supplied value and returns the result of interpolation.
protected Collection<? extends Arbiter>	loadArbiters() Loads a Collection of Arbiter objects and returns it.
protected Collection<? extends Configuration>	loadConfigurations() Loads a Collection of Configuration objects and returns it.
protected Collection<? extends Converter<?>>	loadConverters() Loads a Collection of Converter objects and returns it.
protected ConfigurationValue	performArbitration(Map<? extends String,? extends String> configurationCoordinates, String name, Collection<? extends ConfigurationValue> values) Given a logical request for a configuration value, represented by the configurationCoordinates and name parameter values, and a Collection of ConfigurationValue instances that represents the ambiguous response from several Configuration instances, attempts to resolve the ambiguity by returning a single ConfigurationValue instead.

Methods inherited from class org.microbean.configuration.api.Configurations

createLogger, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, getValue, newInstance

Methods inherited from class java.lang.Object

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

Field Detail

CONFIGURATION_COORDINATES

public static final String CONFIGURATION_COORDINATES

The name of the configuration property whose value is a Map of configuration coordinates for the current application.

This field is never null.

A request is made via the Configurations.getValue(Map, String, Type) method with null as the value of its first parameter and the value of this field as its second parameter and Map.class as the value of its third parameter. The returned Map is cached for the lifetime of this Configurations object and is returned by the getConfigurationCoordinates() method.

See Also:

Configurations.getValue(Map, String, Type), getConfigurationCoordinates(), Constant Field Values

Constructor Detail

Configurations

public Configurations()

Creates a new Configurations.

The loadConfigurations(), loadConverters() and loadArbiters() methods will be invoked during construction.

See Also:

loadConfigurations(), loadConverters(), loadArbiters(), Configurations(Collection, Collection, Collection)

Configurations

public Configurations(Collection<? extends Configuration> configurations)

Creates a new Configurations.

The loadConverters() and loadArbiters() methods will be invoked during construction. IF the supplied configurations is null, then the loadConfigurations() method will be invoked during construction.

Parameters:

configurations - a Collection of Configuration instances; if null then the return value of the loadConfigurations() method will be used instead

See Also:

loadConfigurations(), loadConverters(), loadArbiters(), Configurations(Collection, Collection, Collection)

Configurations

public Configurations(Collection<? extends Configuration> configurations,
                      Collection<? extends Converter<?>> converters,
                      Collection<? extends Arbiter> arbiters)

Creates a new Configurations.

The loadConverters() and loadArbiters() methods will be invoked during construction. IF the supplied configurations is null, then the loadConfigurations() method will be invoked during construction.

Parameters:

configurations - a Collection of Configuration instances; if null then the return value of the loadConfigurations() method will be used instead

converters - a Collection of Converter instances; if null then the return value of the loadConverters() method will be used instead

arbiters - a Collection of Arbiter instances; if null then the return value of the loadArbiters() method will be used instead

See Also:

loadConfigurations(), loadConverters(), loadArbiters()

Method Detail

loadConfigurations

protected Collection<? extends Configuration> loadConfigurations()

Loads a Collection of Configuration objects and returns it.

This method never returns null.

Overrides of this method must not return null.

The default implementation of this method uses the ServiceLoader mechanism to load Configuration instances.

Returns:

a non-null, Collection of Configuration instances

See Also:

ServiceLoader.load(Class)

loadConverters

protected Collection<? extends Converter<?>> loadConverters()

Loads a Collection of Converter objects and returns it.

This method never returns null.

Overrides of this method must not return null.

The default implementation of this method uses the ServiceLoader mechanism to load Converter instances.

Returns:

a non-null, Collection of Converter instances

See Also:

ServiceLoader.load(Class)

loadArbiters

protected Collection<? extends Arbiter> loadArbiters()

Loads a Collection of Arbiter objects and returns it.

This method never returns null.

Overrides of this method must not return null.

The default implementation of this method uses the ServiceLoader mechanism to load Arbiter instances.

Returns:

a non-null, Collection of Arbiter instances

See Also:

ServiceLoader.load(Class)

getConfigurationCoordinates

public Map<String,String> getConfigurationCoordinates()

Returns a Map of configuration coordinates—aspects and their values that define a location within which requests for configuration values may take place.

This method may return null.

Overrides of this method may return null.

The default implementation of this method returns configuration coordinates that are discovered at construction time and cached for the lifetime of this Configurations object.

Specified by:

getConfigurationCoordinates in class Configurations

Returns:

a Map of configuration coordinates; may be null

getConversionTypes

public final Set<Type> getConversionTypes()

Returns a non-null, immutable Set of Types representing all the types to which String configuration values may be converted by the Converters loaded by this Configurations object.

This method never returns null.

Specified by:

getConversionTypes in class Configurations

Returns:

a non-null, immutable Set of Types

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            String name,
                            Type type,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied type.

This method may return null.

Specified by:

getValue in class Configurations

Type Parameters:

T - the type to which a String-typed configuration value should be converted

Parameters:

configurationCoordinates - a Map representing the configuration coordinates in effect for this request; may be null

name - the name of the configuration property for which a value will be returned; must not be null

type - a Type representing the type to which the configuration value will be converted; must not be null

defaultValue - the value that will be converted if null would otherwise be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

NoSuchConverterException - if there is no Converter available that handles the Type represented by the supplied type

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable and arbitration was performed but could not resolve the dispute

ConfigurationException - if any other configuration-related error occurs

See Also:

getValue(Map, String, Converter, String)

getValue

public final <T> T getValue(String name,
                            Converter<T> converter)

Returns a configuration value corresponding to the configuration property suitable for the supplied name, as converted by the supplied Converter.

This method may return null.

Type Parameters:

T - the type to which a String-typed configuration value should be converted

Parameters:

name - the name of the configuration property for which a value will be returned; must not be null

converter - a Converter instance that will convert any String configuration value into the type of object that this method will return; must not be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or converter is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable and arbitration was performed but could not resolve the dispute

See Also:

getValue(Map, String, Converter, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            String name,
                            Converter<T> converter)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, as converted by the supplied Converter.

This method may return null.

Type Parameters:

T - the type to which a String-typed configuration value should be converted

Parameters:

configurationCoordinates - a Map representing the configuration coordinates in effect for this request; may be null

name - the name of the configuration property for which a value will be returned; must not be null

converter - a Converter instance that will convert any String configuration value into the type of object that this method will return; must not be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or converter is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable and arbitration was performed but could not resolve the dispute

ConfigurationException - if any other configuration-related error occurs

See Also:

getValue(Map, String, Converter, String)

getValue

public <T> T getValue(Map<String,String> configurationCoordinates,
                      String name,
                      Converter<T> converter,
                      String defaultValue)

Returns an object that is the value for the configuration request represented by the supplied configurationCoordinates, name and defaultValue parameters, as converted by the supplied Converter.

This method may return null.

Type Parameters:

T - the type of the object to be returned

Parameters:

configurationCoordinates - the configuration coordinates for which a value should be selected; may be null

name - the name of the configuration property within the world defined by the supplied configurationCoordinates whose value is to be selected; must not be null

converter - a Converter instance that will convert any String configuration value into the type of object that this method will return; must not be null

defaultValue - the fallback default value to use as an absolute last resort; may be null; will also be converted by the supplied Converter

Returns:

the value for the implied configuration property, or null

Throws:

NullPointerException - if either name or converter is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable and arbitration was performed but could not resolve the dispute

ConfigurationException - if any other configuration-related error occurs

See Also:

Converter.convert(String), Configuration.getValue(Map, String), performArbitration(Map, String, Collection), handleMalformedConfigurationValues(Collection)

interpolate

public String interpolate(String value)

Interpolates any expressions occurring within the supplied value and returns the result of interpolation.

This method may return null.

Overrides of this method may return null.

The default implementation of this method performs interpolation by using a ValueExpression as produced by an ExpressionFactory.

A configurations object is made available to any Expression Language expressions, which exposes this Configurations object. This means, among other things, that you can retrieve configuration values using the following syntax:

${configurations["java.home"]}

Parameters:

value - a configuration value String, before any type conversion has taken place, with (possibly) expression language expressions in it; may be null in which case null is returned

Returns:

the result of interpolating the supplied value, or null

Throws:

PropertyNotFoundException - if the supplied value contained a valid expression language expression that identifies an unknown property

See Also:

the section in the Java EE Tutorial on the Unified Expression Language

getNames

public Set<String> getNames()

Returns a Set of names of ConfigurationValues that might be returned by this Configurations instance.

This method does not return null.

Overrides of this method must not return null.

This implementation does not cache results.

Just because a name appears in the returned Set does not mean that a ConfigurationValue will be returned for it in a location in configuration space identified by any arbitrary set of configuration coordinates.

Specified by:

getNames in class Configurations

Returns:

a non-null Set of names of ConfigurationValues

handleMalformedConfigurationValues

protected void handleMalformedConfigurationValues(Collection<ConfigurationValue> badValues)

Handles any badly formed ConfigurationValue instances received from Configuration instances during the execution of a configuration value request.

The default implementation of this method does nothing. Malformed values are thus effectively discarded.

This method is called from the getValue(Map, String, Converter, String) method.

Parameters:

badValues - a Collection of ConfigurationValue instances that were deemed to be malformed in some way; may be null

Throws:

ConfigurationException - if the getValue(Map, String, Converter, String) method should abort processing

See Also:

getValue(Map, String, Converter, String)

performArbitration

protected ConfigurationValue performArbitration(Map<? extends String,? extends String> configurationCoordinates,
                                                String name,
                                                Collection<? extends ConfigurationValue> values)

Given a logical request for a configuration value, represented by the configurationCoordinates and name parameter values, and a Collection of ConfigurationValue instances that represents the ambiguous response from several Configuration instances, attempts to resolve the ambiguity by returning a single ConfigurationValue instead.

This method may return null.

Overrides of this method may return null.

The default implementation of this method asks all registered Arbiters in turn to perform the arbitration and returns the first non-null response received.

Parameters:

configurationCoordinates - the (immutable) configuration coordinates in effect for the request; may be null

name - the name of the configuration value; may be null

values - an immutable Collection of definitionally ambiguous ConfigurationValues that resulted from the request; may be null

Returns:

the result of arbitration, or null

Throws:

AmbiguousConfigurationValuesException - if successful arbitration did not happen for any reason

See Also:

Arbiter