Package io.confound.config

Interface Configuration

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static char KEY_SEGMENT_SEPARATOR
      The delimiter separating segments of a compound key, such as foo.bar.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default MissingConfigurationKeyException createMissingConfigurationKeyException​(java.lang.String key)
      Creates an exception indicating that a given configuration key could not be found.
      static Configuration empty()  
      java.util.Optional<java.lang.Boolean> findBoolean​(java.lang.String key)
      Retrieves a Boolean configuration value that may not be present.
      java.util.OptionalDouble findDouble​(java.lang.String key)
      Retrieves a floating point configuration value that may not be present.
      java.util.OptionalInt findInt​(java.lang.String key)
      Retrieves an integer configuration value that may not be present.
      default java.util.OptionalLong findLong​(java.lang.String key)
      Retrieves a long integer configuration value that may not be present.
      default java.util.Optional<java.lang.Object> findObject​(java.lang.String key)
      Retrieves a general configuration object that may not be present.
      <O> java.util.Optional<O> findObject​(java.lang.String key, java.lang.Class<O> type)
      Retrieves a general configuration object that may not be present as the requested type, converting it as necessary.
      java.util.Optional<java.nio.file.Path> findPath​(java.lang.String key)
      Retrieves a path configuration value that may not be present.
      java.util.Optional<java.lang.String> findString​(java.lang.String key)
      Retrieves a string configuration value that may not be present.
      java.util.Optional<java.net.URI> findUri​(java.lang.String key)
      Retrieves a URI configuration value that may not be present.
      default boolean getBoolean​(java.lang.String key)
      Retrieves a Boolean configuration value.
      default double getDouble​(java.lang.String key)
      Retrieves a floating point configuration value.
      default int getInt​(java.lang.String key)
      Retrieves an integer configuration value.
      default long getLong​(java.lang.String key)
      Retrieves a long integer configuration value.
      default java.lang.Object getObject​(java.lang.String key)
      Retrieves a general configuration object.
      default <O> O getObject​(java.lang.String key, java.lang.Class<O> type)
      Retrieves a general configuration object as the requested type, converting it as necessary.
      default java.nio.file.Path getPath​(java.lang.String key)
      Retrieves a path configuration value.
      default java.lang.String getString​(java.lang.String key)
      Retrieves a string configuration value.
      default java.net.URI getUri​(java.lang.String key)
      Retrieves a URI configuration value.
      boolean hasConfigurationValue​(java.lang.String key)
      Determines whether a configuration of some type exists for the given configuration key.
      default <T> T requireConfiguration​(java.util.Optional<T> value, java.lang.String key)
      Retrieves a required configuration from an Optional, throwing a MissingConfigurationKeyException if the configuration key was not present.
      default java.nio.file.Path resolvePath​(java.nio.file.Path path)
      Resolves the given path as appropriate.
      default Configuration subConfiguration​(java.lang.String prefixKey)
      Returns a subset of this configuration representing a subtree of the keyspace with the given key prefix.
      default Configuration superConfiguration​(java.lang.String prefixKey)
      Returns a superset of this configuration representing a broader keyspace with the given key prefix.
      default Configuration withFallback​(Configuration fallbackConfiguration)
      Returns a configuration equivalent to this configuration but that will fall back to a specified parent configuration if a value is not present.
      static Configuration withFallback​(Configuration configuration, java.util.Optional<Configuration> fallbackConfiguration)
      Utility method that returns a configuration equivalent to the given configuration but that will fall back to an optional parent configuration if a value is not present.

    • Field Detail

      • KEY_SEGMENT_SEPARATOR

        static final char KEY_SEGMENT_SEPARATOR
        The delimiter separating segments of a compound key, such as foo.bar.
        See Also:
        Constant Field Values

    • Method Detail

      • empty

        static Configuration empty()
        Returns:
        An empty configuration.

      • requireConfiguration

        default <T> T requireConfiguration​(@Nonnull
                                   java.util.Optional<T> value,
                                   @Nonnull
                                   java.lang.String key)
                            throws MissingConfigurationKeyException
        Retrieves a required configuration from an Optional, throwing a MissingConfigurationKeyException if the configuration key was not present.
        API Note:
        This method is primarily used to check the result of a configuration lookup call for the non-optional convenience configuration lookup versions.
        Implementation Specification:
        The default implementation delegates to createMissingConfigurationKeyException(String).
        Type Parameters:
        T - The type of configuration value to check.
        Parameters:
        value - The retrieved value.
        key - The configuration key.
        Returns:
        The retrieved value.
        Throws:
        MissingConfigurationKeyException - if the given configuration is not present.
        See Also:
        Optional.isPresent()

      • createMissingConfigurationKeyException

        default MissingConfigurationKeyException createMissingConfigurationKeyException​(@Nonnull
                                                                                java.lang.String key)
        Creates an exception indicating that a given configuration key could not be found.
        Parameters:
        key - The configuration key.
        Returns:
        The new exception.

      • hasConfigurationValue

        boolean hasConfigurationValue​(@Nonnull
                              java.lang.String key)
                       throws ConfigurationException
        Determines whether a configuration of some type exists for the given configuration key.
        Parameters:
        key - The configuration key.
        Returns:
        true if a value of any type could be retrieved from this configuration using the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getObject

        @Nonnull
