Class 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) 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.

    • Field Detail

      • NO_DEFAULT_VALUE

        public static final 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 Set<String> names()
        Returns unmodifiable set of properties names defined in this ConfigDef
        Returns:
        new unmodifiable Set instance containing the keys
      • 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.
      • 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
      • 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.
      • 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.