Package: groovy.util

## [Java] Class Node

- groovy.util.Node

- All Implemented Interfaces and Traits:
    Serializable, Cloneable

      public class Node
      extends Object
      implements Serializable, 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" }}`

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static String` | `TEXT_KEY` | The key used for text content when a node has both attributes and text.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `Node(Node parent, 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, Object name, 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.
    `Node(Node parent, Object name, Map attributes)` Creates a new Node named `name` with attributes specified in the `attributes` Map.
    `Node(Node parent, Object name, Map attributes, Object value)` Creates a new Node named `name` with value `value` and with attributes specified in the `attributes` Map.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `append(Node child)` Appends a child to the current node.
    `` | `public Node` | `appendNode(Object name, Map attributes)` Creates a new node as a child of the current node.
    `` | `public Node` | `appendNode(Object name)` Creates a new node as a child of the current node.
    `` | `public Node` | `appendNode(Object name, Object value)` Creates a new node as a child of the current node.
    `` | `public Node` | `appendNode(Object name, Map attributes, Object value)` Creates a new node as a child of the current node.
    `` | `public Object` | `attribute(Object key)` Provides lookup of attributes by key.
    `` | `public Map` | `attributes()` Returns a `Map` of the attributes of the node or an empty `Map` if the node does not have any attributes.
    `` | `public List` | `breadthFirst()` Provides a collection of all the nodes in the tree using a breadth-first preorder traversal.
    `` | `public List` | `breadthFirst(boolean preorder)` Provides a collection of all the nodes in the tree using a breadth-first traversal.
    `` | `public void` | `breadthFirst(Closure c)` Calls the provided closure for all the nodes in the tree using a breadth-first preorder traversal.
    `` | `public void` | `breadthFirst(Map<String, Object> options, Closure c)` Calls the provided closure for all the nodes in the tree using a breadth-first traversal.
    `` | `public List` | `children()` Returns a `List` of the nodes children.
    `` | `public 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.
    `` | `public List` | `depthFirst()` Provides a collection of all the nodes in the tree using a depth-first preorder traversal.
    `` | `public List` | `depthFirst(boolean preorder)` Provides a collection of all the nodes in the tree using a depth-first traversal.
    `` | `public void` | `depthFirst(Closure c)` Provides a collection of all the nodes in the tree using a depth-first preorder traversal.
    `` | `public void` | `depthFirst(Map<String, Object> options, Closure c)` Provides a collection of all the nodes in the tree using a depth-first traversal.
    `` | `public Object` | `get(String key)` Provides lookup of elements by non-namespaced name
    `` | `public NodeList` | `getAt(QName name)` Provides lookup of elements by QName.
    `` | `public Iterator` | `iterator()` Returns an `Iterator` of the children of the node.
    `` | `public List<String>` | `localText()` Returns the list of any direct String nodes of this node.
    `` | `public Object` | `name()` Returns an `Object` representing the name of the node.
    `` | `public Node` | `parent()` Returns the parent of the node.
    `` | `public void` | `plus(Closure c)` Adds sibling nodes (defined using builder-style notation via a Closure) after the current node.
    `` | `public void` | `print(PrintWriter out)` Writes the node to the specified `PrintWriter`.
    `` | `public boolean` | `remove(Node child)` Removes a child of the current node.
    `` | `public Node` | `replaceNode(Closure c)` Replaces the current node with nodes defined using builder-style notation via a Closure.
    `` | `public Node` | `replaceNode(Node n)` Replaces the current node with the supplied node.
    `` | `protected static void` | `setMetaClass(MetaClass metaClass, Class nodeClass)` Extension point for subclasses to override the metaclass.
    `` | `protected void` | `setParent(Node parent)` Adds or replaces the parent of the node.
    `` | `public void` | `setValue(Object value)` Adds or replaces the value of the node.
    `` | `public String` | `text()` Returns the textual representation of the current node and all its child nodes.
    `` | `public BigDecimal` | `toBigDecimal()` Converts the text of this GPathResult to a BigDecimal object.
    `` | `public BigInteger` | `toBigInteger()` Converts the text of this GPathResult to a BigInteger object.
    `` | `public Double` | `toDouble()` Converts the text of this GPathResult to a Double object.
    `` | `public Float` | `toFloat()` Converts the text of this GPathResult to a Float object.
    `` | `public Integer` | `toInteger()` Converts the text of this GPathResult to an Integer object.
    `` | `public Long` | `toLong()` Converts the text of this GPathResult to a Long object.
    `` | `public Map<String, Object>` | `toMap()` Converts this Node tree into a nested `Map<String, Object>`.
      > `` | `public String` | `toString()` Returns a string representation of the object. API Note: In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The string output is not necessarily stable over time or across JVM invocations. Implementation Requirements: The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
      >     getClass().getName() + '@' + Integer.toHexString(hashCode())
    Returns: a string representation of the object.
    `` | `public Object` | `value()` Returns an `Object` representing the value of the node.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### public static final String TEXT_KEY

      The key used for text content when a node has both attributes and text.

      Since:
        6.0.0

  - ### Constructor Detail

    - #### public Node(Node parent, 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

    - #### public Node(Node parent, Object name, 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

    - #### public Node(Node parent, Object name, 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

    - #### public Node(Node parent, Object name, Map attributes, 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

    - #### public boolean append(Node child)

      Appends a child to the current node.

      Parameters:
        `child` - the child to append
      Returns:
        `true`

    - #### public Node appendNode(Object name, 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`

    - #### public Node appendNode(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`

    - #### public Node appendNode(Object name, 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`

    - #### public Node appendNode(Object name, Map attributes, 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`

    - #### public Object attribute(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

    - #### public 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

    - #### public List breadthFirst()

      Provides a collection of all the nodes in the tree using a breadth-first preorder traversal.

      Returns:
        the list of (breadth-first) ordered nodes

    - #### public List breadthFirst(boolean preorder)

      Provides a collection of all the nodes in the tree using a breadth-first traversal.

      Parameters:
        `preorder` - if false, a postorder breadth-first traversal will be performed
      Returns:
        the list of (breadth-first) ordered nodes
      Since:
        2.5.0

    - #### public void breadthFirst(Closure c)

      Calls the provided closure for all the nodes in the tree using a breadth-first preorder traversal.

      Parameters:
        `c` - the closure to run for each node (a one or two parameter can be used; if one parameter is given the closure will be passed the node, for a two param closure the second parameter will be the level).
      Since:
        2.5.0

    - #### public void breadthFirst(Map<String, Object> options, Closure c)

      Calls the provided closure for all the nodes in the tree using a breadth-first traversal. A boolean 'preorder' options is supported.

      Parameters:
        `options` - map containing options
        `c` - the closure to run for each node (a one or two parameter can be used; if one parameter is given the closure will be passed the node, for a two param closure the second parameter will be the level).
      Since:
        2.5.0

    - #### public List children()

      Returns a `List` of the nodes children.

      Returns:
        the nodes children

    - #### public 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.

      Returns:
        the clone

    - #### public List depthFirst()

      Provides a collection of all the nodes in the tree using a depth-first preorder traversal.

      Returns:
        the list of (depth-first) ordered nodes

    - #### public List depthFirst(boolean preorder)

      Provides a collection of all the nodes in the tree using a depth-first traversal.

      Parameters:
        `preorder` - if false, a postorder depth-first traversal will be performed
      Returns:
        the list of (depth-first) ordered nodes
      Since:
        2.5.0

    - #### public void depthFirst(Closure c)

      Provides a collection of all the nodes in the tree using a depth-first preorder traversal.

      Parameters:
        `c` - the closure to run for each node (a one or two parameter can be used; if one parameter is given the closure will be passed the node, for a two param closure the second parameter will be the level).
      Since:
        2.5.0

    - #### public void depthFirst(Map<String, Object> options, Closure c)

      Provides a collection of all the nodes in the tree using a depth-first traversal. A boolean 'preorder' options is supported.

      Parameters:
        `options` - map containing options
        `c` - the closure to run for each node (a one or two parameter can be used; if one parameter is given the closure will be passed the node, for a two param closure the second parameter will be the level).
      Since:
        2.5.0

    - #### public Object get(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

    - #### public NodeList getAt(QName name)

      Provides lookup of elements by QName.

      Parameters:
        `name` - the QName of interest
      Returns:
        the nodes matching name

    - #### public Iterator iterator()

      Returns an `Iterator` of the children of the node.

      Returns:
        the iterator of the nodes children

    - #### public List<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

    - #### public Object name()

      Returns an `Object` representing the name of the node.

      Returns:
        the name or `null` if name is empty

    - #### public Node parent()

      Returns the parent of the node.

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

    - #### 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.

    - #### public void print(PrintWriter out)

      Writes the node to the specified `PrintWriter`.

      Parameters:
        `out` - the writer receiving the output

    - #### 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

    - #### 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

    - #### public Node replaceNode(Node n)

      Replaces the current node with the supplied node.

      Parameters:
        `n` - the new Node
      Returns:
        the original now replaced node

    - #### protected static void setMetaClass(MetaClass metaClass, 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)

    - #### protected void setParent(Node parent)

      Adds or replaces the parent of the node.

      Parameters:
        `parent` - the new parent of the node

    - #### public void setValue(Object value)

      Adds or replaces the value of the node.

      Parameters:
        `value` - the new value of the node

    - #### public 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

    - #### public BigDecimal toBigDecimal()

      Converts the text of this GPathResult to a BigDecimal object.

      Returns:
        the GPathResult, converted to a `BigDecimal`

    - #### public BigInteger toBigInteger()

      Converts the text of this GPathResult to a BigInteger object.

      Returns:
        the GPathResult, converted to a `BigInteger`

    - #### public Double toDouble()

      Converts the text of this GPathResult to a Double object.

      Returns:
        the GPathResult, converted to a `Double`

    - #### public Float toFloat()

      Converts the text of this GPathResult to a Float object.

      Returns:
        the GPathResult, converted to a `Float`

    - #### public Integer toInteger()

      Converts the text of this GPathResult to an Integer object.

      Returns:
        the GPathResult, converted to a `Integer`

    - #### public Long toLong()

      Converts the text of this GPathResult to a Long object.

      Returns:
        the GPathResult, converted to a `Long`

    - #### public Map<String, Object> toMap()

      Converts this Node tree into a nested `Map<String, Object>`.

      Attributes and child elements are merged into a single map keyed by name. If a child element name collides with an attribute name, the child element wins. Leaf child elements (text only, no attributes) become String values. Non-leaf child elements and leaf elements with attributes become nested Maps (recursive). Repeated same-name sibling elements become Lists. Elements with both attributes and text content use the {@value #TEXT_KEY} key for the text.

      Returns:
        a Map representation of this Node
      Since:
        6.0.0

    - #### public String toString()

      Returns a string representation of the object.

      API Note:
        In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The string output is not necessarily stable over time or across JVM invocations.
      Implementation Requirements:
        The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

        >     getClass().getName() + '@' + Integer.toHexString(hashCode())

      Returns:
        a string representation of the object.

    - #### public Object value()

      Returns an `Object` representing the value of the node.

      Returns:
        the value or `null` if value is empty