Package org.spongepowered.configurate

Interface ScopedConfigurationNode<N extends ScopedConfigurationNode<N>>

Type Parameters:
N - self type
All Superinterfaces:
ConfigurationNode
All Known Subinterfaces:
AttributedConfigurationNode, BasicConfigurationNode, CommentedConfigurationNode, CommentedConfigurationNodeIntermediary<N>
public interface ScopedConfigurationNode<N extends ScopedConfigurationNode<N>> extends ConfigurationNode
Intermediate node type to reduce need for casting.

Any methods that return ConfigurationNode in ConfigurationNode should be overridden to return the N self-type instead.

Since:
4.0.0

  • Method Details

    • self

      N self()
      Get a correctly typed instance of this node.
      Returns:
      the node type
      Since:
      4.0.0

    • appendListNode

      N appendListNode()
      Gets a new child node created as the next entry in the list.
      Specified by:
      appendListNode in interface ConfigurationNode
      Returns:
      a new child created as the next entry in the list when it is attached

    • copy

      N 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).

      Specified by:
      copy in interface ConfigurationNode
      Returns:
      a copy of this node

    • node

      N 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.

      Specified by:
      node in interface ConfigurationNode
      Parameters:
      path - the path to fetch the node at
      Returns:
      the node at the given path, possibly virtual

    • node

      N 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.

      Specified by:
      node in interface ConfigurationNode
      Parameters:
      path - the path to fetch the node at
      Returns:
      the node at the given path, possibly virtual

    • parent

      @Nullable N parent()
      Gets the parent of this node.

      If this node is currently virtual, this method's result may be inaccurate.

      Specified by:
      parent in interface ConfigurationNode
      Returns:
      the nodes parent

    • from

      N from(ConfigurationNode other)
      Apply all data from other to this node, overwriting any existing data.
      Specified by:
      from in interface ConfigurationNode
      Parameters:
      other - source node
      Returns:
      this node

    • mergeFrom

      N 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.

      Specified by:
      mergeFrom in interface ConfigurationNode
      Parameters:
      other - the node to merge values from
      Returns:
      this node

    • set

      N 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.

      Specified by:
      set in interface ConfigurationNode
      Parameters:
      value - the value to set
      Returns:
      this node
      Throws:
      SerializationException

    • set

      default N 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 a Map, 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 take TypeToken and ConfigurationNode.set(Class, Object) should be preferred where possible.

      Specified by:
      set in interface ConfigurationNode
      Parameters:
      type - the type to use for serialization type information
      value - 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.

    • set

      default N set(AnnotatedType type, @Nullable Object value) throws SerializationException
      Set this node's value to the given value.

      If the provided value is a Collection or a Map, 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 take TypeToken and ConfigurationNode.set(Class, Object) should be preferred where possible.

      Specified by:
      set in interface ConfigurationNode
      Parameters:
      type - the annotated type to use for serialization type information
      value - 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.

    • set

      default <V> N set(Class<V> type, @Nullable V value) throws SerializationException
      Description copied from interface: ConfigurationNode
      Set this node's value to the given value.

      If the provided value is a Collection or a Map, 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.

      Specified by:
      set in interface ConfigurationNode
      Type Parameters:
      V - the type to serialize to
      Parameters:
      type - the type to use for serialization type information
      value - 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.

    • set

      default <V> N set(io.leangen.geantyref.TypeToken<V> type, @Nullable V value) throws SerializationException
      Description copied from interface: ConfigurationNode
      Set this node's value to the given value.

      If the provided value is a Collection or a Map, 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.

      Specified by:
      set in interface ConfigurationNode
      Type Parameters:
      V - the type to serialize to
      Parameters:
      type - the type to use for serialization type information
      value - 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.

    • setList

      default <V> N setList(Class<V> elementType, @Nullable List<V> items) throws SerializationException
      Description copied from interface: ConfigurationNode
      Set the node's value to the provided list.

      This method provides a helper for constructing the appropriate Type for serializing a List

      Specified by:
      setList in interface ConfigurationNode
      Type Parameters:
      V - list element type, the T in List<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.
      See Also:

    • setList

      default <V> N setList(io.leangen.geantyref.TypeToken<V> elementType, @Nullable List<V> items) throws SerializationException
      Description copied from interface: ConfigurationNode
      Set the node's value to the provided list.

      This method provides a helper for constructing the appropriate Type for serializing a List

      Specified by:
      setList in interface ConfigurationNode
      Type Parameters:
      V - list element type, the T in List<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.
      See Also:

    • raw

      N 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.

      Specified by:
      raw in interface ConfigurationNode
      Parameters:
      value - the value to set on this node
      Returns:
      this node

    • childrenList

      List<N> 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.

      Specified by:
      childrenList in interface ConfigurationNode
      Returns:
      the list children currently attached to this node

    • childrenMap

      Map<Object,N> 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.

      Specified by:
      childrenMap in interface ConfigurationNode
      Returns:
      the map children currently attached to this node

    • toMapCollector

      default <V> Collector<Map.Entry<?,V>,N,N> toMapCollector(io.leangen.geantyref.TypeToken<V> valueType)
      Create a collector that appends values to this node as map children.

      This collector does not accept values in parallel.

      Specified by:
      toMapCollector in interface ConfigurationNode
      Type Parameters:
      V - value type
      Parameters:
      valueType - marker for value type
      Returns:
      a new collector

    • toMapCollector

      default <V> Collector<Map.Entry<?,V>,N,N> toMapCollector(Class<V> valueType)
      Create a collector that appends values to this node as map children.

      This collector does not accept values in parallel.

      Specified by:
      toMapCollector in interface ConfigurationNode
      Type Parameters:
      V - value type
      Parameters:
      valueType - marker for value type
      Returns:
      a new collector

    • toListCollector

      default <V> Collector<V,N,N> toListCollector(io.leangen.geantyref.TypeToken<V> valueType)
      Create a collector that appends values to this node as list children.

      This collector does not accept values in parallel.

      Specified by:
      toListCollector in interface ConfigurationNode
      Type Parameters:
      V - value type
      Parameters:
      valueType - marker for value type
      Returns:
      a new collector

    • toListCollector

      default <V> Collector<V,N,N> toListCollector(Class<V> valueType)
      Create a collector that appends values to this node as list children.

      This collector does not accept values in parallel.

      Specified by:
      toListCollector in interface ConfigurationNode
      Type Parameters:
      V - value type
      Parameters:
      valueType - marker for value type
      Returns:
      a new collector

    • act

      default <E extends Exception> N act(CheckedConsumer<? super N,E> action) throws E
      Execute an action on this node. This allows performing multiple operations on a single node without having to clutter up the surrounding scope.
      Type Parameters:
      E - thrown type
      Parameters:
      action - the action to perform on this node
      Returns:
      this node
      Throws:
      E - when thrown by callback action
      Since:
      4.0.0

    • hint

      <V> N hint(RepresentationHint<V> hint, @Nullable V value)
      Description copied from interface: ConfigurationNode
      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.

      Specified by:
      hint in interface ConfigurationNode
      Type Parameters:
      V - hint value type
      Parameters:
      hint - the hint to set a value for
      value - value to set, or null to unset for self
      Returns:
      this node