Package org.apache.commons.configuration2.tree

# Class ImmutableNode

java.lang.Object
org.apache.commons.configuration2.tree.ImmutableNode

All Implemented Interfaces:
  `Iterable<ImmutableNode>`

public final class ImmutableNode extends Object implements 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 final class`
  `ImmutableNode.Builder`
  A builder class for creating instances of `ImmutableNode`.

- ## Method Summary

  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.
  `Map<String,Object>`
  `getAttributes()`
  Gets a map with the attributes of this node.
  `List<ImmutableNode>`
  `getChildren()`
  Gets a list with the children of this node.
  `List<ImmutableNode>`
  `getChildren(String name)`
  Returns a list with the children of this node.
  `String`
  `getNodeName()`
  Gets the name of this node.
  `Object`
  `getValue()`
  Gets the value of this node.
  `Iterator<ImmutableNode>`
  `iterator()`
  `ImmutableNode`
  `removeAttribute(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(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(String name, 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(Map<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(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(Object newValue)`
  Creates a new `ImmutableNode` instance which is a copy of this object with the value changed to the passed in value.
  `Stream<ImmutableNode>`
  `stream()`
  Returns a sequential `Stream` with this node as its source.
  `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`

- ## Method Details

  - ### 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:
      `IllegalArgumentException` - if the child node is null

  - ### getAttributes

    public Map<String,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 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 List<ImmutableNode> getChildren(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 String getNodeName()
    Gets the name of this node.
    Returns:
      the name of this node

  - ### getValue

    public Object getValue()
    Gets the value of this node.
    Returns:
      the value of this node

  - ### iterator

    public Iterator<ImmutableNode> iterator()
    Specified by:
      `iterator` in interface `Iterable<ImmutableNode>`
    Returns:
      An iterator of `child nodes.`
    Since:
      2.8.0

  - ### removeAttribute

    public ImmutableNode removeAttribute(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:
      `IllegalArgumentException` - if the new child node is null

  - ### replaceChildren

    public ImmutableNode replaceChildren(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(String name, 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(Map<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(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(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 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 String toString()
    Overrides:
      `toString` in class `Object`