Package io.confound.config.file

Class ResourcesConfigurationManager

java.lang.Object

io.confound.config.AbstractConfigurationManager

io.confound.config.file.AbstractFileConfigurationManager

io.confound.config.file.ResourcesConfigurationManager

All Implemented Interfaces:

io.clogr.Clogged, io.confound.config.ConfigurationManager

public class ResourcesConfigurationManager
extends AbstractFileConfigurationManager
implements io.clogr.Clogged

A configuration manager that can load and parse a configuration from class resources.

This configuration manager is similar to a FileSystemConfigurationManager, except that it only has two algorithms for looking up resources: a single resource path (either relative or absolute), or a resource path and base resource filename. This configuration manager by default requires a configuration, as it is assumed that no resources configuration would be configured unless it were known ahead of time that the configuration resource exists.

Author:

Garret Wilson

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ResourcesConfigurationManager.Builder	Builder for the manager.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CONFIG_CLASSIFIER	The default classifier to use for determining a configuration resource for a context package or class.
static final String	DEFAULT_PACKAGE_BASE_NAME	The default base name to use for determining a configuration resource for a context package.

Constructor Summary

Constructors

Modifier	Constructor	Description
	ResourcesConfigurationManager(ClassLoader classLoader, String resourcePath)	Class loader and resource path constructor for a required configuration file.
	ResourcesConfigurationManager(ClassLoader classLoader, String resourcePath, boolean required)	Class loader, resource path, and optional required constructor.
	ResourcesConfigurationManager(ClassLoader classLoader, String resourceBasePath, String resourceBaseName)	Class loader, resource base path, and resource base name constructor for a required configuration file.
	ResourcesConfigurationManager(ClassLoader classLoader, String resourceBasePath, String resourceBaseName, boolean required)	Class loader, resource base path, resource base name, and optional required constructor.
protected	ResourcesConfigurationManager(Iterable<ConfigurationFileFormat> fileFormats, ClassLoader classLoader, String resourcePath, String resourceBaseName, boolean required)	File formats, class loader, resource (base) path, resource base name, and optional required constructor.

Method Summary

Modifier and Type	Method	Description
static ResourcesConfigurationManager	forClass(Class<?> contextClass)	Creates a configuration manager that loads a required configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader.
static ResourcesConfigurationManager	forClass(Class<?> contextClass, String classifier)	Creates a configuration manager that loads a required configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader.
static ResourcesConfigurationManager	forPackage(Class<?> contextClass)	Creates a configuration manager that loads a required configuration using the default base filename "config" relative to a class, using the class' resource loader.
static ResourcesConfigurationManager	forResourceBaseName(Class<?> contextClass, String resourceBaseName)	Creates a configuration manager that loads a required configuration using a resource base filename relative to a class, using the class' resource loader.
static ResourcesConfigurationManager	forResourceName(Class<?> contextClass, String resourceName)	Creates a configuration manager that loads a required configuration using a complete resource filename relative to a class, using the class' resource loader.
static ResourcesConfigurationManager	forResourcePath(ClassLoader classLoader, String resourcePath)	Creates a configuration manager that loads a required configuration from a complete path to a configuration resource, relative to a class, using the class' resource loader.
Optional<ConfigurationFileFormat>	getFileFormat(String resourcePath)	Determines the file format to use for the given path based on the registered formats and the path filename extension(s).
void	invalidate()	This version additionally removes any cached configuration path.
boolean	isStale(io.confound.config.Configuration configuration)	This version additionally checks to see if whether there is a cached configuration resource path.
Optional<io.confound.config.Configuration>	loadConfiguration()
static Optional<io.confound.config.Configuration>	loadConfigurationForClass(Class<?> contextClass)	Loads an optional configuration using the classifier "config" appended to a class' name, using the class' resource loader.
static Optional<io.confound.config.Configuration>	loadConfigurationForClass(Class<?> contextClass, String classifier)	Loads an optional configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader.
static Optional<io.confound.config.Configuration>	loadConfigurationForPackage(Class<?> contextClass)	Loads an optional configuration using the default base filename "config" relative to a class, using the class' resource loader.
static Optional<io.confound.config.Configuration>	loadConfigurationForResourceBaseName(Class<?> contextClass, String resourceBaseName)	Loads an optional configuration using a resource base filename relative to a class, using the class' resource loader.
static Optional<io.confound.config.Configuration>	loadConfigurationForResourceName(Class<?> contextClass, String resourceName)	Loads an optional configuration using a complete resource filename relative to a class, using the class' resource loader.
static Optional<io.confound.config.Configuration>	loadConfigurationForResourcePath(ClassLoader classLoader, String resourcePath)	Loads an optional configuration from a complete path to a configuration resource, relative to a class, using the class' resource loader.
void	saveConfiguration(io.confound.config.Configuration configuration)	This implementation does not yet support saving configurations, and will throw an exception.

