Interface ConfigurationNode
-
- All Known Subinterfaces:
AttributedConfigurationNode
,BasicConfigurationNode
,CommentedConfigurationNode
,CommentedConfigurationNodeIntermediary<N>
,ScopedConfigurationNode<N>
public interface ConfigurationNode
A node in the configuration tree.All aspects of a configurations structure are represented using instances of
ConfigurationNode
, and the links between them.ConfigurationNode
s can hold different types of value. They can:- Hold a single "scalar" value (accessed by
rawScalar()
- Represent a "list" of child
ConfigurationNode
s (accessed byisList()
andchildrenList()
) - Represent a "map" of child
ConfigurationNode
s (accessed byisMap()
andchildrenMap()
) - Hold no value at all (when
virtual()
is true)
The overall configuration stems from a single "root" node, which is provided by the
ConfigurationLoader
, or by other means programmatically.- Since:
- 4.0.0
-
-
Field Summary
Fields Modifier and Type Field Description static int
NUMBER_DEF
Default value for unknown number results.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description ConfigurationNode
appendListNode()
Gets a new child node created as the next entry in the list.List<? extends ConfigurationNode>
childrenList()
Gets the "list children" attached to this node, if it has any.Map<Object,? extends ConfigurationNode>
childrenMap()
Gets the "map children" attached to this node, if it has any.ConfigurationNode
copy()
Creates a deep copy of this node.boolean
empty()
Return true when this node has a null or empty value.ConfigurationNode
from(ConfigurationNode other)
Apply all data fromother
to this node, overwriting any existing data.default <V> @Nullable V
get(TypeToken<V> type)
Get the current value associated with this node.default <V> V
get(TypeToken<V> type, Supplier<V> defSupplier)
Get the current value associated with this node.default <V> V
get(TypeToken<V> type, V def)
Get the current value associated with this node.default <V> @Nullable V
get(Class<V> type)
Get the current value associated with this node.default <V> V
get(Class<V> type, Supplier<V> defSupplier)
Get the current value associated with this node.default <V> V
get(Class<V> type, V def)
Get the current value associated with this node.@Nullable Object
get(Type type)
Get the current value associated with this node.default Object
get(Type type, Object def)
Get the current value associated with this node.default Object
get(Type type, Supplier<?> defSupplier)
Get the current value associated with this node.default boolean
getBoolean()
Gets the value typed using the appropriate type conversion fromScalars
.default boolean
getBoolean(boolean def)
Gets the value typed using the appropriate type conversion fromScalars
.default double
getDouble()
Gets the value typed using the appropriate type conversion fromScalars
.default double
getDouble(double def)
Gets the value typed using the appropriate type conversion fromScalars
.default float
getFloat()
Gets the value typed using the appropriate type conversion fromScalars
.default float
getFloat(float def)
Gets the value typed using the appropriate type conversion fromScalars
.default int
getInt()
Gets the value typed using the appropriate type conversion fromScalars
.default int
getInt(int def)
Gets the value typed using the appropriate type conversion fromScalars
.default <V> @Nullable List<V>
getList(TypeToken<V> type)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default <V> List<V>
getList(TypeToken<V> elementType, Supplier<List<V>> defSupplier)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default <V> List<V>
getList(TypeToken<V> elementType, List<V> def)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default <V> @Nullable List<V>
getList(Class<V> type)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default <V> List<V>
getList(Class<V> elementType, Supplier<List<V>> defSupplier)
If this node has list values, this function unwraps them and converts them to an appropriate type based on the provided function.default <V> List<V>
getList(Class<V> elementType, List<V> 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 fromScalars
.default long
getLong(long def)
Gets the value typed using the appropriate type conversion fromScalars
.default @Nullable String
getString()
Gets the value typed using the appropriate type conversion fromScalars
.default String
getString(String def)
Gets the value typed using the appropriate type conversion fromScalars
.boolean
hasChild(Iterable<?> path)
Checks whether or not a non-virtual node is present at the relative pathpath
.boolean
hasChild(Object... path)
Checks whether or not a non-virtual node is present at the relative pathpath
.<V> @Nullable V
hint(RepresentationHint<V> hint)
Query a representation hint from this node.<V> ConfigurationNode
hint(RepresentationHint<V> hint, @Nullable V value)
Set a representation hint on this node.boolean
isList()
Gets if this node has "list children".boolean
isMap()
Gets if this node has "map children".@Nullable Object
key()
Gets the "key" of this node.ConfigurationNode
mergeFrom(ConfigurationNode other)
Set all the values from the given node that are not present in this node to their values in the provided node.ConfigurationNode
node(Iterable<?> path)
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.ConfigurationNode
node(Object... path)
Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.ConfigurationOptions
options()
Gets the options that currently apply to this node.<V> @Nullable V
ownHint(RepresentationHint<V> hint)
Query a representation hint from this node.Map<RepresentationHint<?>,?>
ownHints()
Get an unmodifiable copy of representation hints stored on this node.@Nullable ConfigurationNode
parent()
Gets the parent of this node.NodePath
path()
Gets the full path ofkeys
from the root node to this node.@Nullable Object
raw()
Get the raw value of this node.ConfigurationNode
raw(@Nullable Object value)
Set the raw value of this node.@Nullable Object
rawScalar()
Get the raw value of this node if the node is a scalar.boolean
removeChild(Object key)
Removes a direct child of this node.ConfigurationNode
set(@Nullable Object value)
Set this node's value to the given value.<V> ConfigurationNode
set(TypeToken<V> type, @Nullable V value)
Set this node's value to the given value.<V> ConfigurationNode
set(Class<V> type, @Nullable V value)
Set this node's value to the given value.ConfigurationNode
set(Type type, @Nullable Object value)
Set this node's value to the given value.default <V> ConfigurationNode
setList(TypeToken<V> elementType, @Nullable List<V> items)
Set the node's value to the provided list.default <V> ConfigurationNode
setList(Class<V> elementType, @Nullable List<V> items)
Set the node's value to the provided list.default <V> Collector<V,? extends ConfigurationNode,? extends ConfigurationNode>
toListCollector(TypeToken<V> valueType)
Create a collector that appends values to this node as list children.default <V> Collector<V,? extends ConfigurationNode,? extends ConfigurationNode>
toListCollector(Class<V> valueType)
Create a collector that appends values to this node as list children.default <V> Collector<Map.Entry<?,V>,? extends ConfigurationNode,? extends ConfigurationNode>
toMapCollector(TypeToken<V> valueType)
Create a collector that appends values to this node as map children.default <V> Collector<Map.Entry<?,V>,? extends ConfigurationNode,? extends ConfigurationNode>
toMapCollector(Class<V> valueType)
Create a collector that appends values to this node as map children.boolean
virtual()
Gets if this node is virtual.default <S,T>
Tvisit(ConfigurationVisitor.Safe<S,T> visitor)
Visit this node hierarchy as described inConfigurationVisitor
.<S,T>
Tvisit(ConfigurationVisitor.Safe<S,T> visitor, S state)
Visit this node hierarchy as described inConfigurationVisitor
.default <S,T,E extends Exception>
Tvisit(ConfigurationVisitor<S,T,E> visitor)
Visit this node hierarchy as described inConfigurationVisitor
.<S,T,E extends Exception>
Tvisit(ConfigurationVisitor<S,T,E> visitor, S state)
Visit this node hierarchy as described inConfigurationVisitor
.
-
-
-
Field Detail
-
NUMBER_DEF
static final int NUMBER_DEF
Default value for unknown number results.- Since:
- 4.0.0
- See Also:
- Constant Field Values
-
-
Method Detail
-
key
@Nullable Object key()
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
path()
for that.The
ConfigurationNode
s returned as values fromchildrenMap()
will have keys derived from their pairing in the map node.The
ConfigurationNode
s returned fromchildrenList()
will have keys derived from their position (index) in the list node.- Returns:
- the key of this node
- Since:
- 4.0.0
-
path
NodePath path()
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
- Since:
- 4.0.0
-
parent
@Nullable ConfigurationNode parent()
Gets the parent of this node.If this node is currently
virtual
, this method's result may be inaccurate.- Returns:
- the nodes parent
- Since:
- 4.0.0
-
node
ConfigurationNode node(Object... path)
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 configuration 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
- Since:
- 4.0.0
-
node
ConfigurationNode node(Iterable<?> path)
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.
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
- Since:
- 4.0.0
-
hasChild
boolean hasChild(Object... path)
Checks whether or not a non-virtual node is present at the relative pathpath
.This allows checking for more remote nodes in the configuration hierarchy without having to instantiate new unattached node objects.
- Parameters:
path
- path to search at- Returns:
- if a non-virtual child is present
- Since:
- 4.0.0
-
hasChild
boolean hasChild(Iterable<?> path)
Checks whether or not a non-virtual node is present at the relative pathpath
.This allows checking for more remote nodes in the configuration hierarchy without having to instantiate new unattached node objects.
- Parameters:
path
- path to search at- Returns:
- if a non-virtual child is present
- Since:
- 4.0.0
-
virtual
boolean virtual()
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- Since:
- 4.0.0
-
options
ConfigurationOptions options()
Gets the options that currently apply to this node.- Returns:
- the
ConfigurationOptions
instance controlling the functionality of this node. - Since:
- 4.0.0
-
isList
boolean isList()
Gets if this node has "list children".- Returns:
- if this node has children in the form of a list
- Since:
- 4.0.0
-
isMap
boolean isMap()
Gets if this node has "map children".- Returns:
- if this node has children in the form of a map
- Since:
- 4.0.0
-
empty
boolean empty()
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
This is a separate value from
virtual()
. Emptiness refers to the value of this node itself, while virtuality refers to whether or not this node is attached to a configuration structure.- Returns:
- whether this node is empty
- Since:
- 4.0.0
-
childrenList
List<? extends ConfigurationNode> childrenList()
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.- Returns:
- the list children currently attached to this node
- Since:
- 4.0.0
-
childrenMap
Map<Object,? extends ConfigurationNode> childrenMap()
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
- Since:
- 4.0.0
-
toMapCollector
default <V> Collector<Map.Entry<?,V>,? extends ConfigurationNode,? extends ConfigurationNode> toMapCollector(TypeToken<V> valueType)
Create a collector that appends values to this node as map children.This collector does not accept values in parallel.
- Type Parameters:
V
- value type- Parameters:
valueType
- marker for value type- Returns:
- a new collector
- Since:
- 4.0.0
-
toMapCollector
default <V> Collector<Map.Entry<?,V>,? extends ConfigurationNode,? extends ConfigurationNode> toMapCollector(Class<V> valueType)
Create a collector that appends values to this node as map children.This collector does not accept values in parallel.
- Type Parameters:
V
- value type- Parameters:
valueType
- marker for value type- Returns:
- a new collector
- Since:
- 4.0.0
-
toListCollector
default <V> Collector<V,? extends ConfigurationNode,? extends ConfigurationNode> toListCollector(TypeToken<V> valueType)
Create a collector that appends values to this node as list children.This collector does not accept values in parallel.
- Type Parameters:
V
- value type- Parameters:
valueType
- marker for value type- Returns:
- a new collector
- Since:
- 4.0.0
-
toListCollector
default <V> Collector<V,? extends ConfigurationNode,? extends ConfigurationNode> toListCollector(Class<V> valueType)
Create a collector that appends values to this node as list children.This collector does not accept values in parallel.
- Type Parameters:
V
- value type- Parameters:
valueType
- marker for value type- Returns:
- a new collector
- Since:
- 4.0.0
-
get
default <V> @Nullable V get(TypeToken<V> type) throws SerializationException
Get the current value associated with this node.This method will perform deserialization using the appropriate
TypeSerializer
for the given type, or attempting to cast if no type serializer is found.- Type Parameters:
V
- the type to get- Parameters:
type
- the type to deserialize to- Returns:
- the value if present and of the proper type, else null
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default <V> V get(TypeToken<V> type, V def) throws SerializationException
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:
V
- the type to get- Parameters:
type
- the type to deserialize as.def
- value to return ifvirtual()
or value is not of appropriate type- Returns:
- the value if of the proper type, else
def
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default <V> V get(TypeToken<V> type, Supplier<V> defSupplier) throws SerializationException
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:
V
- 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:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default <V> @Nullable V get(Class<V> type) throws SerializationException
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:
V
- the type to get- Parameters:
type
- the type to deserialize to- Returns:
- the value if present and of the proper type, else null
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default <V> V get(Class<V> type, V def) throws SerializationException
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:
V
- the type to get- Parameters:
type
- the type to deserialize as.def
- value to return ifvirtual()
or value is not of appropriate type- Returns:
- the value if of the proper type, else
def
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default <V> V get(Class<V> type, Supplier<V> defSupplier) throws SerializationException
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:
V
- 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:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
@Nullable Object get(Type type) throws SerializationException
Get the current value associated with this node.This method will attempt to deserialize the node's value to the provided
Type
using a configuredTypeSerializer
for the given type, or casting if no type serializer is found.- Parameters:
type
- the type to deserialize to- Returns:
- the value if present and of the proper type, else null
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default Object get(Type type, Object def) throws SerializationException
Get the current value associated with this node.This method will attempt to deserialize the node's value to the provided
Type
using a configuredTypeSerializer
for the given type, or casting if no type serializer is found.- Parameters:
type
- the type to deserialize asdef
- value to return ifvirtual()
or value is not of appropriate type- Returns:
- the value if of the proper type, else
def
- Throws:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
get
default Object get(Type type, Supplier<?> defSupplier) throws SerializationException
Get the current value associated with this node.This method will attempt to deserialize the node's value to the provided
Type
using a configuredTypeSerializer
for the given type, or casting if no type serializer is found.- 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:
SerializationException
- if the value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> @Nullable List<V> getList(TypeToken<V> type) throws SerializationException
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:
V
- the expected type- Parameters:
type
- the expected type- Returns:
- an immutable copy of the values contained
- Throws:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> List<V> getList(TypeToken<V> elementType, List<V> def) throws SerializationException
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:
V
- expected type- Parameters:
elementType
- expected typedef
- 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:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> List<V> getList(TypeToken<V> elementType, Supplier<List<V>> defSupplier) throws SerializationException
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:
V
- expected type- Parameters:
elementType
- expected typedefSupplier
- 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:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> @Nullable List<V> getList(Class<V> type) throws SerializationException
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:
V
- the expected type- Parameters:
type
- the expected type- Returns:
- an immutable copy of the values contained
- Throws:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> List<V> getList(Class<V> elementType, List<V> def) throws SerializationException
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:
V
- expected type- Parameters:
elementType
- expected typedef
- 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:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getList
default <V> List<V> getList(Class<V> elementType, Supplier<List<V>> defSupplier) throws SerializationException
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:
V
- expected type- Parameters:
elementType
- expected typedefSupplier
- 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:
SerializationException
- if any value fails to be converted to the requested type- Since:
- 4.0.0
-
getString
default @Nullable String getString()
Gets the value typed using the appropriate type conversion fromScalars
.
-
getString
default String getString(String def)
Gets the value typed using the appropriate type conversion fromScalars
.
-
getFloat
default float getFloat()
Gets the value typed using the appropriate type conversion fromScalars
.- Returns:
- the value coerced to a float, or
NUMBER_DEF
if not a float - Since:
- 4.0.0
- See Also:
raw()
-
getFloat
default float getFloat(float def)
Gets the value typed using the appropriate type conversion fromScalars
.- Parameters:
def
- the default value if no appropriate value is set- Returns:
- the value coerced to a float, or
def
if not a float - Since:
- 4.0.0
- See Also:
raw()
-
getDouble
default double getDouble()
Gets the value typed using the appropriate type conversion fromScalars
.- Returns:
- the value coerced to a double, or
NUMBER_DEF
if coercion failed - Since:
- 4.0.0
- See Also:
raw()
-
getDouble
default double getDouble(double def)
Gets the value typed using the appropriate type conversion fromScalars
.- Parameters:
def
- the default value if no appropriate value is set- Returns:
- the value coerced to a double, or
def
if coercion failed - Since:
- 4.0.0
- See Also:
raw()
-
getInt
default int getInt()
Gets the value typed using the appropriate type conversion fromScalars
.- Returns:
- value coerced to an integer, or
NUMBER_DEF
if coercion failed. - Since:
- 4.0.0
- See Also:
raw()
-
getInt
default int getInt(int def)
Gets the value typed using the appropriate type conversion fromScalars
.- Parameters:
def
- the default value if no appropriate value is set- Returns:
- value coerced to an integer, or
def
if coercion failed. - Since:
- 4.0.0
- See Also:
raw()
-
getLong
default long getLong()
Gets the value typed using the appropriate type conversion fromScalars
.- Returns:
- value coerced to a long, or
NUMBER_DEF
if coercion failed - Since:
- 4.0.0
- See Also:
raw()
-
getLong
default long getLong(long def)
Gets the value typed using the appropriate type conversion fromScalars
.- Parameters:
def
- the default value if no appropriate value is set- Returns:
- value coerced to a long, or
def
if coercion failed - Since:
- 4.0.0
- See Also:
raw()
-
getBoolean
default boolean getBoolean()
Gets the value typed using the appropriate type conversion fromScalars
.- Returns:
- value coerced to a boolean, or false if coercion failed
- Since:
- 4.0.0
- See Also:
raw()
-
getBoolean
default boolean getBoolean(boolean def)
Gets the value typed using the appropriate type conversion fromScalars
.- Parameters:
def
- the default value if no appropriate value is set- Returns:
- value coerced to a boolean, or
def
if coercion failed - Since:
- 4.0.0
- See Also:
raw()
-
set
ConfigurationNode set(@Nullable Object value) throws SerializationException
Set this node's value to the given value.The value type will be taken from the provided value's class and used to determine a serializer. To set a value of a parameterized type, the parameters must be explicitly specified.
- Parameters:
value
- the value to set- Returns:
- this node
- Throws:
SerializationException
- Since:
- 4.0.0
-
set
<V> ConfigurationNode set(TypeToken<V> type, @Nullable V value) throws SerializationException
Set 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:
V
- the type to serialize to- Parameters:
type
- the type to use for serialization type informationvalue
- the value to set- Returns:
- this node
- Throws:
SerializationException
- if the value fails to be converted to the requested type. No change will be made to the node.- Since:
- 4.0.0
-
set
<V> ConfigurationNode set(Class<V> type, @Nullable V value) throws SerializationException
Set 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.This method will fail if a raw type (i.e. a parameterized type without its type parameters) is passed.
- Type Parameters:
V
- the type to serialize to- Parameters:
type
- the type to use for serialization type informationvalue
- the value to set- Returns:
- this node
- Throws:
IllegalArgumentException
- if a raw type is passedSerializationException
- if the value fails to be converted to the requested type. No change will be made to the node.- Since:
- 4.0.0
-
set
ConfigurationNode set(Type type, @Nullable Object value) throws SerializationException
Set 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.This method will fail if a raw type (i.e. a parameterized type without its type parameters) is passed.
Because this method accepts a non-parameterized
Type
parameter, it has no compile-time type checking. The variants that takeTypeToken
andset(Class, Object)
should be preferred where possible.- Parameters:
type
- the type to use for serialization type informationvalue
- the value to set- Returns:
- this node
- Throws:
IllegalArgumentException
- if a raw type is passedIllegalArgumentException
- ifvalue
is not eithernull
or of typetype
SerializationException
- if the value fails to be converted to the requested type. No change will be made to the node.- Since:
- 4.0.0
-
setList
default <V> ConfigurationNode setList(Class<V> elementType, @Nullable List<V> items) throws SerializationException
Set the node's value to the provided list.This method provides a helper for constructing the appropriate
Type
for serializing aList
- Type Parameters:
V
- list element type, theT
inList<T>
- Parameters:
elementType
- the type of the list elements. This must not be a raw type.items
- the list to serializer- Returns:
- this node
- Throws:
SerializationException
- if the value fails to be converted to the requested type.- Since:
- 4.0.0
- See Also:
for details on restrictions.
-
setList
default <V> ConfigurationNode setList(TypeToken<V> elementType, @Nullable List<V> items) throws SerializationException
Set the node's value to the provided list.This method provides a helper for constructing the appropriate
Type
for serializing aList
- Type Parameters:
V
- list element type, theT
inList<T>
- Parameters:
elementType
- the type of the list elements. This must not be a raw type.items
- the list to serializer- Returns:
- this node
- Throws:
SerializationException
- if the value fails to be converted to the requested type.- Since:
- 4.0.0
- See Also:
for details on restrictions.
-
raw
@Nullable Object raw()
Get the raw value of this node.The raw value is the plain value that will be passed to the loaders, without serialization except for unwrapping of maps and collections.
- Returns:
- this configuration's current value
- Since:
- 4.0.0
- See Also:
raw(Object)
-
raw
ConfigurationNode raw(@Nullable Object value)
Set the raw value of this node.The provided value must be of a type accepted by
ConfigurationOptions.acceptsType(Class)
. No other serialization will be performed.- Parameters:
value
- the value to set on this node- Returns:
- this node
- Since:
- 4.0.0
-
rawScalar
@Nullable Object rawScalar()
Get the raw value of this node if the node is a scalar.The raw value is the plain value that will be passed to the loaders, without serialization.
Map and list values will not be unboxed.
- Returns:
- this configuration's current value if it is a scalar, or else null.
- Since:
- 4.0.0
- See Also:
raw()
-
from
ConfigurationNode from(ConfigurationNode other)
Apply all data fromother
to this node, overwriting any existing data.- Parameters:
other
- source node- Returns:
- this node
- Since:
- 4.0.0
-
mergeFrom
ConfigurationNode mergeFrom(ConfigurationNode other)
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 node
- Since:
- 4.0.0
-
removeChild
boolean removeChild(Object key)
Removes a direct child of this node.- Parameters:
key
- the key of the node to remove- Returns:
- if a node was removed
- Since:
- 4.0.0
-
appendListNode
ConfigurationNode 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
- Since:
- 4.0.0
-
copy
ConfigurationNode 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
- Since:
- 4.0.0
-
visit
default <S,T,E extends Exception> T visit(ConfigurationVisitor<S,T,E> visitor) throws E extends Exception
Visit 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:
- returned terminal from the visitor
- Throws:
E
- when throw by visitor implementationE extends Exception
- Since:
- 4.0.0
-
visit
<S,T,E extends Exception> T visit(ConfigurationVisitor<S,T,E> visitor, S state) throws E extends Exception
Visit 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:
- returned terminal from the visitor
- Throws:
E
- when throw by visitor implementationE extends Exception
- Since:
- 4.0.0
-
visit
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.
- Type Parameters:
S
- the state typeT
- the terminal type- Parameters:
visitor
- the visitor- Returns:
- the returned terminal from the visitor
- Since:
- 4.0.0
-
visit
<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.
- 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
- Since:
- 4.0.0
-
hint
<V> ConfigurationNode hint(RepresentationHint<V> hint, @Nullable V value)
Set a representation hint on this node.Removing a hint from this node means the hint's value will be delegated to the node's parent. To explicitly revert to a hint's default, apply that default value.
- Type Parameters:
V
- hint value type- Parameters:
hint
- the hint to set a value forvalue
- value to set, or null to unset for self- Returns:
- this node
- Since:
- 4.0.0
-
hint
<V> @Nullable V hint(RepresentationHint<V> hint)
Query a representation hint from this node.If the hint is not set on this node, its parents will be recursively checked for a value.
- Type Parameters:
V
- value type- Parameters:
hint
- the hint to get- Returns:
- value of the hint, or
RepresentationHint.defaultValue()
- Since:
- 4.0.0
-
ownHint
<V> @Nullable V ownHint(RepresentationHint<V> hint)
Query a representation hint from this node.This will only check the current node, and return null rather than any default value.
- Type Parameters:
V
- value type- Parameters:
hint
- the hint to get- Returns:
- value of the hint, or
null
- Since:
- 4.0.0
-
ownHints
Map<RepresentationHint<?>,?> ownHints()
Get an unmodifiable copy of representation hints stored on this node.This does not include inherited hints.
- Returns:
- copy of hints this node has set.
- Since:
- 4.0.0
-
-