Package com.electronwill.nightconfig.core

Class ConfigSpec

java.lang.Object
com.electronwill.nightconfig.core.ConfigSpec
Direct Known Subclasses:
ConcurrentConfigSpec
public class ConfigSpec extends Object
Represents a specification for a configuration. With a ConfigSpec you can define mandatory "properties" that the config's values must have and then check that the config is correct, and even correct it automatically!

Defining entries

Use the "define" methods to define that some entry must be present in the config, and how its value must be. You have to specify - at least - the path of the value and a default value that will be used to replace the config's value in case it's incorrect.
For instance, the following code defines a value with path "a.b" and which must be a String: 
configSpec.define("a.b", "defaultString");

Validators

Some methods (like the one used in the previous paragraph) automatically generate the rules that make a config value correct or incorrect. But you can provide your own rule by specifying a "validator": a Predicate that returns true if and only if the given value is correct.
For instance, this defines a value "arraylist" that must be an ArrayList: configSpec.define("arraylist", new ArrayList(), o -> o instanceof ArrayList);

Suppliers of default value

If the default value is heavy to create you should use a Supplier instead of creating a default value, which is useless if the config's value happens to be correct.
For instance, the code in the previous paragraph could be rewritten like this: configSpec.define("heavy", () -> new ArrayList(), o -> o instanceof ArrayList);

Checking configurations

Use the "isCorrect" methods to check whether a configuration is correct or not. A configuration is correct if and only if:*
  1. Each entry defined in the spec is present in the config.
  2. Each entry in the config is defined in the spec.
  3. Each entry in the config has a correct value according to the spec.

Correcting configurations

