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();

 // check define(String, Type, Object, Importance, String) for more details.
 defs.define("config_with_default", Type.STRING, "default string value", Importance.High, "Configuration with default value.");
 // check define(String, Type, Object, Validator, Importance, String) for more details.
 defs.define("config_with_validator", Type.INT, 42, Range.atLeast(0), Importance.High, "Configuration with user provided validator.");
 // check define(String, Type, Importance, String, String, int, Width, String, List<String>) for more details.
 defs.define("config_with_dependents", Type.INT, Importance.LOW, "Configuration with dependents.", "group", 1, Width.SHORT, "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<ConfigValue> configValues = defs.validate(props);
 // The ConfigValue 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 enum	ConfigDef.Importance	The importance level for a configuration
static class	ConfigDef.LambdaValidator
static class	ConfigDef.ListSize
static class	ConfigDef.NonEmptyString
static class	ConfigDef.NonEmptyStringWithoutControlChars
static class	ConfigDef.NonNullValidator
static class	ConfigDef.Range	Validation logic for numeric ranges
static interface	ConfigDef.Recommender	This is used by the validate(Map) to get valid values for a configuration given the current configuration values in order to perform full configuration validation and visibility modification.
static enum	ConfigDef.Type	The config types
static interface	ConfigDef.Validator	Validation logic the user may provide to perform single configuration validation.
static class	ConfigDef.ValidList
static class	ConfigDef.ValidString
static enum	ConfigDef.Width	The width of a configuration value

Field Summary

Fields

Modifier and Type	Field	Description
static final Object	NO_DEFAULT_VALUE	A unique Java object which represents the lack of a default value.

Constructor Summary

Constructors

Constructor	Description
ConfigDef()
ConfigDef(ConfigDef base)

Method Summary

Modifier and Type	Method	Description
Map<String,ConfigDef.ConfigKey>	configKeys()	Get the configuration keys
static 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 logic
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
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
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
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
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
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
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
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
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
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
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
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
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
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
ConfigDef	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 configuration
protected List<String>	headers()
Set<String>	names()	Returns unmodifiable set of properties names defined in this ConfigDef
Map<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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.