Class ConfigDef

java.lang.Object
org.apache.kafka.common.config.ConfigDef

public class ConfigDef extends Object
This class is used for specifying the set of expected configurations. For each configuration, you can specify the name, the type, the default value, the documentation, the group information, the order in the group, the width of the configuration value and the name suitable for display in the UI. You can provide special validation logic used for single configuration validation by overriding ConfigDef.Validator. Moreover, you can specify the dependents of a configuration. The valid values and visibility of a configuration may change according to the values of other configurations. You can override ConfigDef.Recommender to get valid values and set visibility of a configuration given the current configuration values.

To use the class:

 ConfigDef defs = new ConfigDef();

 defs.define("config_with_default", Type.STRING, "default string value", "Configuration with default value.");
 defs.define("config_with_validator", Type.INT, 42, Range.atLeast(0), "Configuration with user provided validator.");
 defs.define("config_with_dependents", Type.INT, "Configuration with dependents.", "group", 1, "Config With Dependents", Arrays.asList("config_with_default","config_with_validator"));

 Map<String, String> props = new HashMap<>();
 props.put("config_with_default", "some value");
 props.put("config_with_dependents", "some other value");

 Map<String, Object> configs = defs.parse(props);
 // will return "some value"
 String someConfig = (String) configs.get("config_with_default");
 // will return default value of 42
 int anotherConfig = (Integer) configs.get("config_with_validator");

 To validate the full configuration, use:
 List<Config> configs = defs.validate(props);
 The Config contains updated configuration information given the current configuration values.
 

