Package io.confound.config.file

Class FileSystemConfigurationManager

  • All Implemented Interfaces:
    io.clogr.Clogged, io.confound.config.ConfigurationManager
    public class FileSystemConfigurationManager
extends AbstractFileConfigurationManager
implements io.clogr.Clogged
    A configuration manager that can load and parse a configuration from the file system.
    Author:
    Garret Wilson

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_BASE_FILENAME
      The default base filename to use for determining a file system resource.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected FileSystemConfigurationManager​(java.lang.Iterable<ConfigurationFileFormat> fileFormats, java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier, boolean required)
      File formats, candidate paths supplier, and optional required constructor.
        FileSystemConfigurationManager​(java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier)
      Constructor for an optional configuration.
        FileSystemConfigurationManager​(java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier, boolean required)
      Constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static FileSystemConfigurationManager forBaseFilename​(java.nio.file.Path directory, java.lang.String baseFilename)
      Creates a configuration manager that discovers an optional configuration file using a base filename.
      static FileSystemConfigurationManager forCandidatePaths​(java.nio.file.Path... configurationCandidatePaths)
      Creates a configuration manager that discovers an optional configuration file from one of the given paths.
      static FileSystemConfigurationManager forDirectory​(java.nio.file.Path directory)
      Creates a configuration manager that discovers an optional configuration file using the default base filename "config".
      static FileSystemConfigurationManager forFilenameGlob​(java.nio.file.Path directory, java.lang.String filenameGlob)
      Creates a configuration manager that discovers an optional configuration file using a filename glob.
      static FileSystemConfigurationManager forFilenamePattern​(java.nio.file.Path directory, java.util.regex.Pattern filenamePattern)
      Creates a configuration manager that discovers an optional configuration file using a filename pattern.
      static FileSystemConfigurationManager forPath​(java.nio.file.Path configurationPath)
      Creates a configuration manager that loads an optional configuration from a given path as necessary.
      java.util.Optional<ConfigurationFileFormat> getFileFormat​(java.nio.file.Path path)
      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 path.
      java.util.Optional<io.confound.config.Configuration> loadConfiguration()
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForBaseFilename​(java.nio.file.Path directory, java.lang.String baseFilename)
      Discovers and loads an optional configuration file using a base filename.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForCandidatePaths​(java.nio.file.Path... configurationCandidatePaths)
      Discovers and loads an optional configuration file from one of the given paths.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForDirectory​(java.nio.file.Path directory)
      Discovers and loads an optional configuration file using the default base filename "config".
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForFilenameGlob​(java.nio.file.Path directory, java.lang.String filenameGlob)
      Discovers and loads an optional configuration file using a filename glob.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForFilenamePattern​(java.nio.file.Path directory, java.util.regex.Pattern filenamePattern)
      Discovers and loads an optional configuration file using a filename pattern.
      static java.util.Optional<io.confound.config.Configuration> loadConfigurationForPath​(java.nio.file.Path configurationPath)
      Loads an optional configuration from a given path as necessary.
      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_BASE_FILENAME

        public static final java.lang.String DEFAULT_BASE_FILENAME
        The default base filename to use for determining a file system resource.
        See Also:
        Constant Field Values

    • Constructor Detail

      • FileSystemConfigurationManager

        public FileSystemConfigurationManager​(@Nonnull
                                      java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier)
        Constructor for an optional configuration.

        The path supplier is allowed to throw UncheckedIOException when the stream is returned and during stream iteration.

        Parameters:
        configurationFileCandidatePathsSupplier - The strategy for determining candidate paths for finding a configuration.

      • FileSystemConfigurationManager

        public FileSystemConfigurationManager​(@Nonnull
                                      java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier,
                                      boolean required)
        Constructor.

        The path supplier is allowed to throw UncheckedIOException when the stream is returned and during stream iteration.

        Parameters:
        configurationFileCandidatePathsSupplier - The strategy for determining candidate paths for finding a configuration.
        required - Whether the manager requires a configuration to be determined when loading.

      • FileSystemConfigurationManager

        protected FileSystemConfigurationManager​(@Nonnull
                                         java.lang.Iterable<ConfigurationFileFormat> fileFormats,
                                         @Nonnull
                                         java.util.function.Supplier<java.util.stream.Stream<java.nio.file.Path>> configurationFileCandidatePathsSupplier,
                                         boolean required)
        File formats, candidate paths supplier, and optional required constructor.

        The path supplier is allowed to throw UncheckedIOException when the stream is returned and during stream iteration.

        Parameters:
        fileFormats - The file formats to support.
        configurationFileCandidatePathsSupplier - The strategy for determining candidate paths for finding a configuration.
        required - Whether the manager requires a configuration to be determined when loading.

    • Method Detail

      • getFileFormat

        public java.util.Optional<ConfigurationFileFormat> getFileFormat​(@Nonnull
                                                                 java.nio.file.Path path)
        Determines the file format to use for the given path based on the registered formats and the path filename extension(s).
        Parameters:
        path - The path for which the file format should be determined.
        Returns:
        The configured file format for the path, if any.
        Throws:
        java.lang.IllegalArgumentException - if the given 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 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

      • forPath

        public static FileSystemConfigurationManager forPath​(@Nonnull
                                                     java.nio.file.Path configurationPath)
        Creates a configuration manager that loads an optional configuration from a given path as necessary.
        Parameters:
        configurationPath - The path at which to find the configuration file.
        Returns:
        A configuration manager for the file at the given path.

      • forCandidatePaths

        public static FileSystemConfigurationManager forCandidatePaths​(@Nonnull
                                                               java.nio.file.Path... configurationCandidatePaths)
        Creates a configuration manager that discovers an optional configuration file from one of the given paths.

        The first configuration file with a supported format is used.

        Parameters:
        configurationCandidatePaths - The potential paths at which to find the configuration file.
        Returns:
        A configuration manager for one of the files at the given paths.
        Throws:
        java.lang.NullPointerException - if one of the paths is null.
        java.lang.IllegalArgumentException - if no paths are given, or if one of the given paths has no filename.

      • forDirectory

        public static FileSystemConfigurationManager forDirectory​(@Nonnull
                                                          java.nio.file.Path directory)
        Creates a configuration manager that discovers an optional configuration file using the default base filename "config".
        Parameters:
        directory - The source directory for configuration file discovery.
        Returns:
        A configuration manager to use a configuration file with the given base name.
        Throws:
        java.lang.NullPointerException - if the directory is null.
        See Also:
        forBaseFilename(Path, String), DEFAULT_BASE_FILENAME

      • forBaseFilename

        public static FileSystemConfigurationManager forBaseFilename​(@Nonnull
                                                             java.nio.file.Path directory,
                                                             @Nonnull
                                                             java.lang.String baseFilename)
        Creates a configuration manager that discovers an optional configuration file using a base filename.
        Parameters:
        directory - The source directory for configuration file discovery.
        baseFilename - The base filename, such as base, to return files with any extension, such as base.foo and base.foo.bar, or no extension at all.
        Returns:
        A configuration manager to use a configuration file with the given base name.
        Throws:
        java.lang.NullPointerException - if the directory and/or base filename is null.

      • forFilenameGlob

        public static FileSystemConfigurationManager forFilenameGlob​(@Nonnull
                                                             java.nio.file.Path directory,
                                                             @Nonnull
                                                             java.lang.String filenameGlob)
        Creates a configuration manager that discovers an optional configuration file using a filename glob.

        Only a single directory level is searched, regardless of the glob.

        Parameters:
        directory - The source directory for configuration file discovery.
        filenameGlob - The glob for matching files in the directory, such as foo?.{properties,xml} which would match both foot.xml and food.properties.
        Returns:
        A configuration manager to use a configuration file matched by the given filename glob.
        Throws:
        java.lang.NullPointerException - if the directory and/or filename glob is null.

      • forFilenamePattern

        public static FileSystemConfigurationManager forFilenamePattern​(@Nonnull
                                                                java.nio.file.Path directory,
                                                                @Nonnull
                                                                java.util.regex.Pattern filenamePattern)
        Creates a configuration manager that discovers an optional configuration file using a filename pattern.
        Parameters:
        directory - The source directory for configuration file discovery.
        filenamePattern - The regular expression pattern for matching files in the directory.
        Returns:
        A configuration manager to use a configuration file matched by the given filename pattern.
        Throws:
        java.lang.NullPointerException - if the directory and/or filename pattern is null.

      • loadConfigurationForPath

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForPath​(@Nonnull
                                                                                            java.nio.file.Path configurationPath)
                                                                                     throws java.io.IOException,
                                                                                            io.confound.config.ConfigurationException
        Loads an optional configuration from a given path as necessary.
        Parameters:
        configurationPath - The path at which to find the configuration file.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        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.

      • loadConfigurationForCandidatePaths

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForCandidatePaths​(@Nonnull
                                                                                                      java.nio.file.Path... configurationCandidatePaths)
                                                                                               throws java.io.IOException,
                                                                                                      io.confound.config.ConfigurationException
        Discovers and loads an optional configuration file from one of the given paths.

        The first configuration file with a supported format is used.

        Parameters:
        configurationCandidatePaths - The potential paths at which to find the configuration file.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        java.lang.NullPointerException - if one of the paths is null.
        java.lang.IllegalArgumentException - if no paths are given, or if one of the given paths has no filename.
        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.

      • loadConfigurationForDirectory

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForDirectory​(@Nonnull
                                                                                                 java.nio.file.Path directory)
                                                                                          throws java.io.IOException,
                                                                                                 io.confound.config.ConfigurationException
        Discovers and loads an optional configuration file using the default base filename "config".
        Parameters:
        directory - The source directory for configuration file discovery.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        java.lang.NullPointerException - if the directory 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:
        forBaseFilename(Path, String), DEFAULT_BASE_FILENAME

      • loadConfigurationForBaseFilename

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForBaseFilename​(@Nonnull
                                                                                                    java.nio.file.Path directory,
                                                                                                    @Nonnull
                                                                                                    java.lang.String baseFilename)
                                                                                             throws java.io.IOException,
                                                                                                    io.confound.config.ConfigurationException
        Discovers and loads an optional configuration file using a base filename.
        Parameters:
        directory - The source directory for configuration file discovery.
        baseFilename - The base filename, such as base, to return files with any extension, such as base.foo and base.foo.bar, or no extension at all.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        java.lang.NullPointerException - if the directory and/or 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.

      • loadConfigurationForFilenameGlob

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForFilenameGlob​(@Nonnull
                                                                                                    java.nio.file.Path directory,
                                                                                                    @Nonnull
                                                                                                    java.lang.String filenameGlob)
                                                                                             throws java.io.IOException,
                                                                                                    io.confound.config.ConfigurationException
        Discovers and loads an optional configuration file using a filename glob.

        Only a single directory level is searched, regardless of the glob.

        Parameters:
        directory - The source directory for configuration file discovery.
        filenameGlob - The glob for matching files in the directory, such as foo?.{properties,xml} which would match both foot.xml and food.properties.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        java.lang.NullPointerException - if the directory and/or filename glob 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.

      • loadConfigurationForFilenamePattern

        public static java.util.Optional<io.confound.config.Configuration> loadConfigurationForFilenamePattern​(@Nonnull
                                                                                                       java.nio.file.Path directory,
                                                                                                       @Nonnull
                                                                                                       java.util.regex.Pattern filenamePattern)
                                                                                                throws java.io.IOException,
                                                                                                       io.confound.config.ConfigurationException
        Discovers and loads an optional configuration file using a filename pattern.
        Parameters:
        directory - The source directory for configuration file discovery.
        filenamePattern - The regular expression pattern for matching files in the directory.
        Returns:
        The loaded configuration, which will not be present if no appropriate configuration was found.
        Throws:
        java.lang.NullPointerException - if the directory and/or filename pattern 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.