com.electronwill.nightconfig.core

Class ConfigSpec

java.lang.Object

com.electronwill.nightconfig.core.ConfigSpec

Direct Known Subclasses:

ConcurrentConfigSpec

public class ConfigSpec
extends java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConfigSpec.CorrectionAction
static interface	ConfigSpec.CorrectionListener Listens to the corrections made by the methods correct(Config) and correct(Config, CorrectionListener).

Field Summary

Fields

Modifier and Type	Field and Description
protected Config	storage

Constructor Summary

Constructors

Constructor and Description
ConfigSpec()

Method Summary

Modifier and Type	Method and Description
int	correct(Config config) Corrects a configuration.
int	correct(Config config, ConfigSpec.CorrectionListener listener) Corrects a configuration.
java.lang.Object	correct(java.util.List<java.lang.String> path, java.lang.Object value) Corrects a value.
java.lang.Object	correct(java.lang.String path, java.lang.Object value) Corrects a value.
void	define(java.util.List<java.lang.String> path, java.lang.Object defaultValue) Defines an entry.
void	define(java.util.List<java.lang.String> path, java.lang.Object defaultValue, java.util.function.Predicate<java.lang.Object> validator) Defines an entry.
void	define(java.util.List<java.lang.String> path, java.util.function.Supplier<?> defaultValueSupplier, java.util.function.Predicate<java.lang.Object> validator) Defines an entry.
void	define(java.lang.String path, java.lang.Object defaultValue) Defines an entry.
void	define(java.lang.String path, java.lang.Object defaultValue, java.util.function.Predicate<java.lang.Object> validator) Defines an entry.
void	define(java.lang.String path, java.util.function.Supplier<?> defaultValueSupplier, java.util.function.Predicate<java.lang.Object> validator) Defines an entry.
<T extends java.lang.Enum<T>> void	defineEnum(java.util.List<java.lang.String> path, java.lang.Class<T> enumType, EnumGetMethod method, java.util.function.Supplier<T> defaultValueSupplier)
<T extends java.lang.Enum<T>> void	defineEnum(java.util.List<java.lang.String> path, T defaultValue, EnumGetMethod method)
<T extends java.lang.Enum<T>> void	defineEnum(java.lang.String path, java.lang.Class<T> enumType, EnumGetMethod method, java.util.function.Supplier<T> defaultValueSupplier)
<T extends java.lang.Enum<T>> void	defineEnum(java.lang.String path, T defaultValue, EnumGetMethod method)
void	defineInList(java.util.List<java.lang.String> path, java.lang.Object defaultValue, java.util.Collection<?> acceptableValues) Defines an entry.
void	defineInList(java.util.List<java.lang.String> path, java.util.function.Supplier<?> defaultValueSupplier, java.util.Collection<?> acceptableValues) Defines an entry.
void	defineInList(java.lang.String path, java.lang.Object defaultValue, java.util.Collection<?> acceptableValues) Defines an entry.
void	defineInList(java.lang.String path, java.util.function.Supplier<?> defaultValueSupplier, java.util.Collection<?> acceptableValues) Defines an entry.
<V extends java.lang.Comparable<? super V>> void	defineInRange(java.util.List<java.lang.String> path, java.util.function.Supplier<V> defaultValueSupplier, V min, V max) Defines an entry.
<V extends java.lang.Comparable<? super V>> void	defineInRange(java.util.List<java.lang.String> path, V defaultValue, V min, V max) Defines an entry.
<V extends java.lang.Comparable<? super V>> void	defineInRange(java.lang.String path, java.util.function.Supplier<V> defaultValueSupplier, V min, V max) Defines an entry.
<V extends java.lang.Comparable<? super V>> void	defineInRange(java.lang.String path, V defaultValue, V min, V max) Defines an entry.
void	defineList(java.util.List<java.lang.String> path, java.util.List<?> defaultValue, java.util.function.Predicate<java.lang.Object> elementValidator) Defines an entry.
void	defineList(java.util.List<java.lang.String> path, java.util.function.Supplier<java.util.List<?>> defaultValueSupplier, java.util.function.Predicate<java.lang.Object> elementValidator) Defines an entry.
void	defineList(java.lang.String path, java.util.List<?> defaultValue, java.util.function.Predicate<java.lang.Object> elementValidator) Defines an entry.
void	defineList(java.lang.String path, java.util.function.Supplier<java.util.List<?>> defaultValueSupplier, java.util.function.Predicate<java.lang.Object> elementValidator) Defines an entry.
<V> void	defineOfClass(java.util.List<java.lang.String> path, java.util.function.Supplier<V> defaultValueSupplier, java.lang.Class<? super V> acceptableValueClass) Defines an entry.
<V> void	defineOfClass(java.util.List<java.lang.String> path, V defaultValue, java.lang.Class<? super V> acceptableValueClass) Defines an entry.
<V> void	defineOfClass(java.lang.String path, java.util.function.Supplier<V> defaultValueSupplier, java.lang.Class<? super V> acceptableValueClass) Defines an entry.
<V> void	defineOfClass(java.lang.String path, V defaultValue, java.lang.Class<? super V> acceptableValueClass) Defines an entry.
<T extends java.lang.Enum<T>> void	defineRestrictedEnum(java.util.List<java.lang.String> path, java.lang.Class<T> enumType, java.util.Collection<T> acceptableValues, EnumGetMethod method, java.util.function.Supplier<T> defaultValueSupplier)
<T extends java.lang.Enum<T>> void	defineRestrictedEnum(java.util.List<java.lang.String> path, T defaultValue, java.util.Collection<T> acceptableValues, EnumGetMethod method)
<T extends java.lang.Enum<T>> void	defineRestrictedEnum(java.lang.String path, java.lang.Class<T> enumType, java.util.Collection<T> acceptableValues, EnumGetMethod method, java.util.function.Supplier<T> defaultValueSupplier)
<T extends java.lang.Enum<T>> void	defineRestrictedEnum(java.lang.String path, T defaultValue, java.util.Collection<T> acceptableValues, EnumGetMethod method)
boolean	isCorrect(Config config) Checks that a configuration is conform to the specification.
boolean	isCorrect(java.util.List<java.lang.String> path, java.lang.Object value) Checks that a value is conform to the specification.
boolean	isCorrect(java.lang.String path, java.lang.Object value) Checks that a value is conform to the specification.
boolean	isDefined(java.util.List<java.lang.String> path) Checks if an entry has been defined.
boolean	isDefined(java.lang.String path) Checks if an entry has been defined.
void	undefine(java.util.List<java.lang.String> path) Undefines an entry.
void	undefine(java.lang.String path) Undefines an entry.

