Interface ScopedConfigurationNode<N extends ScopedConfigurationNode<N>>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default <E extends java.lang.Exception>
      N
      act​(CheckedConsumer<? super N,​E> action)
      Execute an action on this node.
      N appendListNode()
      Gets a new child node created as the next entry in the list.
      java.util.List<N> childrenList()
      Gets the "list children" attached to this node, if it has any.
      java.util.Map<java.lang.Object,​N> childrenMap()
      Gets the "map children" attached to this node, if it has any.
      N copy()
      Creates a deep copy of this node.
      N from​(ConfigurationNode other)
      Apply all data from other to this node, overwriting any existing data.
      <V> N hint​(RepresentationHint<V> hint, @Nullable V value)
      Set a representation hint on this node.
      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.
      N node​(java.lang.Iterable<?> path)
      Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.
      N node​(java.lang.Object... path)
      Gets the node at the given (relative) path, possibly traversing multiple levels of nodes.
      @Nullable N parent()
      Gets the parent of this node.
      N raw​(@Nullable java.lang.Object value)
      Set the raw value of this node.
      N self()
      Get a correctly typed instance of this node.
      N set​(@Nullable java.lang.Object value)
      Set this node's value to the given value.
      default <V> N set​(io.leangen.geantyref.TypeToken<V> type, @Nullable V value)
      Set this node's value to the given value.
      default <V> N set​(java.lang.Class<V> type, @Nullable V value)
      Set this node's value to the given value.
      default N set​(java.lang.reflect.AnnotatedType type, @Nullable java.lang.Object value)
      Set this node's value to the given value.
      default N set​(java.lang.reflect.Type type, @Nullable java.lang.Object value)
      Set this node's value to the given value.
      default <V> N setList​(io.leangen.geantyref.TypeToken<V> elementType, @Nullable java.util.List<V> items)
      Set the node's value to the provided list.
      default <V> N setList​(java.lang.Class<V> elementType, @Nullable java.util.List<V> items)
      Set the node's value to the provided list.
      default <V> java.util.stream.Collector<V,​N,​N> toListCollector​(io.leangen.geantyref.TypeToken<V> valueType)
      Create a collector that appends values to this node as list children.
      default <V> java.util.stream.Collector<V,​N,​N> toListCollector​(java.lang.Class<V> valueType)
      Create a collector that appends values to this node as list children.
      default <V> java.util.stream.Collector<java.util.Map.Entry<?,​V>,​N,​N> toMapCollector​(io.leangen.geantyref.TypeToken<V> valueType)
      Create a collector that appends values to this node as map children.
      default <V> java.util.stream.Collector<java.util.Map.Entry<?,​V>,​N,​N> toMapCollector​(java.lang.Class<V> valueType)
      Create a collector that appends values to this node as map children.
    • Method Detail

      • 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​(java.lang.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​(java.lang.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 java.lang.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​(java.lang.reflect.Type type,
                      @Nullable java.lang.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​(java.lang.reflect.AnnotatedType type,
                      @Nullable java.lang.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​(java.lang.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​(java.lang.Class<V> elementType,
                              @Nullable java.util.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:
        for details on restrictions.
      • setList

        default <V> N setList​(io.leangen.geantyref.TypeToken<V> elementType,
                              @Nullable java.util.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:
        for details on restrictions.
      • raw

        N raw​(@Nullable java.lang.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
      • childrenMap

        java.util.Map<java.lang.Object,​NchildrenMap()
        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> java.util.stream.Collector<java.util.Map.Entry<?,​V>,​N,​NtoMapCollector​(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> java.util.stream.Collector<java.util.Map.Entry<?,​V>,​N,​NtoMapCollector​(java.lang.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> java.util.stream.Collector<V,​N,​NtoListCollector​(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> java.util.stream.Collector<V,​N,​NtoListCollector​(java.lang.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 java.lang.Exception> N act​(CheckedConsumer<? super N,​E> action)
                                               throws E extends java.lang.Exception
        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
        E extends java.lang.Exception
        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