Package com.impossibl.postgres.system

Class Setting<T>

  • Type Parameters:
    T - Type of the setting
    public class Setting<T>
extends Object
    Completely defined setting that can be transformed to/from text, use alternate names, carries a description and optional default value. Settings belong to groups that determine where they are valid. Groups can be global or local. If a group is global, all of its settings are global. Each setting requires a "primary" name (available via getName(). This name is used when storing settings and when displaying information about the setting. Each setting is allowed to have alternate names that can be used when searching a source for an setting's value. For example, the getSystem() method searches for a value in the system properties by looking up the primary name & then alternate names in turn until it finds a non-null value. All settings in global groups are required to have unique names (including their alternate names); it is enforced during instantiation and will throw an exception is duplicates are found. Getting Started: To declare a setting you need 3 things. A factory class, a Setting.Group, and a static field that holds the setting. Because the settings are used by annotation processing this is done via annotations. Factory: A setting factory is a simple class that holds one or more group and setting definitions and is annotated with the Setting.Factory annotation. \@Setting.Factory public class MySettings { // declare groups & settings here } Group: Each settings is required to belong to a group. Groups are declared using the Setting.Group.Info annotation and the Setting.Group.declare() initializer. \@Setting.Factory public class MySettings { \@Setting.Group.Info(id="my", desc="My Settings") public static final MY_GROUP = Setting.Group.declare(); } Setting: Now that you have a factory and a group you can define settings. It's done similarly to the group declaration but requires different information. \@Setting.Factory public class MySettings { \@Setting.Group.Info(id="my", desc="My Settings") public static final MY_GROUP = Setting.Group.declare(); \@Setting.Info(name="a.setting", group="my", desc"A Setting", def="10") public static final A = Setting.declare() } Annotation Processing: Setting & Setting.Group are designed to work with the "settingsgen" annotation processor. It generates documentation and an abstract JDBC datasource named AbstractGeneratedDataSource from all of the global settings groups. NOTE: Settings can be defined in code without annotations and thus without the support of the annotation processor. This is required for settings with types not supported by the processor. Annotation Supported Types: Although any type can be used with a setting only the following types can be declared via annotations using the annotation processor

    • Constructor Detail

      • Setting

        public Setting​(Setting.Group group,
               String description,
               Class<T> type,
               T defaultValue,
               Setting.Converter<T> fromString,
               Function<T,​String> toString,
               String[] names)
        Constructs a new setting instance with a static default value and without support via the annotation processor.
        Parameters:
        group - Group the setting belongs to.
        description - Description of the setting.
        type - Type of the setting.
        defaultValue - Default value of the setting in its native type.
        fromString - Functional that converts a string to this settings type.
        toString - Functional that converts a native setting value to a string.
        names - Primary & alternate names for the setting.

      • Setting

        public Setting​(Setting.Group group,
               String description,
               Class<T> type,
               Supplier<String> dynamicDefaultSupplier,
               Setting.Converter<T> fromString,
               Function<T,​String> toString,
               String[] names)
        Constructs a new setting instance with a dynamic default value and without support via the annotation processor.
        Parameters:
        group - Group the setting belongs to.
        description - Description of the setting.
        type - Type of the setting.
        dynamicDefaultSupplier - Supplier of the dynamic default value for this setting.
        fromString - Functional that converts a string to this settings type.
        toString - Functional that converts a native setting value to a string.
        names - Primary & alternate names for the setting.

    • Method Detail

      • declare

        public static <U> Setting<U> declare()
        Forward declare a setting that will be initialized by annotation processing.
        Returns:
        Uninitialized setting instance
        See Also:
        Setting

      • init

        public void init​(String groupId,
                 String description,
                 Class<T> type,
                 String defaultValue,
                 Setting.Converter<T> fromString,
                 Function<T,​String> toString,
                 String[] names)
        Initializes a forward declared setting instance. This is intended for use only by the annotation processor.
        Parameters:
        groupId - Id of the group the setting belongs to.
        description - Description of the setting.
        type - Type of the setting.
        fromString - Functional that converts a string to this settings type.
        toString - Functional that converts a native setting value to a string.
        names - Primary & alternate names for the setting.

      • init

        public void init​(String groupId,
                 String description,
                 Class<T> type,
                 Supplier<String> defaultValue,
                 Setting.Converter<T> fromString,
                 Function<T,​String> toString,
                 String[] names)
        Initializes a forward declared setting instance. This is intended for use only by the annotation processor.
        Parameters:
        groupId - Id of the group the setting belongs to.
        description - Description of the setting.
        type - Type of the setting.
        fromString - Functional that converts a string to this settings type.
        toString - Functional that converts a native setting value to a string.
        names - Primary & alternate names for the setting.

      • getGroup

        public Setting.Group getGroup()
        Retrieve the setting's group
        Returns:
        Group this setting belongs to

      • getName

        public String getName()
        Retrieve the primary name of this setting.
        Returns:
        Primary name of the setting.

      • getNames

        public String[] getNames()
        Get all names for this setting; including primary and alternate names.
        Returns:
        All names for this setting.

      • getType

        public Class<? extends T> getType()
        Retrieve the type of this setting.
        Returns:
        Type of this setting.

      • isDefaultDynamic

        public boolean isDefaultDynamic()
        Flag that tells whether the setting uses a dynamic or static default value.
        Returns:
        true if the default value is dynamic, false otherwise.

      • getDefault

        public T getDefault()
        Retrieve the default value of this setting.
        Returns:
        Default value of this setting.

      • getDefaultText

        public String getDefaultText()
        Retrieve the default value of this setting as text.
        Returns:
        Text version of the default value of this setting.

      • getDescription

        public String getDescription()
        Retrieve the description of this setting.
        Returns:
        Description of this setting.

      • fromString

        public T fromString​(String value)
        Convert a string to the setting's native type.
        Parameters:
        value - String value to parse.
        Returns:
        Value in the settings native type.
        Throws:
        IllegalArgumentException - If the value cannot be parsed.

      • toString

        public String toString​(T value)
        Convert a native type to a string value.
        Parameters:
        value - Native value to convert into text.
        Returns:
        Value in text form.

      • getSystem

        public T getSystem()
        Looks up the setting in system properties. This method tries all names (primary & alternates) in the order in which they were defined and returns the first non-null value. If no value is found the settings default value is returned.
        Returns:
        System property value of the setting or its default value.

      • get

        public T get​(Properties properties)
        Looks up the setting in the provided properties. This method tries all names (primary & alternates) in the order in which they were defined and returns the first non-null value. If no value is found the setting's getDefault() default) value is returned.
        Returns:
        Property value of the setting or its default value.

      • getText

        public String getText​(Properties properties)
        Looks up the setting in the provided properties, returning it as a text value. This method tries all names (primary & alternates) in the order in which they were defined and returns the first non-null value. If no value is found the setting's getDefaultText() default) value is returned.
        Returns:
        Property value of the setting or its default text value.