Package net.obvj.confectory

Class Configuration<T>

  • Type Parameters:
    T - the target configuration type
    All Implemented Interfaces:
    ConfigurationDataRetriever<T>, ConfigurationMetadataRetriever<T>
    public final class Configuration<T>
extends Object
implements ConfigurationDataRetriever<T>, ConfigurationMetadataRetriever<T>
    An object that contains configuration data from a specific source, as well as related metadata.

    A Configuration may also be defined as a combination of a Source and a Mapper, producing either a properties list, a JSON object, or a user-defined bean.

    Each Configuration may be assigned a namespace and precedence number, which determines an order of importance. So, once stored in a common configuration container, the object with the highest precedence value will be chosen first, taking precedence over the other ones in the same namespace.

    A Configuration object is eager by default, that is, the resource will be loaded directly during build() time. Optionally, a Configuration may be created with the lazy flag, indicating that the resource shall not be loaded until really needed.

    A Configuration may also be marked as optional, indicating that the configuration shall be loaded quietly, that is, an "empty" Configuration object will be instantiated even if the resource cannot be loaded (not default behavior).

    IMPORTANT: Use a ConfigurationBuilder to create a Configuration object. A builder instance can be retrieved by calling the static method builder(). For example: 

     Configuration<Properties> config = Configuration.<Properties>builder()
         .source(new ClasspathFileSource<>("my.properties"))
         .mapper(new PropertiesMapper())
         .namespace("default")
         .precedence(10)
         .build();
    Since:
    0.1.0
    Author:
    oswaldo.bapvic.jr (Oswaldo Junior)
    See Also:
    Source, Mapper, ConfigurationBuilder

    • Method Detail

      • getPrecedence

        public int getPrecedence()
        Description copied from interface: ConfigurationMetadataRetriever
        Returns the precedence value defined for this Configuration object.

        In a common container, objects with higher-precedence may be selected first in case of key collision.

        Specified by:
        getPrecedence in interface ConfigurationMetadataRetriever<T>
        Returns:
        an integer number representing the order of importance given to this Configuration

      • isOptional

        public boolean isOptional()
        Description copied from interface: ConfigurationMetadataRetriever
        Returns a flag indicating whether this Configuration is optional.

        An optional Configuration object may behave quietly in the event of a failure to load the data.

        Specified by:
        isOptional in interface ConfigurationMetadataRetriever<T>
        Returns:
        true if this Configuration setup is optional; false, otherwise

      • getBean

        public T getBean()
        Description copied from interface: ConfigurationDataRetriever
        Returns the configuration bean used by this data retriever, typically for manual handling and/or troubleshooting purposes.
        Specified by:
        getBean in interface ConfigurationDataRetriever<T>
        Returns:
        the configuration bean (Note: it can be null if the Configuration is marked as optional)

      • get

        public Object get​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the object associated with the specified key.

        Notes:

        • The actual return type may vary depending on the underlying implementation
        • On a JSON implementation, the return will usually be an array
        Specified by:
        get in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the object object associated with the specified key. Depending on the actual implementation, the result may be either null or an empty array if the specified key is not found

      • getAsString

        public String getAsString()
        Description copied from interface: ConfigurationDataRetriever
        Returns a string representation of the bean used by this data retriever, typically for manual handling and/or troubleshooting purposes.
        Specified by:
        getAsString in interface ConfigurationDataRetriever<T>
        Returns:
        a string representation of the configuration bean (Note: it can be null if the Configuration is marked as optional)

      • getBoolean

        public Boolean getBoolean​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Boolean object associated with the specified key.
        Specified by:
        getBoolean in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the Boolean object associated with the specified key; null if not found

      • getInteger

        public Integer getInteger​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Integer object associated with the specified key.
        Specified by:
        getInteger in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath
        Returns:
        the Integer object associated with the specified key; null if not found

      • getLong

        public Long getLong​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Long object associated with the specified key.
        Specified by:
        getLong in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath
        Returns:
        the Long object associated with the specified key; null if not found

      • getDouble

        public Double getDouble​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Double object associated with the specified key.
        Specified by:
        getDouble in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath
        Returns:
        the Double object associated with the specified key; null if not found

      • getString

        public String getString​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the String object associated with the specified key.
        Specified by:
        getString in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the String object associated with the specified key; null if not found

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public boolean equals​(Object other)
        Indicates whether some other object is "equal to" this one.

        Two Configuration objects can be considered equal if both share the same namespace and Source.

        Overrides:
        equals in class Object
        Parameters:
        other - the other object with which to compare
        Returns:
        true if this object is the same as the one specified in the argument; false otherwise.

      • getMandatoryBoolean

        public Boolean getMandatoryBoolean​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Boolean object associated with the specified key, throwing an exception if not found.
        Specified by:
        getMandatoryBoolean in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the Boolean value associated with the specified key; never null

      • getMandatoryInteger

        public Integer getMandatoryInteger​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Integer object associated with the specified key, throwing an exception if not found.
        Specified by:
        getMandatoryInteger in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the Integer object associated with the specified key; never null

      • getMandatoryLong

        public Long getMandatoryLong​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Long object associated with the specified key, throwing an exception if not found.
        Specified by:
        getMandatoryLong in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the Long object associated with the specified key; never null

      • getMandatoryDouble

        public Double getMandatoryDouble​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the Double object associated with the specified key, throwing an exception if not found.
        Specified by:
        getMandatoryDouble in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the Double object associated with the specified key; never null

      • getMandatoryString

        public String getMandatoryString​(String key)
        Description copied from interface: ConfigurationDataRetriever
        Returns the String object associated with the specified key, throwing an exception if not found.
        Specified by:
        getMandatoryString in interface ConfigurationDataRetriever<T>
        Parameters:
        key - the object key (some implementations may also accept a path expression, e.g: JSONPath)
        Returns:
        the String object associated with the specified key; never null

      • merge

        public Configuration<T> merge​(Configuration<T> other)
        Combines this Configuration with another one, producing a new Configuration.

        The resulting Configuration will receive all the elements from both objects. In case of conflicting keys, the values at the highest-precedence Configuration will be selected.

        The metadata of the highest-precedence Configuration (namespace and precedence) will be applied to the new Configuration.

        Note: The other Configuration must be of the same type as the current one.

        Parameters:
        other - the Configuration to be merged with this one; not null
        Returns:
        a new Configuration resulting from the combination of this object and the specified one
        Throws:
        NullPointerException - if the other Configuration is null
        Since:
        2.2.0
        See Also:
        ConfigurationMerger

      • merge

        public Configuration<T> merge​(Configuration<T> other,
                              net.obvj.jsonmerge.JsonMergeOption... mergeOptions)
        Combines this Configuration with another one, producing a new Configuration, using advanced options.

        The resulting Configuration will receive all the elements from both objects. In case of conflicting keys, the values at the highest-precedence Configuration will be selected.

        The metadata of the highest-precedence Configuration (namespace and precedence) will be applied to the new Configuration.

        Note: The other Configuration must be of the same type as the current one.

        Parameters:
        other - the Configuration to be merged with this one; not null
        mergeOptions - an array of options on how to merge the objects (optional)
        Returns:
        a new Configuration resulting from the combination of this object and the specified one
        Throws:
        NullPointerException - if the other Configuration is null
        Since:
        2.2.0
        See Also:
        ConfigurationMerger