Class ImmutableNode

  • All Implemented Interfaces:
    java.lang.Iterable<ImmutableNode>

    public final class ImmutableNode
    extends java.lang.Object
    implements java.lang.Iterable<ImmutableNode>

    An immutable default implementation for configuration nodes.

    This class is used for an in-memory representation of hierarchical configuration data. It stores typical information like a node name, a value, child nodes, or attributes.

    After their creation, instances cannot be manipulated. There are methods for updating properties, but these methods return new ImmutableNode instances. Instances are created using the nested Builder class.

    Since:
    2.0
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ImmutableNode.Builder
      A builder class for creating instances of ImmutableNode.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.Map<java.lang.String,​java.lang.Object> attributes
      A map with the attributes of this node.
      private java.util.List<ImmutableNode> children
      A collection with the child nodes of this node.
      private java.lang.String nodeName
      The name of this node.
      private java.lang.Object value
      The value of this node.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ImmutableNode​(ImmutableNode.Builder b)
      Creates a new instance of ImmutableNode from the given Builder object.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ImmutableNode addChild​(ImmutableNode child)
      Creates a new ImmutableNode instance which is a copy of this object, but has the given child node added.
      private static void checkChildNode​(ImmutableNode child)
      Checks whether the given child node is not null.
      private ImmutableNode createWithBasicProperties​(ImmutableNode.Builder builder)
      Initializes the given builder with basic properties (node name and value) and returns the newly created node.
      private ImmutableNode createWithNewAttributes​(java.util.Map<java.lang.String,​java.lang.Object> newAttrs)
      Creates a new ImmutableNode instance with the same properties as this object, but with the given new attributes.
      java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
      Gets a map with the attributes of this node.
      java.util.List<ImmutableNode> getChildren()
      Gets a list with the children of this node.
      java.util.List<ImmutableNode> getChildren​(java.lang.String name)
      Returns a list with the children of this node.
      java.lang.String getNodeName()
      Gets the name of this node.
      java.lang.Object getValue()
      Gets the value of this node.
      java.util.Iterator<ImmutableNode> iterator()  
      ImmutableNode removeAttribute​(java.lang.String name)
      Returns a new ImmutableNode instance which is a copy of this object, but with the specified attribute removed.
      ImmutableNode removeChild​(ImmutableNode child)
      Returns a new ImmutableNode instance which is a copy of this object, but with the given child node removed.
      ImmutableNode replaceChild​(ImmutableNode oldChild, ImmutableNode newChild)
      Returns a new ImmutableNode instance which is a copy of this object, but with the given child replaced by the new one.
      ImmutableNode replaceChildren​(java.util.Collection<ImmutableNode> newChildren)
      Returns a new ImmutableNode instance which is a copy of this object, but with the children replaced by the ones in the passed in collection.
      ImmutableNode setAttribute​(java.lang.String name, java.lang.Object value)
      Returns a new ImmutableNode instance which is a copy of this object, but with the specified attribute set to the given value.
      ImmutableNode setAttributes​(java.util.Map<java.lang.String,​?> newAttributes)
      Returns a new ImmutableNode instance which is a copy of this object, but with all attributes added defined by the given map.
      ImmutableNode setName​(java.lang.String name)
      Creates a new ImmutableNode instance which is a copy of this object with the name changed to the passed in value.
      ImmutableNode setValue​(java.lang.Object newValue)
      Creates a new ImmutableNode instance which is a copy of this object with the value changed to the passed in value.
      java.util.stream.Stream<ImmutableNode> stream()
      Returns a sequential Stream with this node as its source.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Field Detail

      • nodeName

        private final java.lang.String nodeName
        The name of this node.
      • value

        private final java.lang.Object value
        The value of this node.
      • children

        private final java.util.List<ImmutableNode> children
        A collection with the child nodes of this node.
      • attributes

        private final java.util.Map<java.lang.String,​java.lang.Object> attributes
        A map with the attributes of this node.
    • Constructor Detail

      • ImmutableNode

        private ImmutableNode​(ImmutableNode.Builder b)
        Creates a new instance of ImmutableNode from the given Builder object.
        Parameters:
        b - the Builder
    • Method Detail

      • checkChildNode

        private static void checkChildNode​(ImmutableNode child)
        Checks whether the given child node is not null. This check is done at multiple places to ensure that newly added child nodes are always defined.
        Parameters:
        child - the child node to be checked
        Throws:
        java.lang.IllegalArgumentException - if the child node is null
      • addChild

        public ImmutableNode addChild​(ImmutableNode child)
        Creates a new ImmutableNode instance which is a copy of this object, but has the given child node added.
        Parameters:
        child - the child node to be added (must not be null)
        Returns:
        the new node with the child node added
        Throws:
        java.lang.IllegalArgumentException - if the child node is null
      • createWithBasicProperties

        private ImmutableNode createWithBasicProperties​(ImmutableNode.Builder builder)
        Initializes the given builder with basic properties (node name and value) and returns the newly created node. This is a helper method for updating a node when only children or attributes are affected.
        Parameters:
        builder - the already prepared builder
        Returns:
        the newly created node
      • createWithNewAttributes

        private ImmutableNode createWithNewAttributes​(java.util.Map<java.lang.String,​java.lang.Object> newAttrs)
        Creates a new ImmutableNode instance with the same properties as this object, but with the given new attributes.
        Parameters:
        newAttrs - the new attributes
        Returns:
        the new node instance
      • getAttributes

        public java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
        Gets a map with the attributes of this node. This map cannot be modified.
        Returns:
        a map with this node's attributes
      • getChildren

        public java.util.List<ImmutableNode> getChildren()
        Gets a list with the children of this node. This list cannot be modified.
        Returns:
        a list with the child nodes
      • getChildren

        public java.util.List<ImmutableNode> getChildren​(java.lang.String name)
        Returns a list with the children of this node.
        Parameters:
        name - the node name to find
        Returns:
        a list with the child nodes
      • getNodeName

        public java.lang.String getNodeName()
        Gets the name of this node.
        Returns:
        the name of this node
      • getValue

        public java.lang.Object getValue()
        Gets the value of this node.
        Returns:
        the value of this node
      • removeAttribute

        public ImmutableNode removeAttribute​(java.lang.String name)
        Returns a new ImmutableNode instance which is a copy of this object, but with the specified attribute removed. If there is no attribute with the given name, the same node instance is returned.
        Parameters:
        name - the name of the attribute
        Returns:
        the new node without this attribute
      • removeChild

        public ImmutableNode removeChild​(ImmutableNode child)
        Returns a new ImmutableNode instance which is a copy of this object, but with the given child node removed. If the child node does not belong to this node, the same node instance is returned.
        Parameters:
        child - the child node to be removed
        Returns:
        the new node with the child node removed
      • replaceChild

        public ImmutableNode replaceChild​(ImmutableNode oldChild,
                                          ImmutableNode newChild)
        Returns a new ImmutableNode instance which is a copy of this object, but with the given child replaced by the new one. If the child to be replaced cannot be found, the same node instance is returned.
        Parameters:
        oldChild - the child node to be replaced
        newChild - the replacing child node (must not be null)
        Returns:
        the new node with the child replaced
        Throws:
        java.lang.IllegalArgumentException - if the new child node is null
      • replaceChildren

        public ImmutableNode replaceChildren​(java.util.Collection<ImmutableNode> newChildren)
        Returns a new ImmutableNode instance which is a copy of this object, but with the children replaced by the ones in the passed in collection. With this method all children can be replaced in a single step. For the collection the same rules apply as for ImmutableNode.Builder.addChildren(Collection).
        Parameters:
        newChildren - the collection with the new children (may be null)
        Returns:
        the new node with replaced children
      • setAttribute

        public ImmutableNode setAttribute​(java.lang.String name,
                                          java.lang.Object value)
        Returns a new ImmutableNode instance which is a copy of this object, but with the specified attribute set to the given value. If an attribute with this name does not exist, it is created now. Otherwise, the new value overrides the old one.
        Parameters:
        name - the name of the attribute
        value - the attribute value
        Returns:
        the new node with this attribute
      • setAttributes

        public ImmutableNode setAttributes​(java.util.Map<java.lang.String,​?> newAttributes)
        Returns a new ImmutableNode instance which is a copy of this object, but with all attributes added defined by the given map. This method is analogous to setAttribute(String, Object), but all attributes in the given map are added. If the map is null or empty, this method has no effect.
        Parameters:
        newAttributes - the map with attributes to be added
        Returns:
        the new node with these attributes
      • setName

        public ImmutableNode setName​(java.lang.String name)
        Creates a new ImmutableNode instance which is a copy of this object with the name changed to the passed in value.
        Parameters:
        name - the name of the newly created node
        Returns:
        the new node with the changed name
      • setValue

        public ImmutableNode setValue​(java.lang.Object newValue)
        Creates a new ImmutableNode instance which is a copy of this object with the value changed to the passed in value.
        Parameters:
        newValue - the value of the newly created node
        Returns:
        the new node with the changed value
      • stream

        public java.util.stream.Stream<ImmutableNode> stream()
        Returns a sequential Stream with this node as its source.
        Returns:
        a sequential Stream over the elements in this node.
        Since:
        2.9.0
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object