Package ninja.leaping.configurate

Interface ConfigurationNode

    • Method Detail

      • 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

      • 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

      • 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

      • 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

        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

      • 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
        E extends Exception

      • 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
        E extends Exception

      • 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