Package org.apache.kafka.common.config
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.-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ConfigDef.CaseInsensitiveValidString
static class
ConfigDef.CompositeValidator
static class
ConfigDef.ConfigKey
static class
ConfigDef.Importance
The importance level for a configurationstatic class
ConfigDef.LambdaValidator
static class
ConfigDef.NonEmptyString
static class
ConfigDef.NonEmptyStringWithoutControlChars
static class
ConfigDef.NonNullValidator
static class
ConfigDef.Range
Validation logic for numeric rangesstatic interface
ConfigDef.Recommender
This is used by thevalidate(Map)
to get valid values for a configuration given the current configuration values in order to perform full configuration validation and visibility modification.static class
ConfigDef.Type
The config typesstatic interface
ConfigDef.Validator
Validation logic the user may provide to perform single configuration validation.static class
ConfigDef.ValidList
static class
ConfigDef.ValidString
static class
ConfigDef.Width
The width of a configuration value -
Field Summary
Fields Modifier and Type Field Description static Object
NO_DEFAULT_VALUE
A unique Java object which represents the lack of a default value. -
Constructor Summary
-
Method Summary
Modifier and Type Method Description Map<String,ConfigDef.ConfigKey>
configKeys()
Get the configuration keysstatic String
convertToString(Object parsedValue, ConfigDef.Type type)
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.Map<String,Object>
defaultValues()
ConfigDef
define(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance, String documentation)
Define a new configuration with no special validation logicConfigDef
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 recommenderConfigDef
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 recommenderConfigDef
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 logicConfigDef
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 recommenderConfigDef
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 recommenderConfigDef
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 recommenderConfigDef
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 recommenderConfigDef
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 configurationConfigDef
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 dependentsConfigDef
define(String name, ConfigDef.Type type, ConfigDef.Importance importance, String documentation)
Define a new configuration with no default value and no special validation logicConfigDef
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 recommenderConfigDef
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 recommenderConfigDef
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 logicConfigDef
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 recommenderConfigDef
define(ConfigDef.ConfigKey key)
ConfigDef
defineInternal(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Importance importance)
Define a new internal configuration.ConfigDef
defineInternal(String name, ConfigDef.Type type, Object defaultValue, ConfigDef.Validator validator, ConfigDef.Importance importance, String documentation)
Define a new internal configuration.void
embed(String keyPrefix, String groupPrefix, int startingOrd, ConfigDef child)
protected String
getConfigValue(ConfigDef.ConfigKey key, String headerName)
List<String>
groups()
Get the groups for the configurationprotected List<String>
headers()
Set<String>
names()
Returns unmodifiable set of properties names defined in this ConfigDefMap<String,Object>
parse(Map<?,?> props)
Parse and validate configs against this configuration definition.static Object
parseType(String name, Object value, ConfigDef.Type type)
Parse a value according to its expected type.String
toEnrichedRst()
Configs with new metadata (group, orderInGroup, dependents) formatted with reStructuredText, suitable for embedding in Sphinx documentation.String
toHtml()
String
toHtml(int headerDepth, Function<String,String> idGenerator)
Converts this config into an HTML list that can be embedded into docs.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.String
toHtml(Map<String,String> dynamicUpdateModes)
Converts this config into an HTML list that can be embedded into docs.String
toHtmlTable()
String
toHtmlTable(Map<String,String> dynamicUpdateModes)
Converts this config into an HTML table that can be embedded into docs.String
toRst()
Get the configs formatted with reStructuredText, suitable for embedding in Sphinx documentation.List<ConfigValue>
validate(Map<String,String> props)
Validate the current configuration values with the configuration definition.Map<String,ConfigValue>
validateAll(Map<String,String> props)
ConfigDef
withClientSaslSupport()
Add standard SASL client configuration options.ConfigDef
withClientSslSupport()
Add standard SSL client configuration options.
-
Field Details
-
NO_DEFAULT_VALUE
A unique Java object which represents the lack of a default value.
-
-
Constructor Details
-
ConfigDef
public ConfigDef() -
ConfigDef
-
-
Method Details
-
names
Returns unmodifiable set of properties names defined in this ConfigDef- Returns:
- new unmodifiable
Set
instance containing the keys
-
defaultValues
-
define
-
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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentvalidator
- the validator to use in checking the correctness of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- the configurations that are dependents of this configurationrecommender
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentvalidator
- the validator to use in checking the correctness of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentvalidator
- the validator to use in checking the correctness of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displayrecommender
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentvalidator
- the validator to use in checking the correctness of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- the configurations that are dependents of this configurationrecommender
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displayrecommender
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- 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 parametertype
- the type of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- the configurations that are dependents of this configurationrecommender
- 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 parametertype
- the type of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displaydependents
- 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 parametertype
- the type of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- the name suitable for displayrecommender
- 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 parametertype
- the type of the configimportance
- the importance of this configdocumentation
- the documentation string for the configgroup
- the group this config belongs toorderInGroup
- the order of this config in the groupwidth
- the width of the configdisplayName
- 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 parametertype
- the type of the configdefaultValue
- the default value to use if this config isn't presentvalidator
- the validator to use in checking the correctness of the configimportance
- the importance of this configdocumentation
- 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 parametertype
- The type of the configdefaultValue
- The default value to use if this config isn't presentimportance
- 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 parametertype
- The type of the configimportance
- 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 parametertype
- The type of the configdefaultValue
- The default value to use if this config isn't presentimportance
- 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 parametertype
- The type of the configdefaultValue
- The default value to use if this config isn't presentvalidator
- The validator to use in checking the correctness of the configimportance
- 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
Get the configuration keys- Returns:
- a map containing all configuration keys
-
groups
Get the groups for the configuration- Returns:
- a list of group names
-
withClientSslSupport
Add standard SSL client configuration options.- Returns:
- this
-
withClientSaslSupport
Add standard SASL client configuration options.- Returns:
- this
-
parse
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
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
-
parseType
Parse a value according to its expected type.- Parameters:
name
- The config namevalue
- The config valuetype
- The expected type- Returns:
- The parsed object
-
convertToString
-
convertToStringMapWithPasswordValues
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
-
getConfigValue
-
toHtmlTable
-
toHtmlTable
Converts this config into an HTML table that can be embedded into docs. IfdynamicUpdateModes
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
Get the configs formatted with reStructuredText, suitable for embedding in Sphinx documentation. -
toEnrichedRst
Configs with new metadata (group, orderInGroup, dependents) formatted with reStructuredText, suitable for embedding in Sphinx documentation. -
embed
-
toHtml
-
toHtml
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
Converts this config into an HTML list that can be embedded into docs. IfdynamicUpdateModes
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. IfdynamicUpdateModes
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.
-