Methods inherited from class java.lang.Object

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

Field Detail

storage

protected final Config storage

Constructor Detail

ConfigSpec

public ConfigSpec()

Method Detail

define

public void define(java.lang.String path,
                   java.lang.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(java.util.List<java.lang.String> path,
                   java.lang.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(java.lang.String path,
                   java.lang.Object defaultValue,
                   java.util.function.Predicate<java.lang.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(java.lang.String path,
                   java.util.function.Supplier<?> defaultValueSupplier,
                   java.util.function.Predicate<java.lang.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(java.util.List<java.lang.String> path,
                   java.lang.Object defaultValue,
                   java.util.function.Predicate<java.lang.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(java.util.List<java.lang.String> path,
                   java.util.function.Supplier<?> defaultValueSupplier,
                   java.util.function.Predicate<java.lang.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(java.lang.String path,
                              V defaultValue,
                              java.lang.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(java.lang.String path,
                              java.util.function.Supplier<V> defaultValueSupplier,
                              java.lang.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(java.util.List<java.lang.String> path,
                              V defaultValue,
                              java.lang.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(java.util.List<java.lang.String> path,
                              java.util.function.Supplier<V> defaultValueSupplier,
                              java.lang.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(java.lang.String path,
                         java.lang.Object defaultValue,
                         java.util.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(java.lang.String path,
                         java.util.function.Supplier<?> defaultValueSupplier,
                         java.util.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(java.util.List<java.lang.String> path,
                         java.lang.Object defaultValue,
                         java.util.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(java.util.List<java.lang.String> path,
                         java.util.function.Supplier<?> defaultValueSupplier,
                         java.util.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 java.lang.Comparable<? super V>> void defineInRange(java.lang.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 java.lang.Comparable<? super V>> void defineInRange(java.lang.String path,
                                                                      java.util.function.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 java.lang.Comparable<? super V>> void defineInRange(java.util.List<java.lang.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 java.lang.Comparable<? super V>> void defineInRange(java.util.List<java.lang.String> path,
                                                                      java.util.function.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(java.lang.String path,
                       java.util.List<?> defaultValue,
                       java.util.function.Predicate<java.lang.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(java.lang.String path,
                       java.util.function.Supplier<java.util.List<?>> defaultValueSupplier,
                       java.util.function.Predicate<java.lang.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(java.util.List<java.lang.String> path,
                       java.util.List<?> defaultValue,
                       java.util.function.Predicate<java.lang.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(java.util.List<java.lang.String> path,
                       java.util.function.Supplier<java.util.List<?>> defaultValueSupplier,
                       java.util.function.Predicate<java.lang.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 java.lang.Enum<T>> void defineEnum(java.lang.String path,
                                                     T defaultValue,
                                                     EnumGetMethod method)

defineEnum

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

defineEnum

public <T extends java.lang.Enum<T>> void defineEnum(java.lang.String path,
                                                     java.lang.Class<T> enumType,
                                                     EnumGetMethod method,
                                                     java.util.function.Supplier<T> defaultValueSupplier)

defineEnum

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

defineRestrictedEnum

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

defineRestrictedEnum

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

defineRestrictedEnum

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

defineRestrictedEnum

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

undefine

public void undefine(java.lang.String path)

Undefines an entry.

Parameters:

path - the entry's path

undefine

public void undefine(java.util.List<java.lang.String> path)

Undefines an entry.

Parameters:

path - the entry's path

isDefined

public boolean isDefined(java.lang.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(java.util.List<java.lang.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(java.lang.String path,
                         java.lang.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(java.util.List<java.lang.String> path,
                         java.lang.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 java.lang.Object correct(java.lang.String path,
                                java.lang.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 java.lang.Object correct(java.util.List<java.lang.String> path,
                                java.lang.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.