org.microbean.microprofile.config

Class Config

java.lang.Object

org.microbean.microprofile.config.Config

All Implemented Interfaces:

Closeable, Serializable, AutoCloseable, Config, TypeConverter

public final class Config
extends Object
implements Closeable, Config, Serializable, TypeConverter

A Serializable implementation of the Config interface that is also a Closeable TypeConverter.

Author:

Laird Nelson

See Also:

Config, Serialized Form

Constructor Summary

Constructors

Constructor and Description
Config() Creates a new Config with a default set of ConfigSources and a default set of Converters (including discovered Converters).
Config(Collection<? extends ConfigSource> sources, TypeConverter typeConverter) Creates a new Config instance.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this Config using a best-effort strategy.
<T> T	convert(String rawValue, Type type) Implements the TypeConverter.convert(String, Type) method by invoking the same method on this Config's affiliated TypeConverter supplied at construction time and returning the result.
Iterable<ConfigSource>	getConfigSources() Returns an Iterable representing a snapshot at a moment in time of this Config's affiliated ConfigSources as they existed at that time.
<T> Optional<T>	getOptionalValue(String name, Class<T> type) Returns an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type.
<T> Optional<T>	getOptionalValue(String name, Type type) Returns an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type.
Iterable<String>	getPropertyNames() Returns an Iterable representing a snapshot at a moment in time of the configuration property names as they existed at that time.
<T> T	getValue(String name, Class<T> type) Returns the value for the configuration property named by the supplied name, as converted to an object of the supplied type.
<T> T	getValue(String name, Type type) Returns the value for the configuration property named by the supplied name, as converted to an object of the supplied type.
boolean	isClosed() Returns true if this Config has been closed.

Methods inherited from class java.lang.Object

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

Constructor Detail

Config

public Config()
       throws IOException

Creates a new Config with a default set of ConfigSources and a default set of Converters (including discovered Converters).

Throws:

IOException - if an error occurs while reading a META-INF/microprofile-config.properties resource

ServiceConfigurationError - if there is a problem interacting with a ServiceLoader

Config

public Config(Collection<? extends ConfigSource> sources,
              TypeConverter typeConverter)

Creates a new Config instance.

The MicroProfile Config specification wants Config implementations to be acquired using ConfigProvider.getConfig() invocations. This constructor exists primarily for convenience.

Thread Safety

sources will be synchronized on and iterated over by this constructor, which may have implications on the type of Collection supplied.

Parameters:

sources - a Collection of ConfigSources; may be null; will be synchronized on and iterated over; copied by value; no reference is retained to this object

typeConverter - a TypeConverter implementation used for type conversion; must not be null; if it implements Closeable it will be closed by this Config's close() method

Throws:

NullPointerException - of typeConverter is null

See Also:

ConfigProviderResolver, ConfigProvider.getConfig()

Method Detail

close

public final void close()
                 throws IOException

Closes this Config using a best-effort strategy.

An attempt is made to close each ConfigSource that is itself an instance of Closeable and that was supplied to this Config at construction time. If any errors occur along the way, they are added as suppressed exceptions to an IOException which is thrown as a kind of aggregate.

When this method finishes normally, all of this Config's associated Closeable ConfigSources will be closed. In addition, the TypeConverter supplied at construction time will be closed as well if it implements Closeable.

Thread Safety

This method is idempotent and safe for concurrent use by multiple threads.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if at least one Closeable ConfigSource was not successfully closed or if the TypeConverter supplied at construction time implements Closeable and threw an IOException

isClosed

public final boolean isClosed()

Returns true if this Config has been closed.

A closed Config will throw IllegalStateException from most of its methods.

Thread Safety

This method is safe for use by multiple threads.

Returns:

true if this Config has been closed; false otherwise

See Also:

close()

getConfigSources

public final Iterable<ConfigSource> getConfigSources()

Returns an Iterable representing a snapshot at a moment in time of this Config's affiliated ConfigSources as they existed at that time.

This method never returns null.

The underlying collection of ConfigSources the returned Iterable is capable of iterating over is an immutable copy of the internal collection of ConfigSources managed by this Config.

The Iterable returned by this method creates Iterators that do not support the Iterator.remove() method.

The MicroProfile Config specification implies a state of affairs that permits ConfigSources "inside" a Config to come and go. Consequently, this method returns what is effectively a dissociated snapshot at a moment in time of a collection of ConfigSources that were once managed by this Config at that moment in time.

Thread Safety

This method is safe for use by multiple threads.

The Iterable returned by this method is safe for use by multiple threads.

Specified by:

getConfigSources in interface Config

Returns:

an Iterable of ConfigSources; never null

Throws:

IllegalStateException - if this Config has been closed

getPropertyNames

public final Iterable<String> getPropertyNames()

Returns an Iterable representing a snapshot at a moment in time of the configuration property names as they existed at that time.

This method never returns null.

The underlying collection of property names the returned Iterable is capable of iterating over is an immutable copy of the internal collection of configuration property names managed by this Config.

The Iterable returned by this method creates Iterators that do not support the Iterator.remove() method.

The MicroProfile Config specification implies a state of affairs that permits ConfigSources "inside" a Config to come and go. Consequently, this method returns what is effectively a dissociated snapshot at a moment in time of a collection of the configuration property names that were once managed by this Config at that moment in time.

No caching is performed by this method. Property names are harvested from calls to ConfigSource.getPropertyNames() on each ConfigSource present in the Iterable returned by the getConfigSources() method.

Thread Safety

This method is safe for use by multiple threads.

