Package org.elasticsearch.common.settings

Class Setting<T>

java.lang.Object
org.elasticsearch.common.settings.Setting<T>
All Implemented Interfaces:
org.elasticsearch.xcontent.ToXContent, org.elasticsearch.xcontent.ToXContentObject
Direct Known Subclasses:
SecureSetting, Setting.AffixSetting
public class Setting<T> extends Object implements org.elasticsearch.xcontent.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 Details

  • Constructor Details

    • Setting

      public Setting(Setting.Key key, Function<Settings,String> defaultValue, Function<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, Function<Settings,String> defaultValue, Function<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(String key, String defaultValue, Function<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(String key, String defaultValue, Function<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(String key, Function<Settings,String> defaultValue, Function<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(String key, Setting<T> fallbackSetting, Function<String,T> parser, Setting.Validator<T> validator, 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.
      validator - a Setting.Validator for validating this setting
      properties - properties for this setting like scope, filtering...

    • Setting

      public Setting(Setting.Key key, Setting<T> fallbackSetting, Function<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(String key, Setting<T> fallBackSetting, Function<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 Details

    • getKey

      public final 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

    • isOperatorOnly

      public final boolean isOperatorOnly()
      Returns true if this setting is dynamically updateable by operators, 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()

    • isSecure

      public final boolean isSecure(Settings settings)
      Checks whether this is a secure setting.
      Parameters:
      settings - used to check whether this setting is secure
      Returns:
      whether this is a secure setting.

    • getProperties

      public EnumSet<Setting.Property> getProperties()
      Returns the setting properties
      See Also:

    • 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

    • isConsistent

      public boolean isConsistent()
      Returns true if this setting's value can be checked for equality across all nodes. Only SecureSetting instances may have this qualifier.

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

    • exists

      public boolean exists(Settings.Builder builder)

    • 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

    • match

      public final boolean match(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()

    • toXContent

      public final org.elasticsearch.xcontent.XContentBuilder toXContent(org.elasticsearch.xcontent.XContentBuilder builder, org.elasticsearch.xcontent.ToXContent.Params params) throws IOException
      Specified by:
      toXContent in interface org.elasticsearch.xcontent.ToXContent
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class 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(String key)

    • getSettingsDependencies

      public Set<Setting.SettingDependency> getSettingsDependencies(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.

    • versionSetting

      public static Setting<Version> versionSetting(String key, Version defaultValue, Setting.Property... properties)

    • floatSetting

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

    • floatSetting

      public static Setting<Float> floatSetting(String key, float defaultValue, float minValue, Setting.Property... properties)

    • intSetting

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

    • intSetting

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

    • intSetting

      public static Setting<Integer> intSetting(String key, int defaultValue, int minValue, Setting.Validator<Integer> validator, Setting.Property... properties)

    • intSetting

      public static Setting<Integer> intSetting(String key, Setting<Integer> fallbackSetting, int minValue, Setting.Property... properties)

    • intSetting

      public static Setting<Integer> intSetting(String key, Setting<Integer> fallbackSetting, int minValue, int maxValue, Setting.Property... properties)

    • intSetting

      public static Setting<Integer> intSetting(String key, Setting<Integer> fallbackSetting, int minValue, Setting.Validator<Integer> validator, Setting.Property... properties)

    • longSetting

      public static Setting<Long> longSetting(String key, long defaultValue, long minValue, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, Setting.Validator<String> validator, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, Setting.Validator<String> validator, Setting<String> fallback, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, String defaultValue, Setting.Validator<String> validator, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, Setting<String> fallback, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, Setting<String> fallback, Function<String,String> parser, Setting.Property... properties)

    • simpleString

      public static Setting<String> simpleString(String key, 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(String s, int minValue, String key)

    • parseInt

      public static int parseInt(String s, int minValue, String key, boolean isFiltered)

    • parseInt

      public static int parseInt(String s, int minValue, int maxValue, String key)

    • parseInt

      public static int parseInt(String s, int minValue, int maxValue, String key, boolean isFiltered)

    • parseLong

      public static long parseLong(String s, long minValue, String key)

    • parseTimeValue

      public static org.elasticsearch.core.TimeValue parseTimeValue(String s, org.elasticsearch.core.TimeValue minValue, String key)

    • intSetting

      public static Setting<Integer> intSetting(String key, int defaultValue, Setting.Property... properties)

    • boolSetting

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

    • boolSetting

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

    • boolSetting

      public static Setting<Boolean> boolSetting(String key, Setting<Boolean> fallbackSetting, Setting.Validator<Boolean> validator, Setting.Property... properties)

    • boolSetting

      public static Setting<Boolean> boolSetting(String key, boolean defaultValue, Setting.Validator<Boolean> validator, Setting.Property... properties)

    • boolSetting

      public static Setting<Boolean> boolSetting(String key, Function<Settings,String> defaultValueFn, Setting.Property... properties)

    • byteSizeSetting

      public static Setting<ByteSizeValue> byteSizeSetting(String key, ByteSizeValue value, Setting.Property... properties)

    • byteSizeSetting

      public static Setting<ByteSizeValue> byteSizeSetting(String key, Setting<ByteSizeValue> fallbackSetting, Setting.Property... properties)

    • byteSizeSetting

      public static Setting<ByteSizeValue> byteSizeSetting(String key, Function<Settings,String> defaultValue, Setting.Property... properties)

    • byteSizeSetting

      public static Setting<ByteSizeValue> byteSizeSetting(String key, ByteSizeValue defaultValue, ByteSizeValue minValue, ByteSizeValue maxValue, Setting.Property... properties)

    • byteSizeSetting

      public static Setting<ByteSizeValue> byteSizeSetting(String key, Function<Settings,String> defaultValue, ByteSizeValue minValue, ByteSizeValue maxValue, Setting.Property... properties)

    • parseByteSize

      public static ByteSizeValue parseByteSize(String s, ByteSizeValue minValue, ByteSizeValue maxValue, String key)

    • enumSetting

      public static <T extends Enum<T>> Setting<T> enumSetting(Class<T> clazz, String key, T defaultValue, Setting.Property... properties)
      Creates a setting where the allowed values are defined as enum constants. All enum constants must be uppercase.
      Type Parameters:
      T - the generics type parameter reflecting the actual type of the enum
      Parameters:
      clazz - the enum class
      key - the key for the setting
      defaultValue - the default value for this setting
      properties - properties for this setting like scope, filtering...
      Returns:
      the setting object

    • enumSetting

      public static <T extends Enum<T>> Setting<T> enumSetting(Class<T> clazz, String key, Setting<T> fallbackSetting, Setting.Validator<T> validator, Setting.Property... properties)
      Creates a setting where the allowed values are defined as enum constants. All enum constants must be uppercase.
      Type Parameters:
      T - the generics type parameter reflecting the actual type of the enum
      Parameters:
      clazz - the enum class
      key - the key for the setting
      fallbackSetting - the fallback setting for this setting
      validator - validator for this setting
      properties - properties for this setting like scope, filtering...
      Returns:
      the setting object

    • memorySizeSetting

      public static Setting<ByteSizeValue> memorySizeSetting(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(String key, Function<Settings,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(String key, 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<List<T>> listSetting(String key, List<String> defaultStringValue, Function<String,T> singleValueParser, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, List<String> defaultStringValue, Function<String,T> singleValueParser, Setting.Validator<List<T>> validator, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, Setting<List<T>> fallbackSetting, Function<String,T> singleValueParser, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, Function<String,T> singleValueParser, Function<Settings,List<String>> defaultStringValue, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, Function<String,T> singleValueParser, Function<Settings,List<String>> defaultStringValue, Setting.Validator<List<T>> validator, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, @Nullable Setting<List<T>> fallbackSetting, Function<String,T> singleValueParser, Function<Settings,List<String>> defaultStringValue, Setting.Property... properties)

    • listSetting

      public static <T> Setting<List<T>> listSetting(String key, @Nullable Setting<List<T>> fallbackSetting, Function<String,T> singleValueParser, Function<Settings,List<String>> defaultStringValue, Setting.Validator<List<T>> validator, Setting.Property... properties)

    • groupSetting

      public static Setting<Settings> groupSetting(String key, Setting.Property... properties)

    • groupSetting

      public static Setting<Settings> groupSetting(String key, Consumer<Settings> validator, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, Setting<org.elasticsearch.core.TimeValue> fallbackSetting, org.elasticsearch.core.TimeValue minValue, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, Function<Settings,org.elasticsearch.core.TimeValue> defaultValue, org.elasticsearch.core.TimeValue minValue, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, org.elasticsearch.core.TimeValue defaultValue, org.elasticsearch.core.TimeValue minValue, org.elasticsearch.core.TimeValue maxValue, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, org.elasticsearch.core.TimeValue defaultValue, org.elasticsearch.core.TimeValue minValue, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, org.elasticsearch.core.TimeValue defaultValue, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, Setting<org.elasticsearch.core.TimeValue> fallbackSetting, Setting.Property... properties)

    • timeSetting

      public static Setting<org.elasticsearch.core.TimeValue> timeSetting(String key, Setting<org.elasticsearch.core.TimeValue> fallBackSetting, Setting.Validator<org.elasticsearch.core.TimeValue> validator, Setting.Property... properties)

    • positiveTimeSetting

      public static Setting<org.elasticsearch.core.TimeValue> positiveTimeSetting(String key, org.elasticsearch.core.TimeValue defaultValue, Setting.Property... properties)

    • positiveTimeSetting

      public static Setting<org.elasticsearch.core.TimeValue> positiveTimeSetting(String key, Setting<org.elasticsearch.core.TimeValue> fallbackSetting, org.elasticsearch.core.TimeValue minValue, Setting.Property... properties)

    • doubleSetting

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

    • doubleSetting

      public static Setting<Double> doubleSetting(String key, double defaultValue, double minValue, double maxValue, Setting.Property... properties)

    • parseDouble

      public static Double parseDouble(String s, double minValue, double maxValue, String key, Setting.Property... properties)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • prefixKeySetting

      public static <T> Setting.AffixSetting<T> prefixKeySetting(String prefix, Function<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(String prefix, String suffix, Function<String,Setting<T>> delegateFactory, Setting.AffixSettingDependency... 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.

    • affixKeySetting

      public static <T> Setting.AffixSetting<T> affixKeySetting(String prefix, String suffix, BiFunction<String,String,Setting<T>> delegateFactory, Setting.AffixSettingDependency... dependencies)