org.microbean.microprofile.config

Class ConfigProviderResolver

java.lang.Object

org.eclipse.microprofile.config.spi.ConfigProviderResolver

org.microbean.microprofile.config.ConfigProviderResolver

All Implemented Interfaces:

AutoCloseable

public final class ConfigProviderResolver
extends ConfigProviderResolver
implements AutoCloseable

An AutoCloseable implementation of the abstract ConfigProviderResolver class.

Thread Safety

This class is safe for concurrent use by multiple threads.

Author:

Laird Nelson

See Also:

ConfigProviderResolver

Constructor Summary

Constructors

Constructor and Description
ConfigProviderResolver() Creates a new ConfigProviderResolver.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this ConfigProviderResolver using a best-effort strategy.
ConfigBuilder	getBuilder() Creates and returns a new ConfigBuilder.
Config	getConfig() Returns the sole Config instance appropriate for the context ClassLoader, creating and building a default one just in time if necessary.
Config	getConfig(ClassLoader classLoader) Returns the sole Config instance appropriate for the supplied ClassLoader, creating and building a default one just in time if necessary.
void	registerConfig(Config config, ClassLoader classLoader) Registers the supplied Config instance under the supplied ClassLoader in some way.
void	releaseConfig(Config config) Releases the supplied Config by closing it if it implements AutoCloseable and atomically removes all of its registrations.

Methods inherited from class org.eclipse.microprofile.config.spi.ConfigProviderResolver

instance, setInstance

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigProviderResolver

public ConfigProviderResolver()

Creates a new ConfigProviderResolver.

Method Detail

close

public final void close()

Closes this ConfigProviderResolver using a best-effort strategy.

This method attempts to release each of the AutoCloseable Config instances that are registered with it. If any exception occurs, it is aggregated with any others and thrown at the end of the whole process.

Thread Safety

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

Specified by:

close in interface AutoCloseable

Throws:

RuntimeException - if an error occurs

See Also:

registerConfig(Config, ClassLoader), releaseConfig(Config)

getBuilder

public final ConfigBuilder getBuilder()

Creates and returns a new ConfigBuilder.

This method never returns null.

Thread Safety

This method is safe for concurrent use by multiple threads.

The ConfigBuilder implementation is safe for concurrent use by multiple threads.

Implementation Notes

Because of the requirement of having an implementation of the ConfigBuilder.forClassLoader(ClassLoader) method, the ConfigBuilder implementation returned by this method may contain a strong reference to a ClassLoader supplied to it by that method. The programmer needs to take care that this does not result in classloader leaks. In general, ConfigBuilders should be retained for only as long as is necessary to build a Config and no longer.

Specified by:

getBuilder in class ConfigProviderResolver

Returns:

a new ConfigBuilder; never null

getConfig

public final Config getConfig()

Returns the sole Config instance appropriate for the context ClassLoader, creating and building a default one just in time if necessary.

Thread Safety

This method is safe for concurrent use by multiple threads.

This method never returns null.

Specified by:

getConfig in class ConfigProviderResolver

Returns:

a Config instance; never null

See Also:

getConfig(ClassLoader), Thread.getContextClassLoader(), ConfigProvider.getConfig()

getConfig

public final Config getConfig(ClassLoader classLoader)

Returns the sole Config instance appropriate for the supplied ClassLoader, creating and building a default one just in time if necessary.

Thread Safety

This method is safe for concurrent use by multiple threads.

Implementation Notes

The specification does not indicate what to do if the supplied ClassLoader is null, but spread throughout other areas of the specification there are implications that a null ClassLoader means that the current thread's context classloader should be used instead. This implementation follows those implications. See issue 426 for more details.

Specified by:

getConfig in class ConfigProviderResolver

Parameters:

classLoader - the ClassLoader used to identify the Config to return; may be null in which case the context ClassLoader will be used instead

Returns:

a Config instance; never null

See Also:

getBuilder(), getConfig(), MicroProfile Config issue 426

registerConfig

public final void registerConfig(Config config,
                                 ClassLoader classLoader)

Registers the supplied Config instance under the supplied ClassLoader in some way.

Thread Safety

This method is safe for concurrent use by multiple threads.

Implementation Notes

The specification says:

If the ClassLoader is null then the current Application will be used.

This implementation assumes "current Application" is equivalent to "current thread's context ClassLoader". See issue 426 for more details.

Specified by:

registerConfig in class ConfigProviderResolver

Parameters:

config - the Config to register; may be null in which case no action will be taken

classLoader - the ClassLoader to use as the key under which the supplied Config should be registered; if null then the return value of Thread.getContextClassLoader() will be used instead

See Also:

ConfigProviderResolver.registerConfig(Config, ClassLoader), MicroProfile Config issue 426

releaseConfig

public final void releaseConfig(Config config)

Releases the supplied Config by closing it if it implements AutoCloseable and atomically removes all of its registrations.

An AutoCloseable Config implementation released by this method becomes effectively unusable by design after this method completes.

In general, owing to the underspecified nature of this method, end users should probably not call it directly.

Thread Safety

This method is safe for concurrent use by multiple threads.

Implementation Notes

The specification says:

A Config normally gets released if the Application it is associated with gets destroyed.

This implementation assumes the previous sentence means that if a Config was previously registered under a ClassLoader A, and under a ClassLoader B, then both registrations will be deleted. The equivalence between "Application" and ClassLoader is derived from the documentation for the ConfigProvider.getConfig() method, where there is an implication that the context classloader will be used as the key under which the Config to be returned may be found.

Elsewhere in the specification, it is stated:

There is exactly a single Config instance per ClassLoader[.]

This is of course false since there may be zero Config instances per ClassLoader. Leaving that aside, this sentence also does not say whether it is permitted for a single Config instance to be shared between two ClassLoaders. This implementation permits such perhaps edge cases, but a call to this releaseConfig(Config) method will remove both such registrations if present.

The specification has no guidance on what to do if a Config is released, and then another one is acquired via ConfigProvider.getConfig(ClassLoader), if anything. This implementation does not track Config instances once they have been released.

The specification does not indicate whether the supplied Config must be non-null. This implementation consequently accepts null Configs and does nothing in such cases.

This method is called by the close() method.

Specified by:

releaseConfig in class ConfigProviderResolver

Parameters:

config - the Config to release; may be null in which case no action will be taken

See Also:

close(), registerConfig(Config, ClassLoader)