Class Setting<T>

  • All Implemented Interfaces:
    ToXContent, ToXContentObject
    Direct Known Subclasses:
    SecureSetting, Setting.AffixSetting

    public class Setting<T>
    extends java.lang.Object
    implements ToXContentObject
    A setting. Encapsulates typical stuff like default value, parsing, and scope. Some (SettingsProperty.Dynamic) can by modified at run time using the API. All settings inside elasticsearch or in any of the plugins should use this type-safe and generic settings infrastructure together with AbstractScopedSettings. This class contains several utility methods that makes it straight forward to add settings for the majority of the cases. For instance a simple boolean settings can be defined like this:
    
     public static final Setting<Boolean>; MY_BOOLEAN = Setting.boolSetting("my.bool.setting", true, SettingsProperty.NodeScope);
     
    To retrieve the value of the setting a Settings object can be passed directly to the get(Settings) method.
     final boolean myBooleanValue = MY_BOOLEAN.get(settings);
     
    It's recommended to use typed settings rather than string based settings. For example adding a setting for an enum type:
    
     public enum Color {
         RED, GREEN, BLUE;
     }
     public static final Setting<Color> MY_BOOLEAN =
         new Setting<>("my.color.setting", Color.RED.toString(), Color::valueOf, SettingsProperty.NodeScope);
     
     
    • Field Detail

      • defaultValue

        protected final java.util.function.Function<Settings,​java.lang.String> defaultValue
    • Constructor Detail

      • Setting

        public Setting​(Setting.Key key,
                       java.util.function.Function<Settings,​java.lang.String> defaultValue,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Property... properties)
        Creates a new Setting instance
        Parameters:
        key - the settings key for this setting.
        defaultValue - a default value function that returns the default values string representation.
        parser - a parser that parses the string rep into a complex datatype.
        properties - properties for this setting like scope, filtering...
      • Setting

        public Setting​(Setting.Key key,
                       java.util.function.Function<Settings,​java.lang.String> defaultValue,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Validator<T> validator,
                       Setting.Property... properties)
        Creates a new Setting instance.
        Parameters:
        key - the settings key for this setting
        defaultValue - a default value function that results a string representation of the default value
        parser - a parser that parses a string representation into the concrete type for this setting
        validator - a Setting.Validator for validating this setting
        properties - properties for this setting
      • Setting

        public Setting​(java.lang.String key,
                       java.lang.String defaultValue,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Property... properties)
        Creates a new Setting instance
        Parameters:
        key - the settings key for this setting.
        defaultValue - a default value.
        parser - a parser that parses the string rep into a complex datatype.
        properties - properties for this setting like scope, filtering...
      • Setting

        public Setting​(java.lang.String key,
                       java.lang.String defaultValue,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Validator<T> validator,
                       Setting.Property... properties)
        Creates a new Setting instance.
        Parameters:
        key - the settings key for this setting
        defaultValue - a default value function that results a string representation of the default value
        parser - a parser that parses a string representation into the concrete type for this setting
        validator - a Setting.Validator for validating this setting
        properties - properties for this setting
      • Setting

        public Setting​(java.lang.String key,
                       java.util.function.Function<Settings,​java.lang.String> defaultValue,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Property... properties)
        Creates a new Setting instance
        Parameters:
        key - the settings key for this setting.
        defaultValue - a default value function that returns the default values string representation.
        parser - a parser that parses the string rep into a complex datatype.
        properties - properties for this setting like scope, filtering...
      • Setting

        public Setting​(Setting.Key key,
                       Setting<T> fallbackSetting,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Property... properties)
        Creates a new Setting instance
        Parameters:
        key - the settings key for this setting.
        fallbackSetting - a setting who's value to fallback on if this setting is not defined
        parser - a parser that parses the string rep into a complex datatype.
        properties - properties for this setting like scope, filtering...
      • Setting

        public Setting​(java.lang.String key,
                       Setting<T> fallBackSetting,
                       java.util.function.Function<java.lang.String,​T> parser,
                       Setting.Property... properties)
        Creates a new Setting instance
        Parameters:
        key - the settings key for this setting.
        fallBackSetting - a setting to fall back to if the current setting is not set.
        parser - a parser that parses the string rep into a complex datatype.
        properties - properties for this setting like scope, filtering...
    • Method Detail

      • getKey

        public final java.lang.String getKey()
        Returns the settings key or a prefix if this setting is a group setting. Note: this method should not be used to retrieve a value from a Settings object. Use get(Settings) instead
        See Also:
        isGroupSetting()
      • getRawKey

        public final Setting.Key getRawKey()
        Returns the original representation of a setting key.
      • isDynamic

        public final boolean isDynamic()
        Returns true if this setting is dynamically updateable, otherwise false
      • isFinal

        public final boolean isFinal()
        Returns true if this setting is final, otherwise false
      • isInternalIndex

        public final boolean isInternalIndex()
      • isPrivateIndex

        public final boolean isPrivateIndex()
      • isFiltered

        public boolean isFiltered()
        Returns true if this setting must be filtered, otherwise false
      • hasNodeScope

        public boolean hasNodeScope()
        Returns true if this setting has a node scope, otherwise false
      • hasIndexScope

        public boolean hasIndexScope()
        Returns true if this setting has an index scope, otherwise false
      • isDeprecated

        public boolean isDeprecated()
        Returns true if this setting is deprecated, otherwise false
      • getDefaultRaw

        public java.lang.String getDefaultRaw​(Settings settings)
        Returns the default value string representation for this setting.
        Parameters:
        settings - a settings object for settings that has a default value depending on another setting if available
      • getDefault

        public T getDefault​(Settings settings)
        Returns the default value for this setting.
        Parameters:
        settings - a settings object for settings that has a default value depending on another setting if available
      • exists

        public boolean exists​(Settings settings)
        Returns true if and only if this setting is present in the given settings instance. Note that fallback settings are excluded.
        Parameters:
        settings - the settings
        Returns:
        true if the setting is present in the given settings instance, otherwise false
      • existsOrFallbackExists

        public boolean existsOrFallbackExists​(Settings settings)
        Returns true if and only if this setting including fallback settings is present in the given settings instance.
        Parameters:
        settings - the settings
        Returns:
        true if the setting including fallback settings is present in the given settings instance, otherwise false
      • get

        public T get​(Settings settings)
        Returns the settings value. If the setting is not present in the given settings object the default value is returned instead.
      • diff

        public void diff​(Settings.Builder builder,
                         Settings source,
                         Settings defaultSettings)
        Add this setting to the builder if it doesn't exists in the source settings. The value added to the builder is taken from the given default settings object.
        Parameters:
        builder - the settings builder to fill the diff into
        source - the source settings object to diff
        defaultSettings - the default settings object to diff against
      • getRaw

        public final java.lang.String getRaw​(Settings settings)
        Returns the raw (string) settings value. If the setting is not present in the given settings object the default value is returned instead. This is useful if the value can't be parsed due to an invalid value to access the actual value.
      • match

        public final boolean match​(java.lang.String toTest)
        Returns true iff the given key matches the settings key or if this setting is a group setting if the given key is part of the settings group.
        See Also:
        isGroupSetting()
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • get

        public final T get​(Settings primary,
                           Settings secondary)
        Returns the value for this setting but falls back to the second provided settings object
      • getConcreteSetting

        public Setting<T> getConcreteSetting​(java.lang.String key)
      • getSettingsDependencies

        public java.util.Set<Setting<?>> getSettingsDependencies​(java.lang.String key)
        Returns a set of settings that are required at validation time. Unless all of the dependencies are present in the settings object validation of setting must fail.
      • floatSetting

        public static Setting<java.lang.Float> floatSetting​(java.lang.String key,
                                                            float defaultValue,
                                                            Setting.Property... properties)
      • floatSetting

        public static Setting<java.lang.Float> floatSetting​(java.lang.String key,
                                                            float defaultValue,
                                                            float minValue,
                                                            Setting.Property... properties)
      • intSetting

        public static Setting<java.lang.Integer> intSetting​(java.lang.String key,
                                                            int defaultValue,
                                                            int minValue,
                                                            int maxValue,
                                                            Setting.Property... properties)
      • intSetting

        public static Setting<java.lang.Integer> intSetting​(java.lang.String key,
                                                            int defaultValue,
                                                            int minValue,
                                                            Setting.Property... properties)
      • intSetting

        public static Setting<java.lang.Integer> intSetting​(java.lang.String key,
                                                            Setting<java.lang.Integer> fallbackSetting,
                                                            int minValue,
                                                            Setting.Property... properties)
      • longSetting

        public static Setting<java.lang.Long> longSetting​(java.lang.String key,
                                                          long defaultValue,
                                                          long minValue,
                                                          Setting.Property... properties)
      • simpleString

        public static Setting<java.lang.String> simpleString​(java.lang.String key,
                                                             Setting.Property... properties)
      • simpleString

        public static Setting<java.lang.String> simpleString​(java.lang.String key,
                                                             java.util.function.Function<java.lang.String,​java.lang.String> parser,
                                                             Setting.Property... properties)
      • simpleString

        public static Setting<java.lang.String> simpleString​(java.lang.String key,
                                                             Setting<java.lang.String> fallback,
                                                             Setting.Property... properties)
      • simpleString

        public static Setting<java.lang.String> simpleString​(java.lang.String key,
                                                             Setting<java.lang.String> fallback,
                                                             java.util.function.Function<java.lang.String,​java.lang.String> parser,
                                                             Setting.Property... properties)
      • simpleString

        public static Setting<java.lang.String> simpleString​(java.lang.String key,
                                                             java.lang.String defaultValue,
                                                             Setting.Property... properties)
        Creates a new Setting instance with a String value
        Parameters:
        key - the settings key for this setting.
        defaultValue - the default String value.
        properties - properties for this setting like scope, filtering...
        Returns:
        the Setting Object
      • parseInt

        public static int parseInt​(java.lang.String s,
                                   int minValue,
                                   java.lang.String key)
      • parseInt

        public static int parseInt​(java.lang.String s,
                                   int minValue,
                                   int maxValue,
                                   java.lang.String key)
      • parseLong

        public static long parseLong​(java.lang.String s,
                                     long minValue,
                                     java.lang.String key)
      • parseTimeValue

        public static TimeValue parseTimeValue​(java.lang.String s,
                                               TimeValue minValue,
                                               java.lang.String key)
      • intSetting

        public static Setting<java.lang.Integer> intSetting​(java.lang.String key,
                                                            int defaultValue,
                                                            Setting.Property... properties)
      • boolSetting

        public static Setting<java.lang.Boolean> boolSetting​(java.lang.String key,
                                                             boolean defaultValue,
                                                             Setting.Property... properties)
      • boolSetting

        public static Setting<java.lang.Boolean> boolSetting​(java.lang.String key,
                                                             Setting<java.lang.Boolean> fallbackSetting,
                                                             Setting.Property... properties)
      • boolSetting

        public static Setting<java.lang.Boolean> boolSetting​(java.lang.String key,
                                                             java.util.function.Function<Settings,​java.lang.String> defaultValueFn,
                                                             Setting.Property... properties)
      • memorySizeSetting

        public static Setting<ByteSizeValue> memorySizeSetting​(java.lang.String key,
                                                               ByteSizeValue defaultValue,
                                                               Setting.Property... properties)
        Creates a setting which specifies a memory size. This can either be specified as an absolute bytes value or as a percentage of the heap memory.
        Parameters:
        key - the key for the setting
        defaultValue - the default value for this setting
        properties - properties properties for this setting like scope, filtering...
        Returns:
        the setting object
      • memorySizeSetting

        public static Setting<ByteSizeValue> memorySizeSetting​(java.lang.String key,
                                                               java.util.function.Function<Settings,​java.lang.String> defaultValue,
                                                               Setting.Property... properties)
        Creates a setting which specifies a memory size. This can either be specified as an absolute bytes value or as a percentage of the heap memory.
        Parameters:
        key - the key for the setting
        defaultValue - a function that supplies the default value for this setting
        properties - properties properties for this setting like scope, filtering...
        Returns:
        the setting object
      • memorySizeSetting

        public static Setting<ByteSizeValue> memorySizeSetting​(java.lang.String key,
                                                               java.lang.String defaultPercentage,
                                                               Setting.Property... properties)
        Creates a setting which specifies a memory size. This can either be specified as an absolute bytes value or as a percentage of the heap memory.
        Parameters:
        key - the key for the setting
        defaultPercentage - the default value of this setting as a percentage of the heap memory
        properties - properties properties for this setting like scope, filtering...
        Returns:
        the setting object
      • listSetting

        public static <T> Setting<java.util.List<T>> listSetting​(java.lang.String key,
                                                                 java.util.List<java.lang.String> defaultStringValue,
                                                                 java.util.function.Function<java.lang.String,​T> singleValueParser,
                                                                 Setting.Property... properties)
      • listSetting

        public static <T> Setting<java.util.List<T>> listSetting​(java.lang.String key,
                                                                 Setting<java.util.List<T>> fallbackSetting,
                                                                 java.util.function.Function<java.lang.String,​T> singleValueParser,
                                                                 Setting.Property... properties)
      • listSetting

        public static <T> Setting<java.util.List<T>> listSetting​(java.lang.String key,
                                                                 java.util.function.Function<java.lang.String,​T> singleValueParser,
                                                                 java.util.function.Function<Settings,​java.util.List<java.lang.String>> defaultStringValue,
                                                                 Setting.Property... properties)
      • listSetting

        public static <T> Setting<java.util.List<T>> listSetting​(java.lang.String key,
                                                                 @Nullable
                                                                 Setting<java.util.List<T>> fallbackSetting,
                                                                 java.util.function.Function<java.lang.String,​T> singleValueParser,
                                                                 java.util.function.Function<Settings,​java.util.List<java.lang.String>> defaultStringValue,
                                                                 Setting.Property... properties)
      • doubleSetting

        public static Setting<java.lang.Double> doubleSetting​(java.lang.String key,
                                                              double defaultValue,
                                                              double minValue,
                                                              Setting.Property... properties)
      • doubleSetting

        public static Setting<java.lang.Double> doubleSetting​(java.lang.String key,
                                                              double defaultValue,
                                                              double minValue,
                                                              double maxValue,
                                                              Setting.Property... properties)
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • prefixKeySetting

        public static <T> Setting.AffixSetting<T> prefixKeySetting​(java.lang.String prefix,
                                                                   java.util.function.Function<java.lang.String,​Setting<T>> delegateFactory)
        This setting type allows to validate settings that have the same type and a common prefix. For instance feature.${type}=[true|false] can easily be added with this setting. Yet, prefix key settings don't support updaters out of the box unless getConcreteSetting(String) is used to pull the updater.
      • affixKeySetting

        public static <T> Setting.AffixSetting<T> affixKeySetting​(java.lang.String prefix,
                                                                  java.lang.String suffix,
                                                                  java.util.function.Function<java.lang.String,​Setting<T>> delegateFactory,
                                                                  Setting.AffixSetting... dependencies)
        This setting type allows to validate settings that have the same type and a common prefix and suffix. For instance storage.${backend}.enable=[true|false] can easily be added with this setting. Yet, affix key settings don't support updaters out of the box unless getConcreteSetting(String) is used to pull the updater.