Methods inherited from class io.confound.config.file.AbstractFileConfigurationManager

createConfigurationNotFoundException, defaultFileFormats, getFileFormatForExtension, getFileFormatForFilename, getFileFormatsByExtension

Methods inherited from class io.confound.config.AbstractConfigurationManager

isRequired

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.clogr.Clogged

getLogger

Field Details

CONFIG_CLASSIFIER

public static final String CONFIG_CLASSIFIER

The default classifier to use for determining a configuration resource for a context package or class.

See Also:

• Constant Field Values

DEFAULT_PACKAGE_BASE_NAME

public static final String DEFAULT_PACKAGE_BASE_NAME

The default base name to use for determining a configuration resource for a context package.

See Also:

• Constant Field Values

Constructor Details

ResourcesConfigurationManager

public ResourcesConfigurationManager(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath)

Class loader and resource path constructor for a required configuration file.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourcePath - The full configuration resource path, relative to the classpath, including configuration filename.

Throws:

IllegalArgumentException - if the given resource path does not include a filename.

ResourcesConfigurationManager

public ResourcesConfigurationManager(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath,
 boolean required)

Class loader, resource path, and optional required constructor.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourcePath - The full configuration resource path, relative to the classpath, including configuration filename.

required - Whether the manager requires a configuration to be determined when loading.

Throws:

IllegalArgumentException - if the given resource path does not include a filename.

ResourcesConfigurationManager

public ResourcesConfigurationManager(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourceBasePath,
 @Nonnull
 String resourceBaseName)

Class loader, resource base path, and resource base name constructor for a required configuration file. Class loader, resource directory, and optional required constructor.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourceBasePath - The configuration resource base path, relative to the classpath, not including configuration filename.

resourceBaseName - The base filename to use for the resource, not including extension.

Throws:

IllegalArgumentException - if the given resource path includes a filename.

ResourcesConfigurationManager

public ResourcesConfigurationManager(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourceBasePath,
 @Nonnull
 String resourceBaseName,
 boolean required)

Class loader, resource base path, resource base name, and optional required constructor.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourceBasePath - The configuration resource base path, relative to the classpath, not including configuration filename.

resourceBaseName - The base filename to use for the resource, not including extension.

required - Whether the manager requires a configuration to be determined when loading.

Throws:

IllegalArgumentException - if the given resource path includes a filename.

ResourcesConfigurationManager

protected ResourcesConfigurationManager(@Nonnull
 Iterable<ConfigurationFileFormat> fileFormats,
 @Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath,
 @Nonnull
 String resourceBaseName,
 boolean required)

File formats, class loader, resource (base) path, resource base name, and optional required constructor.

Parameters:

fileFormats - The file formats to support.

classLoader - The class loader to use for loading a configuration resource.

resourcePath - The configuration resource base path, relative to the classpath, not including configuration filename and ending in a slash; or if no resource base name is specified, the full configuration resource path, relative to the classpath, including configuration filename.