This class can be used standalone or in combination with AbstractConfig which provides some additional functionality for accessing configs.

  • Field Details

    • NO_DEFAULT_VALUE

      public static final Object NO_DEFAULT_VALUE
      A unique Java object which represents the lack of a default value.
  • Constructor Details

    • ConfigDef

      public ConfigDef()
    • ConfigDef

      public ConfigDef(ConfigDef base)
  • Method Details

    • names

      public Set<String> names()
      Returns unmodifiable set of properties names defined in this ConfigDef
      Returns:
      new unmodifiable Set instance containing the keys
    • defaultValues

      public Map<String,Object> defaultValues()
    • define

      public ConfigDef define(ConfigDef.ConfigKey key)
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents, ConfigDef.Recommender recommender)
      Define a new configuration
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      validator - the validator to use in checking the correctness of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      recommender - the recommender provides valid values given the parent configuration values
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents)
      Define a new configuration with no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      validator - the validator to use in checking the correctness of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, ConfigDef.Recommender recommender)
      Define a new configuration with no dependents
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      validator - the validator to use in checking the correctness of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      recommender - the recommender provides valid values given the parent configuration values
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName)
      Define a new configuration with no dependents and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      validator - the validator to use in checking the correctness of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents, ConfigDef.Recommender recommender)
      Define a new configuration with no special validation logic
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      recommender - the recommender provides valid values given the parent configuration values
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents)
      Define a new configuration with no special validation logic and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, ConfigDef.Recommender recommender)
      Define a new configuration with no special validation logic and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      recommender - the recommender provides valid values given the parent configuration values
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName)
      Define a new configuration with no special validation logic, not dependents and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents, ConfigDef.Recommender recommender)
      Define a new configuration with no default value and no special validation logic
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      recommender - the recommender provides valid values given the parent configuration value
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, List<String> dependents)
      Define a new configuration with no default value, no special validation logic and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      dependents - the configurations that are dependents of this configuration
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName, ConfigDef.Recommender recommender)
      Define a new configuration with no default value, no special validation logic and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      recommender - the recommender provides valid values given the parent configuration value
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation, String group, int orderInGroup, ConfigDef.Width width, String displayName)
      Define a new configuration with no default value, no special validation logic, no dependents and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      group - the group this config belongs to
      orderInGroup - the order of this config in the group
      width - the width of the config
      displayName - the name suitable for display
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation)
      Define a new configuration with no group, no order in group, no width, no display name, no dependents and no custom recommender
      Parameters:
      name - the name of the config parameter
      type - the type of the config
      defaultValue - the default value to use if this config isn't present
      validator - the validator to use in checking the correctness of the config
      importance - the importance of this config
      documentation - the documentation string for the config
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation)
      Define a new configuration with no special validation logic
      Parameters:
      name - The name of the config parameter
      type - The type of the config
      defaultValue - The default value to use if this config isn't present
      importance - The importance of this config: is this something you will likely need to change.
      documentation - The documentation string for the config
      Returns:
      This ConfigDef so you can chain calls
    • define

      public ConfigDef define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation)
      Define a new configuration with no default value and no special validation logic
      Parameters:
      name - The name of the config parameter
      type - The type of the config
      importance - The importance of this config: is this something you will likely need to change.
      documentation - The documentation string for the config
      Returns:
      This ConfigDef so you can chain calls
    • defineInternal

      public ConfigDef defineInternal(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance)
      Define a new internal configuration. Internal configuration won't show up in the docs and aren't intended for general use.
      Parameters:
      name - The name of the config parameter
      type - The type of the config
      defaultValue - The default value to use if this config isn't present
      importance - The importance of this config (i.e. is this something you will likely need to change?)
      Returns:
      This ConfigDef so you can chain calls
    • defineInternal

      public ConfigDef defineInternal(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation)
      Define a new internal configuration. Internal configuration won't show up in the docs and aren't intended for general use.
      Parameters:
      name - The name of the config parameter
      type - The type of the config
      defaultValue - The default value to use if this config isn't present
      validator - The validator to use in checking the correctness of the config
      importance - The importance of this config (i.e. is this something you will likely need to change?)
      documentation - The documentation string for the config
      Returns:
      This ConfigDef so you can chain calls
    • configKeys

      public Map<String,ConfigDef.ConfigKey> configKeys()
      Get the configuration keys
      Returns:
      a map containing all configuration keys
    • groups

      public List<String> groups()
      Get the groups for the configuration
      Returns:
      a list of group names
    • withClientSslSupport

      public ConfigDef withClientSslSupport()
      Add standard SSL client configuration options.
      Returns:
      this
    • withClientSaslSupport

      public ConfigDef withClientSaslSupport()
      Add standard SASL client configuration options.
      Returns:
      this
    • parse

      public Map<String,Object> parse(Map<?,?> props)
      Parse and validate configs against this configuration definition. The input is a map of configs. It is expected that the keys of the map are strings, but the values can either be strings or they may already be of the appropriate type (int, string, etc). This will work equally well with either java.util.Properties instances or a programmatically constructed map.
      Parameters:
      props - The configs to parse and validate.
      Returns:
      Parsed and validated configs. The key will be the config name and the value will be the value parsed into the appropriate type (int, string, etc).
    • validate

      public List<ConfigValue> validate(Map<String,String> props)
      Validate the current configuration values with the configuration definition.
      Parameters:
      props - the current configuration values
      Returns:
      List of Config, each Config contains the updated configuration information given the current configuration values.
    • validateAll

      public Map<String,ConfigValue> validateAll(Map<String,String> props)
    • parseType

      public static Object parseType(String name, Object value, ConfigDef.Type type)
      Parse a value according to its expected type.
      Parameters:
      name - The config name
      value - The config value
      type - The expected type
      Returns:
      The parsed object
    • convertToString

      public static String convertToString(Object parsedValue, ConfigDef.Type type)
    • convertToStringMapWithPasswordValues

      public static Map<String,String> convertToStringMapWithPasswordValues(Map<String,?> configs)
      Converts a map of config (key, value) pairs to a map of strings where each value is converted to a string. This method should be used with care since it stores actual password values to String. Values from this map should never be used in log entries.
    • headers

      protected List<String> headers()
    • getConfigValue

      protected String getConfigValue(ConfigDef.ConfigKey key, String headerName)
    • toHtmlTable

      public String toHtmlTable()
    • toHtmlTable

      public String toHtmlTable(Map<String,String> dynamicUpdateModes)
      Converts this config into an HTML table that can be embedded into docs. If dynamicUpdateModes is non-empty, a "Dynamic Update Mode" column will be included n the table with the value of the update mode. Default mode is "read-only".
      Parameters:
      dynamicUpdateModes - Config name -> update mode mapping
    • toRst

      public String toRst()
      Get the configs formatted with reStructuredText, suitable for embedding in Sphinx documentation.
    • toEnrichedRst

      public String toEnrichedRst()
      Configs with new metadata (group, orderInGroup, dependents) formatted with reStructuredText, suitable for embedding in Sphinx documentation.
    • embed

      public void embed(String keyPrefix, String groupPrefix, int startingOrd, ConfigDef child)
    • toHtml

      public String toHtml()
    • toHtml

      public String toHtml(int headerDepth, Function<String,String> idGenerator)
      Converts this config into an HTML list that can be embedded into docs.
      Parameters:
      headerDepth - The top level header depth in the generated HTML.
      idGenerator - A function for computing the HTML id attribute in the generated HTML from a given config name.
    • toHtml

      public String toHtml(Map<String,String> dynamicUpdateModes)
      Converts this config into an HTML list that can be embedded into docs. If dynamicUpdateModes is non-empty, a "Dynamic Update Mode" label will be included in the config details with the value of the update mode. Default mode is "read-only".
      Parameters:
      dynamicUpdateModes - Config name -> update mode mapping.
    • toHtml

      public String toHtml(int headerDepth, Function<String,String> idGenerator, Map<String,String> dynamicUpdateModes)
      Converts this config into an HTML list that can be embedded into docs. If dynamicUpdateModes is non-empty, a "Dynamic Update Mode" label will be included in the config details with the value of the update mode. Default mode is "read-only".
      Parameters:
      headerDepth - The top level header depth in the generated HTML.
      idGenerator - A function for computing the HTML id attribute in the generated HTML from a given config name.
      dynamicUpdateModes - Config name -> update mode mapping.