Package org.apache.kafka.common.config

Class ConfigDef

  • public class ConfigDef
extends java.lang.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 Detail

      • NO_DEFAULT_VALUE

        public static final java.lang.Object NO_DEFAULT_VALUE
        A unique Java object which represents the lack of a default value.

    • Constructor Detail

      • ConfigDef

        public ConfigDef()

      • ConfigDef

        public ConfigDef​(ConfigDef base)

    • Method Detail

      • names

        public java.util.Set<java.lang.String> names()
        Returns unmodifiable set of properties names defined in this ConfigDef
        Returns:
        new unmodifiable Set instance containing the keys

      • defaultValues

        public java.util.Map<java.lang.String,​java.lang.Object> defaultValues()

      • define

        public ConfigDef define​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Validator validator,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Validator validator,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Validator validator,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Validator validator,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.String displayName,
                        java.util.List<java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        ConfigDef.Importance importance,
                        java.lang.String documentation,
                        java.lang.String group,
                        int orderInGroup,
                        ConfigDef.Width width,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Validator validator,
                        ConfigDef.Importance importance,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        java.lang.Object defaultValue,
                        ConfigDef.Importance importance,
                        java.lang.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​(java.lang.String name,
                        ConfigDef.Type type,
                        ConfigDef.Importance importance,
                        java.lang.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​(java.lang.String name,
                                ConfigDef.Type type,
                                java.lang.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 -
        Returns:
        This ConfigDef so you can chain calls

      • configKeys

        public java.util.Map<java.lang.String,​ConfigDef.ConfigKey> configKeys()
        Get the configuration keys
        Returns:
        a map containing all configuration keys

      • groups

        public java.util.List<java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> parse​(java.util.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 java.util.List<ConfigValue> validate​(java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​ConfigValue> validateAll​(java.util.Map<java.lang.String,​java.lang.String> props)

      • parseType

        public static java.lang.Object parseType​(java.lang.String name,
                                         java.lang.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 java.lang.String convertToString​(java.lang.Object parsedValue,
                                               ConfigDef.Type type)

      • convertToStringMapWithPasswordValues

        public static java.util.Map<java.lang.String,​java.lang.String> convertToStringMapWithPasswordValues​(java.util.Map<java.lang.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 java.util.List<java.lang.String> headers()

      • getConfigValue

        protected java.lang.String getConfigValue​(ConfigDef.ConfigKey key,
                                          java.lang.String headerName)

      • toHtmlTable

        public java.lang.String toHtmlTable()

      • toHtmlTable

        public java.lang.String toHtmlTable​(java.util.Map<java.lang.String,​java.lang.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 java.lang.String toRst()
        Get the configs formatted with reStructuredText, suitable for embedding in Sphinx documentation.

      • toEnrichedRst

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

      • embed

        public void embed​(java.lang.String keyPrefix,
                  java.lang.String groupPrefix,
                  int startingOrd,
                  ConfigDef child)

      • toHtml

        public java.lang.String toHtml()

      • toHtml

        public java.lang.String toHtml​(int headerDepth,
                               java.util.function.Function<java.lang.String,​java.lang.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 java.lang.String toHtml​(java.util.Map<java.lang.String,​java.lang.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 java.lang.String toHtml​(int headerDepth,
                               java.util.function.Function<java.lang.String,​java.lang.String> idGenerator,
                               java.util.Map<java.lang.String,​java.lang.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.