Interface ConfigurationNode
- All Known Subinterfaces:
AttributedConfigurationNode
,CommentedConfigurationNode
- All Known Implementing Classes:
SimpleAttributedConfigurationNode
,SimpleCommentedConfigurationNode
,SimpleConfigurationNode
public interface ConfigurationNode
All aspects of a configurations structure are represented using instances of
ConfigurationNode
, and the links between them.
ConfigurationNode
s can hold different types of values
. They can:
- Hold a single "scalar" value (
ValueType.SCALAR
) - Represent a "list" of child
ConfigurationNode
s (ValueType.LIST
) - Represent a "map" of child
ConfigurationNode
s (ValueType.MAP
) - Hold no value at all (
ValueType.NULL
)
The overall configuration stems from a single "root" node, which is provided by the
ConfigurationLoader
, or by other means programmatically.
This is effectively the main class of Configurate.
-
Field Summary
Fields Modifier and Type Field Description static int
NUMBER_DEF
-
Method Summary
Modifier and Type Method Description default ConfigurationNode
act(Consumer<? super ConfigurationNode> action)
Execute an action on this node.default @NonNull ConfigurationNode
appendListNode()
Gets a new child node created as the next entry in the list.@NonNull ConfigurationNode
copy()
Creates a deep copy of this node.@NonNull ConfigurationNode
getAppendedNode()
Deprecated.default boolean
getBoolean()
Gets the value typed using the appropriate type conversion fromTypes
default boolean
getBoolean(boolean def)
Gets the value typed using the appropriate type conversion fromTypes
@NonNull List<? extends ConfigurationNode>
getChildrenList()
Gets the "list children" attached to this node, if it has any.@NonNull Map<Object,? extends ConfigurationNode>
getChildrenMap()
Gets the "map children" attached to this node, if it has any.default double
getDouble()
Gets the value typed using the appropriate type conversion fromTypes
default double
getDouble(double def)
Gets the value typed using the appropriate type conversion fromTypes
default float
getFloat()
Gets the value typed using the appropriate type conversion fromTypes
default float
getFloat(float def)
Gets the value typed using the appropriate type conversion fromTypes
default int
getInt()
Gets the value typed using the appropriate type conversion fromTypes
default int
getInt(int def)
Gets the value typed using the appropriate type conversion fromTypes
@Nullable Object
getKey()
Gets the "key" of this node.default <T> @NonNull List<T>
getList(@NonNull TypeToken<T> type)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.<T> List<T>
getList(@NonNull TypeToken<T> type, @NonNull Supplier<List<T>> defSupplier)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.<T> List<T>
getList(@NonNull TypeToken<T> type, @Nullable List<T> def)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.<T> @NonNull List<T>
getList(@NonNull Function<Object,T> transformer)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.<T> List<T>
getList(@NonNull Function<Object,T> transformer, @NonNull Supplier<List<T>> defSupplier)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.<T> List<T>
getList(@NonNull Function<Object,T> transformer, @Nullable List<T> def)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default long
getLong()
Gets the value typed using the appropriate type conversion fromTypes
default long
getLong(long def)
Gets the value typed using the appropriate type conversion fromTypes
default @NonNull ConfigurationNode
getNode(@NonNull Iterable<?> path)
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.@NonNull ConfigurationNode
getNode(@NonNull Object @NonNull ... path)
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.@NonNull ConfigurationOptions
getOptions()
Gets the options that currently apply to this node@Nullable ConfigurationNode
getParent()
Gets the parent of this node.@NonNull Object[]
getPath()
Gets the full path ofkeys
from the root node to this node.default @Nullable String
getString()
Gets the value typed using the appropriate type conversion fromTypes
default String
getString(@Nullable String def)
Gets the value typed using the appropriate type conversion fromTypes
default @Nullable Object
getValue()
Get the current value associated with this node.default <T> @Nullable T
getValue(@NonNull TypeToken<T> type)
Get the current value associated with this node.<T> T
getValue(@NonNull TypeToken<T> type, @NonNull Supplier<T> defSupplier)
Get the current value associated with this node.<T> T
getValue(@NonNull TypeToken<T> type, T def)
Get the current value associated with this node.default <T> @Nullable T
getValue(@NonNull Function<Object,T> transformer)
Gets the appropriately transformed typed version of this node's value from the provided transformation function.<T> T
getValue(@NonNull Function<Object,T> transformer, @NonNull Supplier<T> defSupplier)
Gets the appropriately transformed typed version of this node's value from the provided transformation function.<T> T
getValue(@NonNull Function<Object,T> transformer, @Nullable T def)
Gets the appropriately transformed typed version of this node's value from the provided transformation function.Object
getValue(@NonNull Supplier<Object> defSupplier)
Get the current value associated with this node.Object
getValue(@Nullable Object def)
Get the current value associated with this node.@NonNull ValueType
getValueType()
default boolean
hasListChildren()
Deprecated.UseisList()
insteaddefault boolean
hasMapChildren()
Deprecated.UseisMap()
insteaddefault boolean
isEmpty()
Return true when this node has a null or empty value.default boolean
isList()
Gets if this node has "list children".default boolean
isMap()
Gets if this node has "map children".boolean
isVirtual()
Gets if this node is virtual.@NonNull ConfigurationNode
mergeValuesFrom(@NonNull ConfigurationNode other)
Set all the values from the given node that are not present in this node to their values in the provided node.boolean
removeChild(@NonNull Object key)
Removes a direct child of this nodestatic @NonNull ConfigurationNode
root()
static @NonNull ConfigurationNode
root(@NonNull ConfigurationOptions options)
static @NonNull ConfigurationNode
root(@NonNull ConfigurationOptions options, Consumer<ConfigurationNode> action)
static @NonNull ConfigurationNode
root(Consumer<ConfigurationNode> action)
default <T> @NonNull ConfigurationNode
setValue(@NonNull TypeToken<T> type, @Nullable T value)
Set this node's value to the given value.@NonNull ConfigurationNode
setValue(@Nullable Object value)
Set this node's value to the given value.default <S, T> T
visit(ConfigurationVisitor.Safe<S,T> visitor)
Visit this node hierarchy as described inConfigurationVisitor
This overload will remove the need for exception handling for visitors that do not have any checked exceptions.default <S, T> T
visit(ConfigurationVisitor.Safe<S,T> visitor, S state)
Visit this node hierarchy as described inConfigurationVisitor
This overload will remove the need for exception handling for visitors that do not have any checked exceptions.default <S, T, E extends Exception>
Tvisit(ConfigurationVisitor<S,T,E> visitor)
Visit this node hierarchy as described inConfigurationVisitor
default <S, T, E extends Exception>
Tvisit(ConfigurationVisitor<S,T,E> visitor, S state)
Visit this node hierarchy as described inConfigurationVisitor
-
Field Details
-
NUMBER_DEF
- See Also:
- Constant Field Values
-
-
Method Details
-
root
-
root
-
root
-
root
static @NonNull ConfigurationNode root(@NonNull ConfigurationOptions options, Consumer<ConfigurationNode> action) -
getKey
Gets the "key" of this node.The key determines this
ConfigurationNode
s position within the overall configuration structure.If this node is currently
virtual
, this method's result may be inaccurate.Note that this method only returns the nearest "link" in the hierarchy, and does not return a representation of the full path. See
getPath()
for that.The
ConfigurationNode
s returned as values fromgetChildrenMap()
will have keys derived from their pairing in the map node.The
ConfigurationNode
s returned fromgetChildrenList()
will have keys derived from their position (index) in the list node.- Returns:
- The key of this node
-
getPath
Gets the full path ofkeys
from the root node to this node.Node implementations may not keep a full path for each node, so this method may be somewhat complex to calculate. Most uses should not need to calculate the full path unless providing debug information
- Returns:
- An array compiled from the keys for each node up the hierarchy
- See Also:
for this node's key relative to its direct parent
-
getParent
Gets the parent of this node.If this node is currently
virtual
, this method's result may be inaccurate.- Returns:
- The nodes parent
-
getNode
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.This is the main method used to navigate through the configuration.
The path parameter effectively consumes an array of keys, which locate the unique position of a given node within the structure. Each element will navigate one level down in the configration hierarchy
A node is always returned by this method. If the given node does not exist in the structure, a
virtual
node will be returned which represents the position.- Parameters:
path
- The path to fetch the node at- Returns:
- The node at the given path, possibly virtual
-
getNode
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.This is the main method used to navigate through the configuration.
The path parameter effectively consumes an iterable of keys, which locate the unique position of a given node within the structure.
A node is always returned by this method. If the given node does not exist in the structure, a
virtual
node will be returned which represents the position.- Parameters:
path
- The path to fetch the node at- Returns:
- The node at the given path, possibly virtual
-
isVirtual
boolean isVirtual()Gets if this node is virtual.Virtual nodes are nodes which are not attached to a wider configuration structure.
A node is primarily "virtual" when it has no set value.
- Returns:
- true if this node is virtual
-
getOptions
Gets the options that currently apply to this node- Returns:
- The ConfigurationOptions instance that governs the functionality of this node
-
getValueType
Gets the value type of this node.- Returns:
- The value type
-
isList
Gets if this node has "list children".- Returns:
- if this node has children in the form of a list
-
isMap
Gets if this node has "map children".- Returns:
- if this node has children in the form of a map
-
hasListChildren
Deprecated.UseisList()
insteadGets if this node has "list children".- Returns:
- if this node has children in the form of a list
-
hasMapChildren
Deprecated.UseisMap()
insteadGets if this node has "map children"- Returns:
- if this node has children in the form of a map
-
isEmpty
Return true when this node has a null or empty value. Values that may result in this method returning true include:null
- the empty string
- an empty map
- an empty list
- Any other type of empty collection
isVirtual()
. Emptiness refers to the value of this node itself, while virtuality refers to whether or not this node is attached to its parent and the rest of the configuration structure.- Returns:
- Whether this node is empty
-
getChildrenList
@NonNull List<? extends ConfigurationNode> getChildrenList()Gets the "list children" attached to this node, if it has any.If this node does not
have list children
, an empty list is returned. For example, if the value of this node is a map, this will return an empty result.- Returns:
- The list children currently attached to this node
-
getChildrenMap
@NonNull Map<Object,? extends ConfigurationNode> getChildrenMap()Gets the "map children" attached to this node, if it has any.If this node does not
have map children
, an empty map returned.- Returns:
- The map children currently attached to this node
-
getValue
Get the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
- Returns:
- This configuration's current value, or null if there is none
- See Also:
getValue(Object)
-
getValue
Get the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
- Parameters:
def
- The default value to return if this node has no set value- Returns:
- This configuration's current value, or
def
if there is none
-
getValue
Get the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
- Parameters:
defSupplier
- The function that will be called to calculate a default value only if there is no existing value- Returns:
- This configuration's current value, or
def
if there is none
-
getValue
Gets the appropriately transformed typed version of this node's value from the provided transformation function.- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation function- Returns:
- A transformed value of the correct type, or null either if no value is present or the value could not be converted
-
getValue
Gets the appropriately transformed typed version of this node's value from the provided transformation function.- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation functiondef
- The default value to return if this node has no set value or is not of a convertible type- Returns:
- A transformed value of the correct type, or
def
either if no value is present or the value could not be converted
-
getValue
Gets the appropriately transformed typed version of this node's value from the provided transformation function.- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation functiondefSupplier
- The function that will be called to calculate a default value only if there is no existing value of the correct type- Returns:
- A transformed value of the correct type, or
def
either if no value is present or the value could not be converted
-
getList
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value
- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation function- Returns:
- An immutable copy of the values contained
-
getList
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value.
- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation functiondef
- The default value if no appropriate value is set- Returns:
- An immutable copy of the values contained that could be successfully converted, or
def
if no values could be converted
-
getList
<T> List<T> getList(@NonNull Function<Object,T> transformer, @NonNull Supplier<List<T>> defSupplier)If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value.
- Type Parameters:
T
- The expected type- Parameters:
transformer
- The transformation functiondefSupplier
- The function that will be called to calculate a default value only if there is no existing value of the correct type- Returns:
- An immutable copy of the values contained that could be successfully converted, or
def
if no values could be converted
-
getList
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value.
- Type Parameters:
T
- The expected type- Parameters:
type
- The expected type- Returns:
- An immutable copy of the values contained
- Throws:
ObjectMappingException
- If any value fails to be converted to the requested type
-
getList
<T> List<T> getList(@NonNull TypeToken<T> type, @Nullable List<T> def) throws ObjectMappingExceptionIf this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value.
- Type Parameters:
T
- The expected type- Parameters:
type
- The expected typedef
- The default value if no appropriate value is set- Returns:
- An immutable copy of the values contained that could be successfully converted, or
def
if no values could be converted - Throws:
ObjectMappingException
- If any value fails to be converted to the requested type
-
getList
<T> List<T> getList(@NonNull TypeToken<T> type, @NonNull Supplier<List<T>> defSupplier) throws ObjectMappingExceptionIf this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.If this node has a scalar value, this function treats it as a list with one value.
- Type Parameters:
T
- The expected type- Parameters:
type
- The expected typedefSupplier
- The function that will be called to calculate a default value only if there is no existing value of the correct type- Returns:
- An immutable copy of the values contained that could be successfully converted, or
def
if no values could be converted - Throws:
ObjectMappingException
- If any value fails to be converted to the requested type
-
getString
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, null if no appropriate value is available
- See Also:
getValue()
-
getString
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getFloat
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, 0 if no appropriate value is available
- See Also:
getValue()
-
getFloat
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getDouble
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, 0 if no appropriate value is available
- See Also:
getValue()
-
getDouble
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getInt
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, 0 if no appropriate value is available
- See Also:
getValue()
-
getInt
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getLong
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, 0 if no appropriate value is available
- See Also:
getValue()
-
getLong
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getBoolean
Gets the value typed using the appropriate type conversion fromTypes
- Returns:
- The appropriate type conversion, false if no appropriate value is available
- See Also:
getValue()
-
getBoolean
Gets the value typed using the appropriate type conversion fromTypes
- Parameters:
def
- The default value if no appropriate value is set- Returns:
- The appropriate type conversion,
def
if no appropriate value is available - See Also:
getValue()
-
getValue
Get the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
This method will also perform deserialization using the appropriate TypeSerializer for the given type, or casting if no type serializer is found.
- Type Parameters:
T
- the type to get- Parameters:
type
- The type to deserialize to- Returns:
- the value if present and of the proper type, else null
- Throws:
ObjectMappingException
- If the value fails to be converted to the requested type
-
getValue
Get the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
This method will also perform deserialization using the appropriate TypeSerializer for the given type, or casting if no type serializer is found.
- Type Parameters:
T
- the type to get- Parameters:
type
- The type to deserialize todef
- The value to return if no value or value is not of appropriate type- Returns:
- the value if of the proper type, else
def
- Throws:
ObjectMappingException
- If the value fails to be converted to the requested type
-
getValue
<T> T getValue(@NonNull TypeToken<T> type, @NonNull Supplier<T> defSupplier) throws ObjectMappingExceptionGet the current value associated with this node.If this node has children, this method will recursively unwrap them to construct a List or a Map.
This method will also perform deserialization using the appropriate TypeSerializer for the given type, or casting if no type serializer is found.
- Type Parameters:
T
- the type to get- Parameters:
type
- The type to deserialize todefSupplier
- The function that will be called to calculate a default value only if there is no existing value of the correct type- Returns:
- the value if of the proper type, else
def
- Throws:
ObjectMappingException
- If the value fails to be converted to the requested type
-
setValue
Set this node's value to the given value.If the provided value is a
This method only accepts native types as values. If the type of a value is unknown at runtime,Collection
or aMap
, it will be unwrapped into the appropriate configuration node structure.ConfigurationOptions.acceptsType(Class)
will return whether or not it is a native type.- Parameters:
value
- The value to set- Returns:
- this
- See Also:
to set a value with any type conversion necessary
-
setValue
default <T> @NonNull ConfigurationNode setValue(@NonNull TypeToken<T> type, @Nullable T value) throws ObjectMappingExceptionSet this node's value to the given value.If the provided value is a
Collection
or aMap
, it will be unwrapped into the appropriate configuration node structure.This method will also perform serialization using the appropriate TypeSerializer for the given type, or casting if no type serializer is found.
- Type Parameters:
T
- The type to serialize to- Parameters:
type
- The type to use for serialization type informationvalue
- The value to set- Returns:
- this
- Throws:
ObjectMappingException
- If the value fails to be converted to the requested type. No change will be made to the node.
-
mergeValuesFrom
Set all the values from the given node that are not present in this node to their values in the provided node.Map keys will be merged. Lists and scalar values will be replaced.
- Parameters:
other
- The node to merge values from- Returns:
- this
-
removeChild
Removes a direct child of this node- Parameters:
key
- The key of the node to remove- Returns:
- If a node was removed
-
getAppendedNode
Deprecated.UseappendListNode()
insteadGets a new child node created as the next entry in the list.- Returns:
- A new child created as the next entry in the list when it is attached
-
appendListNode
Gets a new child node created as the next entry in the list.- Returns:
- A new child created as the next entry in the list when it is attached
-
copy
Creates a deep copy of this node.If this node has child nodes (is a list or map), the child nodes will also be copied. This action is performed recursively.
The resultant node will (initially) contain the same value(s) as this node, and will therefore be
equal
, however, changes made to the original will not be reflected in the copy, and vice versa.The actual scalar values that back the configuration will not be copied - only the node structure that forms the configuration. This is not a problem in most cases, as the scalar values stored in configurations are usually immutable. (e.g. strings, numbers, booleans).
- Returns:
- A copy of this node
-
act
Execute an action on this node. This allows performing multiple operations on a single node without having to clutter up the surrounding scope.- Parameters:
action
- The action to perform on this node- Returns:
- this
-
visit
default <S, T, E extends Exception> T visit(ConfigurationVisitor<S,T,E> visitor) throws E extends ExceptionVisit this node hierarchy as described inConfigurationVisitor
- Type Parameters:
S
- The state typeT
- The terminal typeE
- exception type that may be thrown- Parameters:
visitor
- The visitor- Returns:
- The returned terminal from the visitor
- Throws:
E
- when throw by visitor implementation
-
visit
default <S, T, E extends Exception> T visit(ConfigurationVisitor<S,T,E> visitor, S state) throws E extends ExceptionVisit this node hierarchy as described inConfigurationVisitor
- Type Parameters:
T
- The terminal typeS
- The state typeE
- exception type that may be thrown- Parameters:
visitor
- The visitorstate
- The state to start with- Returns:
- The returned terminal from the visitor
- Throws:
E
- when throw by visitor implementation
-
visit
Visit this node hierarchy as described inConfigurationVisitor
This overload will remove the need for exception handling for visitors that do not have any checked exceptions.- Type Parameters:
S
- The state typeT
- The terminal type- Parameters:
visitor
- The visitor- Returns:
- The returned terminal from the visitor
-
visit
Visit this node hierarchy as described inConfigurationVisitor
This overload will remove the need for exception handling for visitors that do not have any checked exceptions.- Type Parameters:
T
- The terminal typeS
- The state type- Parameters:
visitor
- The visitorstate
- The state to start with- Returns:
- The returned terminal from the visitor
-
appendListNode()
instead