groovy.util

## Class Node

- java.lang.Object
- - groovy.util.Node

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

      public class Node
      extends java.lang.Object
      implements java.io.Serializable, java.lang.Cloneable

  Represents an arbitrary tree node which can be used for structured metadata or any arbitrary XML-like tree. A node can have a name, a value and an optional Map of attributes. Typically the name is a String and a value is either a String or a List of other Nodes, though the types are extensible to provide a flexible structure, e.g. you could use a QName as the name which includes a namespace URI and a local name. Or a JMX ObjectName etc. So this class can represent metadata like `{foo a=1 b="abc"}` or nested metadata like `{foo a=1 b="123" { bar x=12 text="hello" }}`
  Author:
    James Strachan, Paul King
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Node(Node parent, java.lang.Object name)` Creates a new Node named `name` and if a parent is supplied, adds the newly created node as a child of the parent.
    `Node(Node parent, java.lang.Object name, java.util.Map attributes)` Creates a new Node named `name` with attributes specified in the `attributes` Map.
    `Node(Node parent, java.lang.Object name, java.util.Map attributes, java.lang.Object value)` Creates a new Node named `name` with value `value` and with attributes specified in the `attributes` Map.
    `Node(Node parent, java.lang.Object name, java.lang.Object value)` Creates a new Node named `name` with value `value` and if a parent is supplied, adds the newly created node as a child of the parent.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `append(Node child)` Appends a child to the current node.
    `Node` | `appendNode(java.lang.Object name)` Creates a new node as a child of the current node.
    `Node` | `appendNode(java.lang.Object name, java.util.Map attributes)` Creates a new node as a child of the current node.
    `Node` | `appendNode(java.lang.Object name, java.util.Map attributes, java.lang.Object value)` Creates a new node as a child of the current node.
    `Node` | `appendNode(java.lang.Object name, java.lang.Object value)` Creates a new node as a child of the current node.
    `java.lang.Object` | `attribute(java.lang.Object key)` Provides lookup of attributes by key.
    `java.util.Map` | `attributes()` Returns a `Map` of the attributes of the node or an empty `Map` if the node does not have any attributes.
    `java.util.List` | `breadthFirst()` Provides a collection of all the nodes in the tree using a breadth-first traversal.
    `java.util.List` | `children()` Returns a `List` of the nodes children.
    `java.lang.Object` | `clone()` Creates a new Node with the same name, no parent, shallow cloned attributes and if the value is a NodeList, a (deep) clone of those nodes.
    `java.util.List` | `depthFirst()` Provides a collection of all the nodes in the tree using a depth first traversal.
    `java.lang.Object` | `get(java.lang.String key)` Provides lookup of elements by non-namespaced name
    `NodeList` | `getAt(QName name)` Provides lookup of elements by QName.
    `java.util.Iterator` | `iterator()` Returns an `Iterator` of the children of the node.
    `java.util.List<java.lang.String>` | `localText()` Returns the list of any direct String nodes of this node.
    `java.lang.Object` | `name()` Returns an `Object` representing the name of the node.
    `Node` | `parent()` Returns the parent of the node.
    `void` | `plus(Closure c)` Adds sibling nodes (defined using builder-style notation via a Closure) after the current node.
    `void` | `print(java.io.PrintWriter out)` Writes the node to the specified `PrintWriter`.
    `boolean` | `remove(Node child)` Removes a child of the current node.
    `Node` | `replaceNode(Closure c)` Replaces the current node with nodes defined using builder-style notation via a Closure.
    `Node` | `replaceNode(Node n)` Replaces the current node with the supplied node.
    `protected static void` | `setMetaClass(MetaClass metaClass, java.lang.Class nodeClass)` Extension point for subclasses to override the metaclass.
    `protected void` | `setParent(Node parent)` Adds or replaces the parent of the node.
    `void` | `setValue(java.lang.Object value)` Adds or replaces the value of the node.
    `java.lang.String` | `text()` Returns the textual representation of the current node and all its child nodes.
    `java.lang.String` | `toString()`
    `java.lang.Object` | `value()` Returns an `Object` representing the value of the node.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Node

          public Node(Node parent,
                      java.lang.Object name)

      Creates a new Node named `name` and if a parent is supplied, adds the newly created node as a child of the parent.
      Parameters:
        `parent` - the parent node or null if no parent
        `name` - the name of the node

    - #### Node

          public Node(Node parent,
                      java.lang.Object name,
                      java.lang.Object value)

      Creates a new Node named `name` with value `value` and if a parent is supplied, adds the newly created node as a child of the parent.
      Parameters:
        `parent` - the parent node or null if no parent
        `name` - the name of the node
        `value` - the Node value, e.g. some text but in general any Object

    - #### Node

          public Node(Node parent,
                      java.lang.Object name,
                      java.util.Map attributes)

      Creates a new Node named `name` with attributes specified in the `attributes` Map. If a parent is supplied, the newly created node is added as a child of the parent.
      Parameters:
        `parent` - the parent node or null if no parent
        `name` - the name of the node
        `attributes` - a Map of name-value pairs

    - #### Node

          public Node(Node parent,
                      java.lang.Object name,
                      java.util.Map attributes,
                      java.lang.Object value)

      Creates a new Node named `name` with value `value` and with attributes specified in the `attributes` Map. If a parent is supplied, the newly created node is added as a child of the parent.
      Parameters:
        `parent` - the parent node or null if no parent
        `name` - the name of the node
        `attributes` - a Map of name-value pairs
        `value` - the Node value, e.g. some text but in general any Object

  - ### Method Detail

    - #### clone

          public java.lang.Object clone()

      Creates a new Node with the same name, no parent, shallow cloned attributes and if the value is a NodeList, a (deep) clone of those nodes.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        the clone

    - #### append

          public boolean append(Node child)

      Appends a child to the current node.
      Parameters:
        `child` - the child to append
      Returns:
        `true`

    - #### remove

          public boolean remove(Node child)

      Removes a child of the current node.
      Parameters:
        `child` - the child to remove
      Returns:
        `true` if the param was a child of the current node

    - #### appendNode

          public Node appendNode(java.lang.Object name,
                                 java.util.Map attributes)

      Creates a new node as a child of the current node.
      Parameters:
        `name` - the name of the new node
        `attributes` - the attributes of the new node
      Returns:
        the newly created `Node`

    - #### appendNode

          public Node appendNode(java.lang.Object name)

      Creates a new node as a child of the current node.
      Parameters:
        `name` - the name of the new node
      Returns:
        the newly created `Node`

    - #### appendNode

          public Node appendNode(java.lang.Object name,
                                 java.lang.Object value)

      Creates a new node as a child of the current node.
      Parameters:
        `name` - the name of the new node
        `value` - the value of the new node
      Returns:
        the newly created `Node`

    - #### appendNode

          public Node appendNode(java.lang.Object name,
                                 java.util.Map attributes,
                                 java.lang.Object value)

      Creates a new node as a child of the current node.
      Parameters:
        `name` - the name of the new node
        `attributes` - the attributes of the new node
        `value` - the value of the new node
      Returns:
        the newly created `Node`

    - #### replaceNode

          public Node replaceNode(Closure c)

      Replaces the current node with nodes defined using builder-style notation via a Closure.
      Parameters:
        `c` - A Closure defining the new nodes using builder-style notation.
      Returns:
        the original now replaced node

    - #### replaceNode

          public Node replaceNode(Node n)

      Replaces the current node with the supplied node.
      Parameters:
        `n` - the new Node
      Returns:
        the original now replaced node

    - #### plus

          public void plus(Closure c)

      Adds sibling nodes (defined using builder-style notation via a Closure) after the current node.
      Parameters:
        `c` - A Closure defining the new sibling nodes to add using builder-style notation.

    - #### setMetaClass

          protected static void setMetaClass(MetaClass metaClass,
                                             java.lang.Class nodeClass)

      Extension point for subclasses to override the metaclass. The default one supports the property and @ attribute notations.
      Parameters:
        `metaClass` - the original metaclass
        `nodeClass` - the class whose metaclass we wish to override (this class or a subclass)

    - #### text

          public java.lang.String text()

      Returns the textual representation of the current node and all its child nodes.
      Returns:
        the text value of the node including child text

    - #### iterator

          public java.util.Iterator iterator()

      Returns an `Iterator` of the children of the node.
      Returns:
        the iterator of the nodes children

    - #### children

          public java.util.List children()

      Returns a `List` of the nodes children.
      Returns:
        the nodes children

    - #### attributes

          public java.util.Map attributes()

      Returns a `Map` of the attributes of the node or an empty `Map` if the node does not have any attributes.
      Returns:
        the attributes of the node

    - #### attribute

          public java.lang.Object attribute(java.lang.Object key)

      Provides lookup of attributes by key.
      Parameters:
        `key` - the key of interest
      Returns:
        the attribute matching the key or `null` if no match exists

    - #### name

          public java.lang.Object name()

      Returns an `Object` representing the name of the node.
      Returns:
        the name or `null` if name is empty

    - #### value

          public java.lang.Object value()

      Returns an `Object` representing the value of the node.
      Returns:
        the value or `null` if value is empty

    - #### setValue

          public void setValue(java.lang.Object value)

      Adds or replaces the value of the node.
      Parameters:
        `value` - the new value of the node

    - #### parent

          public Node parent()

      Returns the parent of the node.
      Returns:
        the parent or `null` for the root node

    - #### setParent

          protected void setParent(Node parent)

      Adds or replaces the parent of the node.
      Parameters:
        `parent` - the new parent of the node

    - #### get

          public java.lang.Object get(java.lang.String key)

      Provides lookup of elements by non-namespaced name
      Parameters:
        `key` - the name (or shortcut key) of the node(s) of interest
      Returns:
        the nodes which match key

    - #### getAt

          public NodeList getAt(QName name)

      Provides lookup of elements by QName.
      Parameters:
        `name` - the QName of interest
      Returns:
        the nodes matching name

    - #### depthFirst

          public java.util.List depthFirst()

      Provides a collection of all the nodes in the tree using a depth first traversal.
      Returns:
        the list of (depth-first) ordered nodes

    - #### breadthFirst

          public java.util.List breadthFirst()

      Provides a collection of all the nodes in the tree using a breadth-first traversal.
      Returns:
        the list of (breadth-first) ordered nodes

    - #### localText

          public java.util.List<java.lang.String> localText()

      Returns the list of any direct String nodes of this node.
      Returns:
        the list of String values from this node
      Since:
        2.3.0

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### print

          public void print(java.io.PrintWriter out)

      Writes the node to the specified `PrintWriter`.
      Parameters:
        `out` - the writer receiving the output