Package ninja.leaping.configurate

Interface ConfigurationNode

All Known Subinterfaces:
AttributedConfigurationNode, CommentedConfigurationNode
All Known Implementing Classes:
SimpleAttributedConfigurationNode, SimpleCommentedConfigurationNode, SimpleConfigurationNode
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.

ConfigurationNodes can hold different types of values. They can:

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 Details

  • Method Details

    • root

      static @NonNull ConfigurationNode root()

    • root

      static @NonNull ConfigurationNode root​(Consumer<ConfigurationNode> action)

    • root

      static @NonNull ConfigurationNode root​(@NonNull ConfigurationOptions options)

    • root

      static @NonNull ConfigurationNode root​(@NonNull ConfigurationOptions options, Consumer<ConfigurationNode> action)

    • getKey

      @Nullable Object getKey()
      Gets the "key" of this node.

      The key determines this ConfigurationNodes 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 ConfigurationNodes returned as values from getChildrenMap() will have keys derived from their pairing in the map node.

      The ConfigurationNodes returned from getChildrenList() will have keys derived from their position (index) in the list node.

      Returns:
      The key of this node

    • getPath

      @NonNull Object[] getPath()
      Gets the full path of keys 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

      @Nullable ConfigurationNode 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

      @NonNull ConfigurationNode getNode​(@NonNull Object @NonNull ... 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 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

      default @NonNull ConfigurationNode getNode​(@NonNull 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 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

      @NonNull ConfigurationOptions getOptions()
      Gets the options that currently apply to this node
      Returns:
      The ConfigurationOptions instance that governs the functionality of this node

    • getValueType

      @Deprecated @NonNull ValueType getValueType()
      Deprecated.
      Use isList() and isMap() for the same information
      Gets the value type of this node.
      Returns:
      The value type

    • isList

      default boolean isList()
      Gets if this node has "list children".
      Returns:
      if this node has children in the form of a list

    • isMap

      default boolean isMap()
      Gets if this node has "map children".
      Returns:
      if this node has children in the form of a map

    • hasListChildren

      @Deprecated default boolean hasListChildren()
      Deprecated.
      Use isList() instead
      Gets if this node has "list children".
      Returns:
      if this node has children in the form of a list

    • hasMapChildren

      @Deprecated default boolean hasMapChildren()
      Deprecated.
      Use isMap() instead
      Gets if this node has "map children"
      Returns:
      if this node has children in the form of a map

    • isEmpty

      default boolean 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
      This is a distinct value from 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

      default @Nullable 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.

      Returns:
      This configuration's current value, or null if there is none
      See Also:
      getValue(Object)

    • getValue

      Object getValue​(@Nullable Object def)
      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

      Object getValue​(@NonNull Supplier<Object> defSupplier)
      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

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

      <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.
      Type Parameters:
      T - The expected type
      Parameters:
      transformer - The transformation function
      def - 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

      <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.
      Type Parameters:
      T - The expected type
      Parameters:
      transformer - The transformation function
      defSupplier - 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

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

      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

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

      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
      def - 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 function
      defSupplier - 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

      default <T> @NonNull List<T> getList​(@NonNull TypeToken<T> type) throws ObjectMappingException
      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 ObjectMappingException
      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
      def - 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 ObjectMappingException
      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
      defSupplier - 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

      default @Nullable String getString()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, null if no appropriate value is available
      See Also:
      getValue()

    • getString

      default String getString​(@Nullable String def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default float getFloat()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, 0 if no appropriate value is available
      See Also:
      getValue()

    • getFloat

      default float getFloat​(float def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default double getDouble()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, 0 if no appropriate value is available
      See Also:
      getValue()

    • getDouble

      default double getDouble​(double def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default int getInt()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, 0 if no appropriate value is available
      See Also:
      getValue()

    • getInt

      default int getInt​(int def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default long getLong()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, 0 if no appropriate value is available
      See Also:
      getValue()

    • getLong

      default long getLong​(long def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default boolean getBoolean()
      Gets the value typed using the appropriate type conversion from Types
      Returns:
      The appropriate type conversion, false if no appropriate value is available
      See Also:
      getValue()

    • getBoolean

      default boolean getBoolean​(boolean def)
      Gets the value typed using the appropriate type conversion from Types
      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

      default <T> @Nullable T getValue​(@NonNull TypeToken<T> type) throws ObjectMappingException
      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

      <T> T getValue​(@NonNull TypeToken<T> type, T def) throws ObjectMappingException
      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
      def - 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 ObjectMappingException
      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
      defSupplier - 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

      @NonNull ConfigurationNode setValue​(@Nullable Object value)
      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 only accepts native types as values. If the type of a value is unknown at runtime, 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 ObjectMappingException
      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.

      Type Parameters:
      T - The type to serialize to
      Parameters:
      type - The type to use for serialization type information
      value - 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

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

      Map keys will be merged. Lists and scalar values will be replaced.

      Parameters:
      other - The node to merge values from
      Returns:
      this

    • removeChild

      boolean removeChild​(@NonNull Object key)
      Removes a direct child of this node
      Parameters:
      key - The key of the node to remove
      Returns:
      If a node was removed

    • getAppendedNode

      @Deprecated @NonNull ConfigurationNode getAppendedNode()
      Deprecated.
      Use appendListNode() instead
      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

    • appendListNode

      default @NonNull 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

    • copy

      @NonNull 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

    • act

      default ConfigurationNode act​(Consumer<? super ConfigurationNode> action)
      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 Exception
      Visit this node hierarchy as described in ConfigurationVisitor
      Type Parameters:
      S - The state type
      T - The terminal type
      E - 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 Exception
      Visit this node hierarchy as described in ConfigurationVisitor
      Type Parameters:
      T - The terminal type
      S - The state type
      E - exception type that may be thrown
      Parameters:
      visitor - The visitor
      state - The state to start with
      Returns:
      The returned terminal from the visitor
      Throws:
      E - when throw by visitor implementation

    • visit

      default <S,​ T> T visit​(ConfigurationVisitor.Safe<S,​T> visitor)
      Visit this node hierarchy as described in ConfigurationVisitor This overload will remove the need for exception handling for visitors that do not have any checked exceptions.
      Type Parameters:
      S - The state type
      T - The terminal type
      Parameters:
      visitor - The visitor
      Returns:
      The returned terminal from the visitor

    • visit

      default <S,​ T> T visit​(ConfigurationVisitor.Safe<S,​T> visitor, S state)
      Visit this node hierarchy as described in ConfigurationVisitor This overload will remove the need for exception handling for visitors that do not have any checked exceptions.
      Type Parameters:
      T - The terminal type
      S - The state type
      Parameters:
      visitor - The visitor
      state - The state to start with
      Returns:
      The returned terminal from the visitor