resourceBaseName - The base filename to use for the resource, not including extension, or null if the resource path should be considered the full configuration path.

required - Whether the manager requires a configuration to be determined when loading.

Throws:

IllegalArgumentException - if a resource base name is given and the given resource path includes a filename, or if a resource base name is not given and the resource path does not contain a filename.

Method Details

getFileFormat

public Optional<ConfigurationFileFormat> getFileFormat(@Nonnull
 String resourcePath)

Determines the file format to use for the given path based on the registered formats and the path filename extension(s).

Parameters:

resourcePath - The resource path for which the file format should be determined.

Returns:

The configured file format for the resource path, if any.

Throws:

IllegalArgumentException - if the given resource path has no filename.

loadConfiguration

public Optional<io.confound.config.Configuration> loadConfiguration()
                                                             throws IOException,
io.confound.config.ConfigurationException

Specified by:

loadConfiguration in interface io.confound.config.ConfigurationManager

Implementation Specification:

This implementation uses the existing configuration path if it has been determined. If the configuration path has not been determined, such as if this manager has been invalidated using invalidate(), it determines a new configuration path and updates the record.

Throws:

IOException

io.confound.config.ConfigurationException

saveConfiguration

public void saveConfiguration(io.confound.config.Configuration configuration)
                       throws IOException

This implementation does not yet support saving configurations, and will throw an exception.

Specified by:

saveConfiguration in interface io.confound.config.ConfigurationManager

Throws:

IOException

isStale

public boolean isStale(io.confound.config.Configuration configuration)
                throws IOException

This version additionally checks to see if whether there is a cached configuration resource path.

Specified by:

isStale in interface io.confound.config.ConfigurationManager

Throws:

IOException

invalidate

public void invalidate()

This version additionally removes any cached configuration path.

Specified by:

invalidate in interface io.confound.config.ConfigurationManager

forResourcePath

public static ResourcesConfigurationManager forResourcePath(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath)

Creates a configuration manager that loads a required configuration from a complete path to a configuration resource, relative to a class, using the class' resource loader.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourcePath - The complete resource path such as com/example/foo.bar, relative to the classpath, for loading a configuration file from class resources.

Returns:

A configuration manager for the resource at the given path.

Throws:

NullPointerException - if the class loader and/or resource path is null.

forResourceName

public static ResourcesConfigurationManager forResourceName(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourceName)

Creates a configuration manager that loads a required configuration using a complete resource filename relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

resourceName - The resource filename, such as foo.bar for loading a configuration resource relative to the given class.

Returns:

A configuration manager for the resource with the given filename.

Throws:

NullPointerException - if the resource filename is null.

forClass

public static ResourcesConfigurationManager forClass(@Nonnull
 Class<?> contextClass)

Creates a configuration manager that loads a required configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader. For example calling this method with the class FooBar.class will look for a resource with the base name FooBar-config.properties.

Implementation Specification:

This implementation delegates to forClass(Class, String).

Parameters:

contextClass - The class providing the resource context for loading.

Returns:

A configuration manager for determining a resource with the base filename and suffix.

Throws:

NullPointerException - if the context class is null.

See Also:

• forResourceBaseName(Class, String)
• Class.getSimpleName()
• CONFIG_CLASSIFIER

forClass

public static ResourcesConfigurationManager forClass(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String classifier)

Creates a configuration manager that loads a required configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader. For example calling this method with the class Foo.class and a classifier of bar will look for a resource with the base name Foo-bar.properties.

API Note:

The name "classifier" was inspired by the Maven POM classifier used to identify variations of dependencies.

Parameters:

contextClass - The class providing the resource context for loading.

classifier - The identifier for extending the resource name for locating the configuration.

Returns:

A configuration manager for determining a resource with the base filename and suffix.

Throws:

NullPointerException - if the context class is null.

See Also:

• forResourceBaseName(Class, String)
• Class.getSimpleName()

forPackage

