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.
      static java.util.regex.Pattern KEY_SEGMENTS_PATTERN
      The pattern for splitting out the segments of a compound key.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      static void check​(boolean test)
      Checks whether a configuration condition is correct, and throws a ConfigurationException if not.
      static void check​(boolean test, java.lang.String description, java.lang.Object... arguments)
      Checks whether a configuration condition is correct, and throws a ConfigurationException if not.
      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.
      default java.util.Optional<java.util.Collection<java.lang.Object>> findCollection​(java.lang.String key)
      Retrieves a collection of objects that may not be present, converting the underlying group of objects to a Collection if necessary.
      <E> java.util.Optional<java.util.Collection<E>> findCollection​(java.lang.String key, java.lang.Class<E> elementType)
      Retrieves a collection that may not be present, containing objects of the the requested type, converting the underlying group of objects to a Collection and converting each object to the correct type as necessary.
      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<Section> findSection​(java.lang.String key)
      Retrieves a section 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 java.util.Collection<java.lang.Object> getCollection​(java.lang.String key)
      Retrieves a collection of objects, converting the underlying group of objects to a Collection if necessary.
      default <E> java.util.Collection<E> getCollection​(java.lang.String key, java.lang.Class<E> elementType)
      Retrieves a collection, containing objects of the the requested type, converting the underlying group of objects to a Collection and converting each object to the correct type as necessary.
      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 Section getSection​(java.lang.String key)
      Retrieves a section by its key.
      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

      • KEY_SEGMENTS_PATTERN

        static final java.util.regex.Pattern KEY_SEGMENTS_PATTERN
        The pattern for splitting out the segments of a compound key.

    • Method Detail

      • empty

        static Configuration empty()
        Returns:
        An empty configuration.

      • check

        static void check​(boolean test,
                  @Nullable
                  java.lang.String description,
                  @Nonnull
                  java.lang.Object... arguments)
        Checks whether a configuration condition is correct, and throws a ConfigurationException if not.
        Parameters:
        test - The condition expression to test.
        description - A description of the test to be used when generating an exception, optionally formatted with arguments, or null for no description.
        arguments - The arguments to be applied when formatting, or an empty array if the message should not be formatted.
        Throws:
        java.lang.NullPointerException - if the given arguments is null.
        ConfigurationException - if the given test condition is false.
        java.lang.IllegalArgumentException - if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.
        See Also:
        String.format(String, Object...)

      • 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.

      • getCollection

        default java.util.Collection<java.lang.Object> getCollection​(@Nonnull
                                                             java.lang.String key)
                                                      throws ConfigurationException
        Retrieves a collection of objects, converting the underlying group of objects to a Collection if necessary. The returned collection may be read-only, and may be a copy of the original collection, in which case it will maintain the order of the original collection, but is guaranteed to implement Set if the underlying collection implements Set. If the collection is present but cannot be converted, a ConfigurationException will be thrown.

        The returned collection is guaranteed to be thread-safe and to be iterable even if the contents of the underlying configuration change during configuration.

        API Note:
        If no value is associated with the given key, an empty Optional will be returned, not an empty collection.
        Implementation Specification:
        This default version delegates to findCollection(String).
        Parameters:
        key - The configuration key.
        Returns:
        The optional configuration value associated with the given key.
        Throws:
        java.lang.NullPointerException - if the given key and 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.

      • findCollection

        default java.util.Optional<java.util.Collection<java.lang.Object>> findCollection​(@Nonnull
                                                                                  java.lang.String key)
                                                                           throws ConfigurationException
        Retrieves a collection of objects that may not be present, converting the underlying group of objects to a Collection if necessary. The returned collection may be read-only, and may be a copy of the original collection, in which case it will maintain the order of the original collection, but is guaranteed to implement Set if the underlying collection implements Set.

        The returned collection is guaranteed to be thread-safe and to be iterable even if the contents of the underlying configuration change during configuration.

        API Note:
        If no value is associated with the given key, an empty Optional will be returned, not an empty collection.
        Implementation Specification:
        This default version delegates to findCollection(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 and 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.

      • getCollection

        default <E> java.util.Collection<E> getCollection​(@Nonnull
                                                  java.lang.String key,
                                                  @Nonnull
                                                  java.lang.Class<E> elementType)
                                           throws ConfigurationException
        Retrieves a collection, containing objects of the the requested type, converting the underlying group of objects to a Collection and converting each object to the correct type as necessary. If an object cannot be converted, a ConfigurationException will be thrown. The returned collection may be read-only, and may be a copy of the original collection, in which case it will maintain the order of the original collection, but is guaranteed to implement Set if the underlying collection implements Set. If the collection is present but cannot be converted, a ConfigurationException will be thrown.

        The returned collection is guaranteed to be thread-safe and to be iterable even if the contents of the underlying configuration change during configuration.

        API Note:
        If no value is associated with the given key, an empty Optional will be returned, not an empty collection.
        Implementation Specification:
        This default version delegates to findCollection(String, Class).
        Type Parameters:
        E - The type of elements in this collection
        Parameters:
        key - The configuration key.
        elementType - The type of objects requested in the collection.
        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.
        MissingConfigurationKeyException - if no configuration is associated with the given key.
        ConfigurationException - if there is a configuration value stored in an invalid format.

      • findCollection

        <E> java.util.Optional<java.util.Collection<E>> findCollection​(@Nonnull
                                                               java.lang.String key,
                                                               @Nonnull
                                                               java.lang.Class<E> elementType)
                                                        throws ConfigurationException
        Retrieves a collection that may not be present, containing objects of the the requested type, converting the underlying group of objects to a Collection and converting each object to the correct type as necessary. If an object cannot be converted, a ConfigurationException will be thrown. The returned collection may be read-only, and may be a copy of the original collection, in which case it will maintain the order of the original collection, but is guaranteed to implement Set if the underlying collection implements Set.

        The returned collection is guaranteed to be thread-safe and to be iterable even if the contents of the underlying configuration change during configuration.

        API Note:
        If no value is associated with the given key, an empty Optional will be returned, not an empty collection.
        Type Parameters:
        E - The type of elements in this collection
        Parameters:
        key - The configuration key.
        elementType - The type of objects requested in the collection.
        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.

      • getSection

        @Nonnull
default Section getSection​(@Nonnull
                           java.lang.String key)
                    throws MissingConfigurationKeyException,
                           ConfigurationException
        Retrieves a section by its key.
        API Note:
        The returned section is considered a compound entity local to the section root, and retrieval of the values it contains does not support fallback lookup. If fallback lookup is desired, use a compound key relative to the section root configuration.
        Implementation Specification:
        This default version delegates to findSection(String).
        Parameters:
        key - The configuration key.
        Returns:
        The section 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.

      • findSection

        java.util.Optional<Section> findSection​(@Nonnull
                                        java.lang.String key)
                                 throws ConfigurationException
        Retrieves a section that may not be present.
        API Note:
        The returned section is considered a compound entity local to the section root, and retrieval of the values it contains does not support fallback lookup. If fallback lookup is desired, use a compound key relative to the section root configuration.
        Parameters:
        key - The configuration key.
        Returns:
        The optional section 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.

      • 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., A subconfiguration differs from a section in that a subconfiguration is a view of the original configuration and follows the original configuration's fallback rule, while a section acts merely like a compound value reflecting only local settings.
        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.