Use the "correct" methods to correct a configuration. The correction behaves like this:
  1. Each entry that is defined in the spec but absent from the config is added to the config, with the default value defined in the spec.
  2. Each entry that isn't defined in the spec is removed from the config.
  3. Each incorrect config value is replaced by the default value specified in the spec.

  • Field Details

    • storage

      protected final Config storage

  • Constructor Details

    • ConfigSpec

      public ConfigSpec()

  • Method Details

    • define

      public void define(String path, Object defaultValue)
      Defines an entry. To be correct, the type of the config value must be of the same as or a subtype of the defaultValue's type.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value

    • define

      public void define(List<String> path, Object defaultValue)
      Defines an entry. To be correct, the type of the config value must be of the same as or a subtype of the defaultValue's type.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value

    • define

      public void define(String path, Object defaultValue, Predicate<Object> validator)
      Defines an entry. A config value is considered correct if and only if validator.test(configValue) returns true.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      validator - the Predicate that determines if the value is correct or not

    • define

      public void define(String path, Supplier<?> defaultValueSupplier, Predicate<Object> validator)
      Defines an entry. A config value is considered correct if and only if validator.test(configValue) returns true.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      validator - the Predicate that determines if the value is correct or not

    • define

      public void define(List<String> path, Object defaultValue, Predicate<Object> validator)
      Defines an entry. A config value is considered correct if and only if validator.test(configValue) returns true.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      validator - the Predicate that determines if the value is correct or not

    • define

      public void define(List<String> path, Supplier<?> defaultValueSupplier, Predicate<Object> validator)
      Defines an entry. A config value is considered correct if and only if validator.test(configValue) returns true.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      validator - the Predicate that determines if the value is correct or not

    • defineOfClass

      public <V> void defineOfClass(String path, V defaultValue, Class<? super V> acceptableValueClass)
      Defines an entry. A config value is considered correct if and only if it is of the same type as, or of a subtype of the specified class.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      acceptableValueClass - the class that a value of this entry must have

    • defineOfClass

      public <V> void defineOfClass(String path, Supplier<V> defaultValueSupplier, Class<? super V> acceptableValueClass)
      Defines an entry. A config value is considered correct if and only if it is of the same type as, or of a subtype of the specified class.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      acceptableValueClass - the class that a value of this entry must have

    • defineOfClass

      public <V> void defineOfClass(List<String> path, V defaultValue, Class<? super V> acceptableValueClass)
      Defines an entry. A config value is considered correct if and only if it is of the same type as, or of a subtype of the specified class.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      acceptableValueClass - the class that a value of this entry must have

    • defineOfClass

      public <V> void defineOfClass(List<String> path, Supplier<V> defaultValueSupplier, Class<? super V> acceptableValueClass)
      Defines an entry. A config value is considered correct if and only if it is of the same type as, or of a subtype of the specified class.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      acceptableValueClass - the class that a value of this entry must have

    • defineInList

      public void defineInList(String path, Object defaultValue, Collection<?> acceptableValues)
      Defines an entry. A config value is considered correct if and only if it is contained in the specified collection.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      acceptableValues - the Collection containing all the acceptable values

    • defineInList

      public void defineInList(String path, Supplier<?> defaultValueSupplier, Collection<?> acceptableValues)
      Defines an entry. A config value is considered correct if and only if it is contained in the specified collection.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplifer of the default entry value
      acceptableValues - the Collection containing all the acceptable values

    • defineInList

      public void defineInList(List<String> path, Object defaultValue, Collection<?> acceptableValues)
      Defines an entry. A config value is considered correct if and only if it is contained in the specified collection.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      acceptableValues - the Collection containing all the acceptable values

    • defineInList

      public void defineInList(List<String> path, Supplier<?> defaultValueSupplier, Collection<?> acceptableValues)
      Defines an entry. A config value is considered correct if and only if it is contained in the specified collection.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      acceptableValues - the Collection containing all the acceptable values

    • defineInRange

      public <V extends Comparable<? super V>> void defineInRange(String path, V defaultValue, V min, V max)
      Defines an entry. A config value is considered correct if and only if it is less than or equal to min and bigger than or equal to max.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      min - the minimum, inclusive
      max - the maximum, inclusive

    • defineInRange

      public <V extends Comparable<? super V>> void defineInRange(String path, Supplier<V> defaultValueSupplier, V min, V max)
      Defines an entry. A config value is considered correct if and only if it is less than or equal to min and bigger than or equal to max.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      min - the minimum, inclusive
      max - the maximum, inclusive

    • defineInRange

      public <V extends Comparable<? super V>> void defineInRange(List<String> path, V defaultValue, V min, V max)
      Defines an entry. A config value is considered correct if and only if it is less than or equal to min and bigger than or equal to max.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      min - the minimum, inclusive
      max - the maximum, inclusive

    • defineInRange

      public <V extends Comparable<? super V>> void defineInRange(List<String> path, Supplier<V> defaultValueSupplier, V min, V max)
      Defines an entry. A config value is considered correct if and only if it is less than or equal to min and bigger than or equal to max.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      min - the minimum, inclusive
      max - the maximum, inclusive

    • defineList

      public void defineList(String path, List<?> defaultValue, Predicate<Object> elementValidator)
      Defines an entry. A config value is considered correct if and only if all its element are valid according to the elementValidator, that is, if and only if for all element e in the list the call elementValidator.test(e) returns true.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      elementValidator - the Predicate that checks that every element of the list is correct

    • defineList

      public void defineList(String path, Supplier<List<?>> defaultValueSupplier, Predicate<Object> elementValidator)
      Defines an entry. A config value is considered correct if and only if all its element are valid according to the elementValidator, that is, if and only if for all element e in the list the call elementValidator.test(e) returns true.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      elementValidator - the Predicate that checks that every element of the list is correct

    • defineList

      public void defineList(List<String> path, List<?> defaultValue, Predicate<Object> elementValidator)
      Defines an entry. A config value is considered correct if and only if all its element are valid according to the elementValidator, that is, if and only if for all element e in the list the call elementValidator.test(e) returns true.
      Parameters:
      path - the entry's path
      defaultValue - the default entry value
      elementValidator - the Predicate that checks that every element of the list is correct

    • defineList

      public void defineList(List<String> path, Supplier<List<?>> defaultValueSupplier, Predicate<Object> elementValidator)
      Defines an entry. A config value is considered correct if and only if all its element are valid according to the elementValidator, that is, if and only if for all element e in the list the call elementValidator.test(e) returns true.
      Parameters:
      path - the entry's path
      defaultValueSupplier - the Supplier of the default entry value
      elementValidator - the Predicate that checks that every element of the list is correct

    • defineEnum

      public <T extends Enum<T>> void defineEnum(String path, T defaultValue, EnumGetMethod method)

    • defineEnum

      public <T extends Enum<T>> void defineEnum(List<String> path, T defaultValue, EnumGetMethod method)

    • defineEnum

      public <T extends Enum<T>> void defineEnum(String path, Class<T> enumType, EnumGetMethod method, Supplier<T> defaultValueSupplier)

    • defineEnum

      public <T extends Enum<T>> void defineEnum(List<String> path, Class<T> enumType, EnumGetMethod method, Supplier<T> defaultValueSupplier)

    • defineRestrictedEnum

      public <T extends Enum<T>> void defineRestrictedEnum(String path, T defaultValue, Collection<T> acceptableValues, EnumGetMethod method)

    • defineRestrictedEnum

      public <T extends Enum<T>> void defineRestrictedEnum(List<String> path, T defaultValue, Collection<T> acceptableValues, EnumGetMethod method)

    • defineRestrictedEnum

      public <T extends Enum<T>> void defineRestrictedEnum(String path, Class<T> enumType, Collection<T> acceptableValues, EnumGetMethod method, Supplier<T> defaultValueSupplier)

    • defineRestrictedEnum

      public <T extends Enum<T>> void defineRestrictedEnum(List<String> path, Class<T> enumType, Collection<T> acceptableValues, EnumGetMethod method, Supplier<T> defaultValueSupplier)

    • undefine

      public void undefine(String path)
      Undefines an entry.
      Parameters:
      path - the entry's path

    • undefine

      public void undefine(List<String> path)
      Undefines an entry.
      Parameters:
      path - the entry's path

    • isDefined

      public boolean isDefined(String path)
      Checks if an entry has been defined.
      Parameters:
      path - the entry's path
      Returns:
      true if it has been defined, false otherwise

    • isDefined

      public boolean isDefined(List<String> path)
      Checks if an entry has been defined.
      Parameters:
      path - the entry's path
      Returns:
      true if it has been defined, false otherwise

    • isCorrect

      public boolean isCorrect(String path, Object value)
      Checks that a value is conform to the specification.
      Parameters:
      path - the entry's path
      value - the entry's value
      Returns:
      true if it's correct, false if it's incorrect

    • isCorrect

      public boolean isCorrect(List<String> path, Object value)
      Checks that a value is conform to the specification.
      Parameters:
      path - the entry's path
      value - the entry's value
      Returns:
      true if it's correct, false if it's incorrect

    • isCorrect

      public boolean isCorrect(Config config)
      Checks that a configuration is conform to the specification.
      Parameters:
      config - the config to check
      Returns:
      true if it's correct, false if it's incorrect

    • correct

      public Object correct(String path, Object value)
      Corrects a value.
      Parameters:
      path - the value's path
      value - the value to correct
      Returns:
      the corrected value, or the value itself if's it already correct

    • correct

      public Object correct(List<String> path, Object value)
      Corrects a value.
      Parameters:
      path - the value's path
      value - the value to correct
      Returns:
      the corrected value, or the value itself if's it already correct

    • correct

      public int correct(Config config)
      Corrects a configuration.
      Parameters:
      config - the config to correct
      Returns:
      the number of added, removed or replaced values.

    • correct

      public int correct(Config config, ConfigSpec.CorrectionListener listener)
      Corrects a configuration.
      Parameters:
      config - the config to correct
      listener - the listener that will be notified of every change made during the correction of the config.
      Returns:
      the number of added, removed or replaced values.