Package io.confound.config.file

Class 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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_CLASS_BASE_NAME_SUFFIX
      The default base name suffix to use for determining a configuration resource for a context class.
      static java.lang.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​(java.lang.ClassLoader classLoader, java.lang.String resourcePath)
      Class loader and resource path constructor for a required configuration file.
        ResourcesConfigurationManager​(java.lang.ClassLoader classLoader, java.lang.String resourcePath, boolean required)
      Class loader, resource path, and optional required constructor.
        ResourcesConfigurationManager​(java.lang.ClassLoader classLoader, java.lang.String resourceBasePath, java.lang.String resourceBaseName)
      Class loader, resource base path, and resource base name constructor for a required configuration file.
        ResourcesConfigurationManager​(java.lang.ClassLoader classLoader, java.lang.String resourceBasePath, java.lang.String resourceBaseName, boolean required)
      Class loader, resource base path, resource base name, and optional required constructor.
      protected ResourcesConfigurationManager​(java.lang.Iterable<ConfigurationFileFormat> fileFormats, java.lang.ClassLoader classLoader, java.lang.String resourcePath, java.lang.String resourceBaseName, boolean required)
      File formats, class loader, resource (base) path, resource base name, and optional required constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static ResourcesConfigurationManager forClass​(java.lang.Class<?> contextClass)
      Creates a configuration manager that loads a required configuration using the base filename suffix "-config" appended to a class' name, relative to the class, using the class' resource loader.
      static ResourcesConfigurationManager forPackage​(java.lang.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​(java.lang.Class<?> contextClass, java.lang.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​(java.lang.Class<?> contextClass, java.lang.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​(java.lang.ClassLoader classLoader, java.lang.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.
      java.util.Optional<ConfigurationFileFormat> getFileFormat​(java.lang.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.
      java.util.Optional<io.confound.config.Configuration> loadConfiguration()
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForClass​(java.lang.Class<?> contextClass)
      Loads an optional configuration using the base filename suffix "-config" appended to a class' name, relative to the class, using the class' resource loader.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForPackage​(java.lang.Class<?> contextClass)
      Loads an optional configuration using the default base filename "config" relative to a class, using the class' resource loader.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourceBaseName​(java.lang.Class<?> contextClass, java.lang.String resourceBaseName)
      Loads an optional configuration using a resource base filename relative to a class, using the class' resource loader.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourceName​(java.lang.Class<?> contextClass, java.lang.String resourceName)
      Loads an optional configuration using a complete resource filename relative to a class, using the class' resource loader.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourcePath​(java.lang.ClassLoader classLoader, java.lang.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.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 Detail

      • DEFAULT_PACKAGE_BASE_NAME

        public static final java.lang.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

      • DEFAULT_CLASS_BASE_NAME_SUFFIX

        public static final java.lang.String DEFAULT_CLASS_BASE_NAME_SUFFIX
        The default base name suffix to use for determining a configuration resource for a context class.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ResourcesConfigurationManager

        public ResourcesConfigurationManager​(@Nonnull
                                     java.lang.ClassLoader classLoader,
                                     @Nonnull
                                     java.lang.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:
        java.lang.IllegalArgumentException - if the given resource path does not include a filename.

      • ResourcesConfigurationManager

        public ResourcesConfigurationManager​(@Nonnull
                                     java.lang.ClassLoader classLoader,
                                     @Nonnull
                                     java.lang.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:
        java.lang.IllegalArgumentException - if the given resource path does not include a filename.

      • ResourcesConfigurationManager

        public ResourcesConfigurationManager​(@Nonnull
                                     java.lang.ClassLoader classLoader,
                                     @Nonnull
                                     java.lang.String resourceBasePath,
                                     @Nonnull
                                     java.lang.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:
        java.lang.IllegalArgumentException - if the given resource path includes a filename.

      • ResourcesConfigurationManager

        public ResourcesConfigurationManager​(@Nonnull
                                     java.lang.ClassLoader classLoader,
                                     @Nonnull
                                     java.lang.String resourceBasePath,
                                     @Nonnull
                                     java.lang.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:
        java.lang.IllegalArgumentException - if the given resource path includes a filename.

      • ResourcesConfigurationManager

        protected ResourcesConfigurationManager​(@Nonnull
                                        java.lang.Iterable<ConfigurationFileFormat> fileFormats,
                                        @Nonnull
                                        java.lang.ClassLoader classLoader,
                                        @Nonnull
                                        java.lang.String resourcePath,
                                        @Nonnull
                                        java.lang.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:
        java.lang.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 Detail

      • getFileFormat

        public java.util.Optional<ConfigurationFileFormat> getFileFormat​(@Nonnull
                                                                 java.lang.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:
        java.lang.IllegalArgumentException - if the given resource path has no filename.

      • loadConfiguration

        public java.util.Optional<io.confound.config.Configuration> loadConfiguration()
                                                                       throws java.io.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:
        java.io.IOException
        io.confound.config.ConfigurationException

      • saveConfiguration

        public void saveConfiguration​(io.confound.config.Configuration configuration)
                       throws java.io.IOException
        This implementation does not yet support saving configurations, and will throw an exception.
        Specified by:
        saveConfiguration in interface io.confound.config.ConfigurationManager
        Throws:
        java.io.IOException

      • isStale

        public boolean isStale​(io.confound.config.Configuration configuration)
                throws java.io.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:
        java.io.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
                                                            java.lang.ClassLoader classLoader,
                                                            @Nonnull
                                                            java.lang.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:
        java.lang.NullPointerException - if the class loader and/or resource path is null.

      • forResourceName

        public static ResourcesConfigurationManager forResourceName​(@Nonnull
                                                            java.lang.Class<?> contextClass,
                                                            @Nonnull
                                                            java.lang.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:
        java.lang.NullPointerException - if the resource filename is null.

      • forClass

        public static ResourcesConfigurationManager forClass​(@Nonnull
                                                     java.lang.Class<?> contextClass)
        Creates a configuration manager that loads a required configuration using the base filename suffix "-config" appended to a class' name, 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.
        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:
        java.lang.NullPointerException - if the context class is null.
        See Also:
        forResourceBaseName(Class, String), Class.getSimpleName(), DEFAULT_CLASS_BASE_NAME_SUFFIX

      • forPackage

        public static ResourcesConfigurationManager forPackage​(@Nonnull
                                                       java.lang.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:
        java.lang.NullPointerException - if the context class is null.
        See Also:
        forResourceBaseName(Class, String), DEFAULT_PACKAGE_BASE_NAME

      • forResourceBaseName

        public static ResourcesConfigurationManager forResourceBaseName​(@Nonnull
                                                                java.lang.Class<?> contextClass,
                                                                @Nonnull
                                                                java.lang.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:
        java.lang.NullPointerException - if the context class and/or resource base filename is null.

      • loadConfigurationForResourcePath

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourcePath​(@Nonnull
                                                                                                    java.lang.ClassLoader classLoader,
                                                                                                    @Nonnull
                                                                                                    java.lang.String resourcePath)
                                                                                             throws java.io.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:
        java.lang.NullPointerException - if the class loader and/or resource path is null.
        java.io.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 java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourceName​(@Nonnull
                                                                                                    java.lang.Class<?> contextClass,
                                                                                                    @Nonnull
                                                                                                    java.lang.String resourceName)
                                                                                             throws java.io.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:
        java.lang.NullPointerException - if the resource filename is null.
        java.io.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 java.util.Optional<io.confound.config.Configuration> loadConfigurationForClass​(@Nonnull
                                                                                             java.lang.Class<?> contextClass)
                                                                                      throws java.io.IOException,
                                                                                             io.confound.config.ConfigurationException
        Loads an optional configuration using the base filename suffix "-config" appended to a class' name, 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.
        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:
        java.lang.NullPointerException - if the context class is null.
        java.io.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(), DEFAULT_CLASS_BASE_NAME_SUFFIX

      • loadConfigurationForPackage

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForPackage​(@Nonnull
                                                                                               java.lang.Class<?> contextClass)
                                                                                        throws java.io.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:
        java.lang.NullPointerException - if the context class is null.
        java.io.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 java.util.Optional<io.confound.config.Configuration> loadConfigurationForResourceBaseName​(@Nonnull
                                                                                                        java.lang.Class<?> contextClass,
                                                                                                        @Nonnull
                                                                                                        java.lang.String resourceBaseName)
                                                                                                 throws java.io.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:
        java.lang.NullPointerException - if the context class and/or resource base filename is null.
        java.io.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.