The Iterable returned by this method is safe for use by multiple threads.

Specified by:

getPropertyNames in interface Config

Returns:

an Iterable representing a snapshot of a collection of configuration property names which this Config manages; never null

Throws:

IllegalStateException - if this Config has been closed

getOptionalValue

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

Returns an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type.

This method never returns null.

This method does not cache the value it returns.

It is worth noting that the MicroProfile Config specification does not say anything about whether Converters are allowed to attempt to "convert" null values from ConfigSource.getValue(String) invocations into non-null objects. The MicroProfile Config TCK will fail if Converters _do_ attempt to work on null values, so this implementation never uses a null value for conversion.

Thread Safety

This method is safe for use by multiple threads.

Specified by:

getOptionalValue in interface Config

Type Parameters:

T - the type of the value being requested

Parameters:

name - the name of the configuration property whose converted value should be returned; may be null; passed unaltered to ConfigSource.getValue(String) so subject to that method's (unspecified) preconditions

type - the Class representing the type any non-null value should be converted to if possible; must not be null

Returns:

an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type; never null

Throws:

IllegalArgumentException - if the value could not be converted to the requested type

IllegalStateException - if this Config has been closed

See Also:

getOptionalValue(String, Type), getValue(String, Class), getValue(String, Type), ConfigSource.getValue(String), TypeConverter.convert(String, Type), Converter.convert(String)

getOptionalValue

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

Returns an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type.

This method never returns null.

This method does not cache the value it returns.

Thread Safety

This method is safe for use by multiple threads.

Type Parameters:

T - the type of the value being requested

Parameters:

name - the name of the configuration property whose converted value should be returned; may be null; passed unaltered to ConfigSource.getValue(String) so subject to that method's (unspecified) preconditions

type - the Type representing the type any non-null value should be converted to if possible; must not be null

Returns:

an Optional representing an optional configuration property value for the supplied name, as converted to an object of the supplied type; never null

Throws:

IllegalArgumentException - if the value could not be converted to the requested type

IllegalStateException - if this Config has been closed

See Also:

getOptionalValue(String, Class), getValue(String, Class), getValue(String, Type), ConfigSource.getValue(String), TypeConverter.convert(String, Type), Converter.convert(String)

getValue

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

Returns the value for the configuration property named by the supplied name, as converted to an object of the supplied type.

This method never returns null.

This method does not cache the value it returns.

The MicroProfile Config specification does not say whether implementations of the Config.getValue(String, Class) method may or may not return null. null values from ConfigSource.getValue(String) invocations are taken to indicate a given configuration property value's absence, however. Coupled with the fact that all Config.getValue(String, Class) are required to throw NoSuchElementExceptions when "the property isn't present in the configuration", this implementation chooses never to return null.

It is also worth noting that the MicroProfile Config specification does not say anything about whether Converters are allowed to attempt to "convert" null values from ConfigSource.getValue(String) invocations into non-null objects. The MicroProfile Config TCK will fail if Converters _do_ attempt to work on null values, so this implementation never uses a null value for conversion.

Thread Safety

This method is safe for use by multiple threads.

Specified by:

getValue in interface Config

Type Parameters:

T - the type of the values returned by this method

Parameters:

name - the name of the configuration property whose value should be returned; may be null; passed unaltered to ConfigSource.getValue(String) so subject to that method's (unspecified) preconditions

type - the Class representing the type any non-null value should be converted to if possible; must not be null

Returns:

the converted value; never null

Throws:

NoSuchElementException - if the requested configuration property value does not exist

IllegalStateException - if this Config has been closed

See Also:

ConfigSource.getValue(String), getValue(String, Type), getOptionalValue(String, Class), getOptionalValue(String, Type)

getValue

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

Returns the value for the configuration property named by the supplied name, as converted to an object of the supplied type.

This method never returns null.

This method does not cache the value it returns.

It is also worth noting that the MicroProfile Config specification does not say anything about whether Converters are allowed to attempt to "convert" null values from ConfigSource.getValue(String) invocations into non-null objects. The MicroProfile Config TCK will fail if Converters _do_ attempt to work on null values, so this implementation never uses a null value for conversion.

Thread Safety

This method is safe for use by multiple threads.

Type Parameters:

T - the type of the values returned by this method

Parameters:

name - the name of the configuration property whose value should be returned; may be null; passed unaltered to ConfigSource.getValue(String) so subject to that method's (unspecified) preconditions

type - the Type representing the type any non-null value should be converted to if possible; must not be null

Returns:

the converted value; never null

Throws:

NoSuchElementException - if the requested configuration property value does not exist

IllegalStateException - if this Config has been closed

See Also:

ConfigSource.getValue(String), getValue(String, Class), getOptionalValue(String, Class), getOptionalValue(String, Type)

convert

public final <T> T convert(String rawValue,
                           Type type)

Implements the TypeConverter.convert(String, Type) method by invoking the same method on this Config's affiliated TypeConverter supplied at construction time and returning the result.

This method may return null.

Thread Safety

This method is safe for use by multiple threads.

Specified by:

convert in interface TypeConverter

Type Parameters:

T - the type of the return value, assumed to be assignable to references of the supplied type

Parameters:

rawValue - the value to convert; may be null

type - the Type to which the current invocation of this method's return value should be assignable; must not be null

Returns:

an object assignable to the supplied type, or null

Throws:

NullPointerException - if type is null

IllegalArgumentException - if conversion could not occur for any reason

IllegalStateException - if this Config has been closed

See Also:

TypeConverter.convert(String, Type)