Package org.openhab.core.config.core

Class ConfigUtil

java.lang.Object
org.openhab.core.config.core.ConfigUtil
@NonNullByDefault public class ConfigUtil extends Object
The configuration admin service provides us with a map of key->values. Values can be any primitive type like String, int, double as well as the object variants of the number types like Integer, Double etc. You find normalization utility methods in here to convert all number Types to BigDecimal and all Collections to List. This works on a best-effort strategy (e.g. "3" will always end up being a BigDecimal, never a String), except if a ConfigDescriptionParameter is given. In the latter case, a conversion according to the type given in the description is performed.
Author:
Kai Kreuzer - Initial contribution, Thomas Höfer - Minor changes for type normalization based on config description, Florian Hotze - Add support for environment variable substitution in config values

  • Constructor Details

    • ConfigUtil

      public ConfigUtil()

  • Method Details

    • setEnvProvider

      protected static void setEnvProvider(ConfigUtil.EnvProvider provider)
      Setter for envProvider to allow overwriting it in tests.

      This MUST NOT be called in production environments as it can break environment variable resolving.

      Parameters:
      provider - the env provider to use for resolving environment variables

    • getDefaultValueAsCorrectType

      public static @Nullable Object getDefaultValueAsCorrectType(ConfigDescriptionParameter parameter)
      Maps the provided (default) value of the given ConfigDescriptionParameter to the corresponding Java type. In case the provided (default) value is supposed to be a number and cannot be converted into the target type correctly, this method will return null while logging a warning.
      Parameters:
      parameter - the ConfigDescriptionParameter which default value should be normalized (must not be null)
      Returns:
      the default value as the corresponding Java type, or a List of the corresponding Java type if the parameter contains multiple values. Returns null if the value could not be converted.

    • applyDefaultConfiguration

      public static void applyDefaultConfiguration(Map<String,@Nullable Object> configuration, @Nullable ConfigDescription configDescription)
      Applies the default values from a give ConfigDescription to the given configuration Map.
      Parameters:
      configuration - the configuration Map where the default values should be added (must not be null)
      configDescription - the ConfigDescription where the default values are located (may be null, but method won't have any effect then)

    • applyDefaultConfiguration

      public static void applyDefaultConfiguration(Configuration configuration, @Nullable ConfigDescription configDescription)
      Applies the default values from a give ConfigDescription to the given Configuration.
      Parameters:
      configuration - the Configuration where the default values should be added (must not be null)
      configDescription - the ConfigDescription where the default values are located (may be null, but method won't have any effect then)

    • normalizeTypes

      public static Map<String,@Nullable Object> normalizeTypes(Map<String,@Nullable Object> configuration)
      Normalizes the types to the ones allowed for configurations.
      Parameters:
      configuration - the configuration that needs to be normalized
      Returns:
      normalized configuration

    • normalizeType

      public static @Nullable Object normalizeType(@Nullable Object value, @Nullable ConfigDescriptionParameter configDescriptionParameter)
      Normalizes the type of the parameter to the one allowed for configurations.
      Parameters:
      value - the value to return as normalized type
      configDescriptionParameter - the parameter that needs to be normalized
      Returns:
      corresponding value as a valid type
      Throws:
      IllegalArgumentException - if an invalid type has been given

    • normalizeTypes

      public static Map<String,@Nullable Object> normalizeTypes(Map<String,@Nullable Object> configuration, List<ConfigDescription> configDescriptions)
      Normalizes the given configuration according to the given config descriptions. By doing so, it tries to convert types on a best-effort basis. The result will contain BigDecimals, Strings and Booleans wherever a conversion of similar types was possible. However, it does not check for general correctness of types. This can be done using the ConfigDescriptionValidator. If multiple config descriptions are given and a parameter is described several times, then the first one (lower index in the list) wins.
      Parameters:
      configuration - the configuration to be normalized
      configDescriptions - the configuration descriptions that should be applied (must not be empty).
      Returns:
      the normalized configuration or null if given configuration was null
      Throws:
      IllegalArgumentException - if given config description is null

    • normalizeType

      public static @Nullable Object normalizeType(@Nullable Object value)
      Normalizes the type of the parameter to the one allowed for configurations. The conversion is performed 'best-effort' (e.g. "3" will always end up being a BigDecimal, never a String). Use normalizeType(Object, ConfigDescriptionParameter) to make sure your field type ends up as intended.
      Parameters:
      value - the value to return as normalized type
      Returns:
      corresponding value as a valid type

    • resolveVariables

      public static Object resolveVariables(Object value) throws IllegalArgumentException
      Resolves variables in the given value by replacing the variable patterns through the variable values.

      The following rules are applied:

      1. If the given value is a string, it is checked for variable patterns and referenced variables are resolved.
      2. If a variable fails to resolve, a IllegalArgumentException is thrown.
      3. If the value is a collection, this method is called for each element.
      4. If the value is neither a string nor a collection, it is returned as-is.
      Parameters:
      value - the value to resolve
      Returns:
      the resolved value
      Throws:
      IllegalArgumentException - if a variable fails to resolve

    • resolveVariables

      public static Map<String,@Nullable Object> resolveVariables(Map<String,@Nullable Object> configuration) throws IllegalArgumentException
      Resolve variables in the given configuration.

      Note that when substituting variables in non-TEXT values such as BOOLEAN, DECIMAL, etc., the config needs to be normalized.

      Parameters:
      configuration - the configuration to resolve variables in
      Returns:
      the resolved configuration
      Throws:
      IllegalArgumentException - if a variable fails to resolve

    • resolveVariables

      public static Configuration resolveVariables(Configuration configuration) throws IllegalArgumentException
      Resolve variables in the given Configuration.

      Note that when substituting variables in non-TEXT values such as BOOLEAN, DECIMAL, etc., the config needs to be normalized.

      Parameters:
      configuration - the configuration to resolve variables in
      Returns:
      the resolved configuration
      Throws:
      IllegalArgumentException - if a variable fails to resolve

    • resolveVariablesAndNormalizeTypes

      public static Configuration resolveVariablesAndNormalizeTypes(Configuration configuration, List<ConfigDescription> configDescriptions) throws IllegalArgumentException
      Resolve variables and normalize the results in the given Configuration.

      Normalizing after the resolve step allows to use variable substitution for non-TEXT values such as BOOLEAN, DECIMAL, etc.

      Parameters:
      configuration - the configuration to resolve variables in and normalize afterward
      configDescriptions - the configuration descriptions that should be applied (must not be empty).
      Returns:
      the normalized configuration
      Throws:
      IllegalArgumentException - if a variable fails to refresh or the given config description is null