default java.lang.Object getObject​(@Nonnull
                                   java.lang.String key)
                            throws MissingConfigurationKeyException,
                                   ConfigurationException
        Retrieves a general configuration object.
        Implementation Specification:
        This default version delegates to findObject(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findObject

        default java.util.Optional<java.lang.Object> findObject​(@Nonnull
                                                        java.lang.String key)
                                                 throws ConfigurationException
        Retrieves a general configuration object that may not be present.
        Implementation Specification:
        This default version delegates to findObject(String, Class) with type Object.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getObject

        @Nonnull
default <O> O getObject​(@Nonnull
                        java.lang.String key,
                        @Nonnull
                        java.lang.Class<O> type)
                 throws MissingConfigurationKeyException,
                        ConfigurationException
        Retrieves a general configuration object as the requested type, converting it as necessary. If the object is present but cannot be converted, a ConfigurationException will be thrown.
        Implementation Specification:
        This default version delegates to findObject(String, Class).
        Type Parameters:
        O - The type of configuration object expected.
        Parameters:
        key - The configuration key.
        type - The type of object requested.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key and/or type is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findObject

        <O> java.util.Optional<O> findObject​(@Nonnull
                                     java.lang.String key,
                                     @Nonnull
                                     java.lang.Class<O> type)
                              throws ConfigurationException
        Retrieves a general configuration object that may not be present as the requested type, converting it as necessary. If the object is present but cannot be converted, a ConfigurationException will be thrown.
        Type Parameters:
        O - The type of configuration object expected.
        Parameters:
        key - The configuration key.
        type - The type of object requested.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key and/or type is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getBoolean

        @Nonnull
default boolean getBoolean​(@Nonnull
                           java.lang.String key)
                    throws MissingConfigurationKeyException,
                           ConfigurationException
        Retrieves a Boolean configuration value.
        Implementation Specification:
        This default version delegates to findBoolean(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findBoolean

        java.util.Optional<java.lang.Boolean> findBoolean​(@Nonnull
                                                  java.lang.String key)
                                           throws ConfigurationException
        Retrieves a Boolean configuration value that may not be present.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getDouble

        @Nonnull
default double getDouble​(@Nonnull
                         java.lang.String key)
                  throws MissingConfigurationKeyException,
                         ConfigurationException
        Retrieves a floating point configuration value.
        API Note:
        This method returns a primitive value. If you prefer an object, call getObject(String, Class) with the desired class such as Double.
        Implementation Specification:
        This default version delegates to findDouble(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findDouble

        java.util.OptionalDouble findDouble​(@Nonnull
                                    java.lang.String key)
                             throws ConfigurationException
        Retrieves a floating point configuration value that may not be present.
        API Note:
        This method returns a primitive optional. If you prefer a normal Optional, call findObject(String, Class) with the desired class such as Double.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getInt

        @Nonnull
default int getInt​(@Nonnull
                   java.lang.String key)
            throws MissingConfigurationKeyException,
                   ConfigurationException
        Retrieves an integer configuration value.
        API Note:
        This method returns a primitive value. If you prefer an object, call getObject(String, Class) with the desired class such as Integer.
        Implementation Specification:
        This default version delegates to findInt(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findInt

        java.util.OptionalInt findInt​(@Nonnull
                              java.lang.String key)
                       throws ConfigurationException
        Retrieves an integer configuration value that may not be present.
        API Note:
        This method returns a primitive optional. If you prefer a normal Optional, call findObject(String, Class) with the desired class such as Integer.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getLong

        @Nonnull
default long getLong​(@Nonnull
                     java.lang.String key)
              throws MissingConfigurationKeyException,
                     ConfigurationException
        Retrieves a long integer configuration value.
        API Note:
        This method returns a primitive value. If you prefer an object, call getObject(String, Class) with the desired class such as Long.
        Implementation Specification:
        This default version delegates to findLong(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findLong

        default java.util.OptionalLong findLong​(@Nonnull
                                        java.lang.String key)
                                 throws ConfigurationException
        Retrieves a long integer configuration value that may not be present.
        API Note:
        This method returns a primitive optional. If you prefer a normal Optional, call findObject(String, Class) with the desired class such as Double.
        Implementation Specification:
        The default implementation delegates to findInt(String) for convenience.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • getPath

        @Nonnull
default java.nio.file.Path getPath​(@Nonnull
                                   java.lang.String key)
                            throws MissingConfigurationKeyException,
                                   ConfigurationException
        Retrieves a path configuration value.

        The path will be resolved using resolvePath(Path).

        Implementation Specification:
        This default version delegates to findPath(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findPath

        java.util.Optional<java.nio.file.Path> findPath​(@Nonnull
                                                java.lang.String key)
                                         throws ConfigurationException
        Retrieves a path configuration value that may not be present.

        The path will be resolved using resolvePath(Path).

        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • resolvePath

        default java.nio.file.Path resolvePath​(@Nonnull
                                       java.nio.file.Path path)
        Resolves the given path as appropriate. Absolute paths should not be modified. Relative paths may be resolved to some standard or configured absolute path, depending on the implementation. A common base path may be configured separately, stored elsewhere in the configuration, or encoded in the path string itself for example.
        Implementation Specification:
        The default implementation merely returns the given path.
        Parameters:
        path - The path to resolve.
        Returns:
        A resolved form of the path if appropriate.

      • getString

        @Nonnull
default java.lang.String getString​(@Nonnull
                                   java.lang.String key)
                            throws MissingConfigurationKeyException,
                                   ConfigurationException
        Retrieves a string configuration value.

        TODO discuss dereferencing

        Implementation Specification:
        This default version delegates to findString(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.
        See Also:
        Format.format(Object)

      • findString

        java.util.Optional<java.lang.String> findString​(@Nonnull
                                                java.lang.String key)
                                         throws ConfigurationException
        Retrieves a string configuration value that may not be present.

        TODO discuss dereferencing

        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.
        See Also:
        Format.format(Object)

      • getUri

        @Nonnull
default java.net.URI getUri​(@Nonnull
                            java.lang.String key)
                     throws MissingConfigurationKeyException,
                            ConfigurationException
        Retrieves a URI configuration value.
        Implementation Specification:
        This default version delegates to findUri(String).
        Parameters:
        key - The configuration key.
        Returns:
        The configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findUri

        java.util.Optional<java.net.URI> findUri​(@Nonnull
                                         java.lang.String key)
                                  throws ConfigurationException
        Retrieves a URI configuration value that may not be present.
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key is null.
        java.lang.SecurityException - If a security manager exists and it doesn't allow access to the specified configuration.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • withFallback

        default Configuration withFallback​(@Nonnull
                                   Configuration fallbackConfiguration)
        Returns a configuration equivalent to this configuration but that will fall back to a specified parent configuration if a value is not present. This configuration will remain unmodified.
        Parameters:
        fallbackConfiguration - The fallback configuration.
        Returns:
        A version of this configuration that uses fallback lookup.
        Throws:
        java.lang.NullPointerException - if the given fallback configuration is null.

      • withFallback

        static Configuration withFallback​(@Nonnull
                                  Configuration configuration,
                                  @Nonnull
                                  java.util.Optional<Configuration> fallbackConfiguration)
        Utility method that returns a configuration equivalent to the given configuration but that will fall back to an optional parent configuration if a value is not present. The given configuration will remain unmodified.
        Parameters:
        configuration - The configuration to optionally be given a fallback.
        fallbackConfiguration - The optional fallback configuration.
        Returns:
        A version of the configuration that uses fallback lookup or, if no fallback is present, the given configuration.
        Throws:
        java.lang.NullPointerException - if the given configuration and/or optional fallback configuration is null.
        See Also:
        withFallback(Configuration)

      • subConfiguration

        default Configuration subConfiguration​(@Nonnull
                                       java.lang.String prefixKey)
        Returns a subset of this configuration representing a subtree of the keyspace with the given key prefix. The subconfiguration acts as a live view of this configuration, but only has access to keys with the given prefix plus 46, and those keys will effectively have the prefix and delimiter removed. For example if a key prefix of foo.bar is given, only keys logically starting with foo.bar. would be accessible in the subconfiguration. A setting in this configuration with the key foo.bar.example would be accessible in the subconfiguration as example.
        API Note:
        The returned configuration is not merely a "subset" of the settings with identical keys; instead the returned keyspace represents a subtree of they keys, making the returned configuration a "subconfiguration" of the original.
        Parameters:
        prefixKey - The prefix not including the final segment separator 46, for settings to include.
        Returns:
        A configuration view representing a subtree of the configuration keyspace.

      • superConfiguration

        default Configuration superConfiguration​(@Nonnull
                                         java.lang.String prefixKey)
        Returns a superset of this configuration representing a broader keyspace with the given key prefix. The superconfiguration acts as a live view of this configuration, but all keys will effectively have the given prefix plus 46 added. For example if a key prefix of foo.bar is given, and this configuration has a key example, in the superconfiguration it will only be accessible using the key foo.bar.example.
        API Note:
        The returned configuration is not merely a "superset" of the settings with identical keys; instead the returned keyspace represents a parent tree of they keys, making the returned configuration a "superconfiguration" of the original.
        Parameters:
        prefixKey - The prefix not including the final segment separator 46, with which to prefix all settings.
        Returns:
        A configuration view representing a parent tree of the configuration keyspace.