org.microbean.configuration.api

Class Configurations

java.lang.Object

org.microbean.configuration.api.Configurations

public abstract class Configurations
extends Object

A single source for configuration values suitable for an application.

Author:

Laird Nelson

See Also:

getValue(Map, String, Type, String)

Field Summary

Fields

Modifier and Type	Field and Description
protected Logger	logger A Logger for this Configurations.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Configurations() Creates a new Configurations.

Method Summary

Modifier and Type	Method and Description
protected Logger	createLogger() Returns a Logger for use by this Configurations implementation.
abstract 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.
abstract Set<Type>	getConversionTypes() Returns a non-null, immutable Set of Types representing all the types to which String-typed configuration values may be converted by this Configurations object.
abstract Set<String>	getNames() Returns an unmodifiable Set of names of ConfigurationValues that might be returned by this Configurations instance.
String	getValue(Collection<String> names) Returns a configuration value corresponding to the configuration property suitable for the supplied names, or null.
<T> T	getValue(Collection<String> names, Class<T> type) Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or null.
<T> T	getValue(Collection<String> names, Class<T> type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or the supplied defaultValue.
String	getValue(Collection<String> names, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied names, or the supplied defaultValue.
<T> T	getValue(Collection<String> names, Type type) Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or null.
<T> T	getValue(Collection<String> names, TypeLiteral<T> typeLiteral) Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied typeLiteral, or null.
<T> T	getValue(Collection<String> names, TypeLiteral<T> typeLiteral, String defaultValue)
<T> T	getValue(Collection<String> names, Type type, String defaultValue)
String	getValue(Map<String,String> configurationCoordinates, Collection<String> names) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, or null.
<T> T	getValue(Map<String,String> configurationCoordinates, Collection<String> names, Class<T> type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied type.
String	getValue(Map<String,String> configurationCoordinates, Collection<String> names, 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.
<T> T	getValue(Map<String,String> configurationCoordinates, Collection<String> names, TypeLiteral<T> typeLiteral, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied type.
<T> T	getValue(Map<String,String> configurationCoordinates, Collection<String> names, Type type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied type.
String	getValue(Map<String,String> configurationCoordinates, String name) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Class<T> type) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the supplied type.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Class<T> 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 supplied type.
String	getValue(Map<String,String> configurationCoordinates, String name, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, or the supplied defaultValue if otherwise null would be returned.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, Type type) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied type.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, TypeLiteral<T> typeLiteral) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied typeLiteral.
<T> T	getValue(Map<String,String> configurationCoordinates, String name, TypeLiteral<T> typeLiteral, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied typeLiteral.
abstract <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.
String	getValue(String name) Returns a configuration value corresponding to the configuration property with the supplied name.
<T> T	getValue(String name, Class<T> type) Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the supplied type.
<T> T	getValue(String name, Class<T> type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the supplied type.
String	getValue(String name, String defaultValue) Returns a configuration value corresponding to the configuration property with the supplied name, or the supplied defaultValue if otherwise null would be returned.
<T> T	getValue(String name, Type type) Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the type represented by the supplied type.
<T> T	getValue(String name, TypeLiteral<T> typeLiteral) Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the type represented by the supplied typeLiteral.
<T> T	getValue(String name, TypeLiteral<T> typeLiteral, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied name, or the supplied defaultValue if null would otherwise be returned, converted, if possible, to the type represented by the supplied typeLiteral.
<T> T	getValue(String name, Type type, String defaultValue) Returns a configuration value corresponding to the configuration property suitable for the supplied name, or the supplied defaultValue if otherwise null would be returned, converted, if possible, to the type represented by the supplied type.
static Configurations	newInstance() Returns a Configurations implementation found using the standard ServiceLoader mechanism.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final Logger logger

A Logger for this Configurations.

This field is never null.

See Also:

createLogger()

Constructor Detail

Configurations

protected Configurations()

Creates a new Configurations.

Throws:

IllegalStateException - if the createLogger() method returns null

See Also:

createLogger()

Method Detail

createLogger

protected Logger createLogger()

Returns a Logger for use by this Configurations implementation.

This method never returns null.

Overrides of this method must not return null.

Returns:

a non-null Logger

getConversionTypes

public abstract Set<Type> getConversionTypes()

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

This method never returns null.

Returns:

a non-null, immutable Set of Types

See Also:

TypeLiteral

getConfigurationCoordinates

public abstract 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.

Implementations of this method may return null.

Returns:

a Map of configuration coordinates; may be null

getValue

public final String getValue(String name)

Returns a configuration value corresponding to the configuration property with the supplied name.

This method may return null.

Parameters:

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final String getValue(String name,
                             String defaultValue)

Returns a configuration value corresponding to the configuration property with the supplied name, or the supplied defaultValue if otherwise null would be returned.

This method may return null.

Parameters:

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

defaultValue - the value to return if otherwise null would be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name.

This method may return null.

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

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

This method may return null.

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

defaultValue - the value to return if otherwise null would be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(String name,
                            Class<T> type)

Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the supplied type.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(String name,
                            Class<T> type,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the supplied type.

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

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the supplied type.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            String name,
                            Class<T> 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 supplied type.

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

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(String name,
                            TypeLiteral<T> typeLiteral)

Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the type represented by the supplied typeLiteral.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(String name,
                            TypeLiteral<T> typeLiteral,
                            String defaultValue)

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

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

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            String name,
                            TypeLiteral<T> typeLiteral)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied typeLiteral.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            String name,
                            TypeLiteral<T> typeLiteral,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied typeLiteral.

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

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

Returns a configuration value corresponding to the configuration property suitable for the supplied name, converted, if possible, to the type represented by the supplied type.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

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

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

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 and returned if null would otherwise be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

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

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, converted, if possible, to the type represented by the supplied type.

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getValue

public abstract <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.

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 and returned if null would otherwise be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

getValue

public final String getValue(Map<String,String> configurationCoordinates,
                             Collection<String> names,
                             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.

This method may return null.

Parameters:

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

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

getValue

public final String getValue(Map<String,String> configurationCoordinates,
                             Collection<String> names)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and name, or null.

This method may return null.

Parameters:

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

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if names or type is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

getValue

public final String getValue(Collection<String> names)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, or null.

This method may return null.

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if names is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

getValue

public final String getValue(Collection<String> names,
                             String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, or the supplied defaultValue.

This method may return null.

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

Returns:

the configuration value, or the supplied defaultValue

Throws:

NullPointerException - if names is null

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

getValue

public final <T> T getValue(Collection<String> names,
                            Class<T> type,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or the supplied defaultValue.

This method may return null.

Type Parameters:

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

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

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

Returns:

the configuration value, or the supplied defaultValue

Throws:

NullPointerException - if names or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

public final <T> T getValue(Collection<String> names,
                            Type type,
                            String defaultValue)

getValue

public final <T> T getValue(Collection<String> names,
                            TypeLiteral<T> typeLiteral,
                            String defaultValue)

getValue

public final <T> T getValue(Collection<String> names,
                            Class<T> type)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or null.

This method may return null.

Type Parameters:

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

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if names or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

public final <T> T getValue(Collection<String> names,
                            Type type)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied type, or null.

This method may return null.

Type Parameters:

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

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if names or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

public final <T> T getValue(Collection<String> names,
                            TypeLiteral<T> typeLiteral)

Returns a configuration value corresponding to the configuration property suitable for the supplied names, converted, if possible, to the type represented by the supplied typeLiteral, or null.

This method may return null.

Type Parameters:

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

Parameters:

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            Collection<String> names,
                            Class<T> type,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, 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.

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

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

public final <T> T getValue(Map<String,String> configurationCoordinates,
                            Collection<String> names,
                            TypeLiteral<T> typeLiteral,
                            String defaultValue)

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, 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.

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

names - names of configuration properties for which a value will be returned; each element will be tried in turn; must not be null

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

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

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, Collection, Type, String)

getValue

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

Returns a configuration value corresponding to the configuration property suitable for the supplied configurationCoordinates and names, 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.

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

names - names of configuration properties for which a value will be returned; each element will be tried in turn; 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 and returned if null would otherwise be returned; may be null

Returns:

the configuration value, or null

Throws:

NullPointerException - if name or type is null

ConversionException - if type conversion could not occur for any reason

AmbiguousConfigurationValuesException - if two or more values were found that could be suitable

See Also:

getValue(Map, String, Type, String)

getNames

public abstract Set<String> getNames()

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

Implementations of this method must not return null.

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.

Returns:

a non-null Set of names of ConfigurationValues

newInstance

public static final Configurations newInstance()

Returns a Configurations implementation found using the standard ServiceLoader mechanism.

The first entry in the first classpath resource named META-INF/services/org.microbean.configuration.api.Configurations will be treated as a class name, loaded and instantiated, and returned.

Returns:

a non-null Configurations instance

Throws:

ConfigurationException - if there was no implementation found

See Also:

ServiceLoader