public static ResourcesConfigurationManager forPackage(@Nonnull
 Class<?> contextClass)

Creates a configuration manager that loads a required configuration using the default base filename "config" relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

Returns:

A configuration manager for determining a resource with the default base filename.

Throws:

NullPointerException - if the context class is null.

See Also:

• forResourceBaseName(Class, String)
• DEFAULT_PACKAGE_BASE_NAME

forResourceBaseName

public static ResourcesConfigurationManager forResourceBaseName(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourceBaseName)

Creates a configuration manager that loads a required configuration using a resource base filename relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

resourceBaseName - The base filename, such as base, to locate resources with extensions, such as base.foo, supported by installed configuration file formats.

Returns:

A configuration manager for determining a resource with the given base filename.

Throws:

NullPointerException - if the context class and/or resource base filename is null.

loadConfigurationForResourcePath

public static Optional<io.confound.config.Configuration> loadConfigurationForResourcePath(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath)
                                                                                   throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration from a complete path to a configuration resource, relative to a class, using the class' resource loader.

Parameters:

classLoader - The class loader to use for loading a configuration resource.

resourcePath - The complete resource path such as com/example/foo.bar, relative to the classpath, for loading a configuration file from class resources.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the class loader and/or resource path is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.

loadConfigurationForResourceName

public static Optional<io.confound.config.Configuration> loadConfigurationForResourceName(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourceName)
                                                                                   throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration using a complete resource filename relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

resourceName - The resource filename, such as foo.bar for loading a configuration resource relative to the given class.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the resource filename is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.

loadConfigurationForClass

public static Optional<io.confound.config.Configuration> loadConfigurationForClass(@Nonnull
 Class<?> contextClass)
                                                                            throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration using the classifier "config" appended to a class' name, using the class' resource loader. For example calling this method with the class FooBar.class will look for a resource with the base name FooBar-config.properties.

Implementation Specification:

This method delegates to loadConfigurationForClass(Class, String).

Parameters:

contextClass - The class providing the resource context for loading.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the context class is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.

See Also:

• forResourceBaseName(Class, String)
• Class.getSimpleName()
• CONFIG_CLASSIFIER

loadConfigurationForClass

public static Optional<io.confound.config.Configuration> loadConfigurationForClass(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String classifier)
                                                                            throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration using the given classifier appended to a class' name and separated by a dash - character, relative to the class, using the class' resource loader. For example calling this method with the class Foo.class and a classifier of bar will look for a resource with the base name Foo-bar.properties.

API Note:

The name "classifier" was inspired by the Maven POM classifier used to identify variations of dependencies.

Parameters:

contextClass - The class providing the resource context for loading.

classifier - The identifier for extending the resource name for locating the configuration.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the context class is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.

See Also:

• forResourceBaseName(Class, String)
• Class.getSimpleName()

loadConfigurationForPackage

public static Optional<io.confound.config.Configuration> loadConfigurationForPackage(@Nonnull
 Class<?> contextClass)
                                                                              throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration using the default base filename "config" relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the context class is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.

See Also:

• forResourceBaseName(Class, String)
• DEFAULT_PACKAGE_BASE_NAME

loadConfigurationForResourceBaseName

public static Optional<io.confound.config.Configuration> loadConfigurationForResourceBaseName(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourceBaseName)
                                                                                       throws IOException,
io.confound.config.ConfigurationException

Loads an optional configuration using a resource base filename relative to a class, using the class' resource loader.

Parameters:

contextClass - The class providing the resource context for loading.

resourceBaseName - The base filename, such as base, to locate resources with extensions, such as base.foo, supported by installed configuration file formats.

Returns:

The loaded configuration, which will not be present if no appropriate configuration was found.

Throws:

NullPointerException - if the context class and/or resource base filename is null.

IOException - if an I/O error occurs loading the configuration.

io.confound.config.ConfigurationException - If there is invalid data or invalid state preventing the configuration from being loaded.