Package groovy.util

# Class Node

java.lang.Object
groovy.util.Node

All Implemented Interfaces:
  `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" }}`

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `TEXT_KEY`
  The key used for text content when a node has both attributes and text.

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `append(Node child)`
  Appends a child to the current node.
  `Node`
  `appendNode(Object name)`
  Creates a new node as a child of the current node.
  `Node`
  `appendNode(Object name, Object value)`
  Creates a new node as a child of the current node.
  `Node`
  `appendNode(Object name, Map attributes)`
  Creates a new node as a child of the current node.
  `Node`
  `appendNode(Object name, Map attributes, Object value)`
  Creates a new node as a child of the current node.
  `Object`
  `attribute(Object key)`
  Provides lookup of attributes by key.
  `Map`
  `attributes()`
  Returns a `Map` of the attributes of the node or an empty `Map` if the node does not have any attributes.
  `List`
  `breadthFirst()`
  Provides a collection of all the nodes in the tree using a breadth-first preorder traversal.
  `List`
  `breadthFirst(boolean preorder)`
  Provides a collection of all the nodes in the tree using a breadth-first traversal.
  `void`
  `breadthFirst(Closure c)`
  Calls the provided closure for all the nodes in the tree using a breadth-first preorder traversal.
  `void`
  `breadthFirst(Map<String,Object> options, Closure c)`
  Calls the provided closure for all the nodes in the tree using a breadth-first traversal.
  `List`
  `children()`
  Returns a `List` of the nodes children.
  `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.
  `List`
  `depthFirst()`
  Provides a collection of all the nodes in the tree using a depth-first preorder traversal.
  `List`
  `depthFirst(boolean preorder)`
  Provides a collection of all the nodes in the tree using a depth-first traversal.
  `void`
  `depthFirst(Closure c)`
  Provides a collection of all the nodes in the tree using a depth-first preorder traversal.
  `void`
  `depthFirst(Map<String,Object> options, Closure c)`
  Provides a collection of all the nodes in the tree using a depth-first traversal.
  `Object`
  `get(String key)`
  Provides lookup of elements by non-namespaced name
  `NodeList`
  `getAt(QName name)`
  Provides lookup of elements by QName.
  `Iterator`
  `iterator()`
  Returns an `Iterator` of the children of the node.
  `List<String>`
  `localText()`
  Returns the list of any direct String nodes of this node.
  `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(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, 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(Object value)`
  Adds or replaces the value of the node.
  `String`
  `text()`
  Returns the textual representation of the current node and all its child nodes.
  `BigDecimal`
  `toBigDecimal()`
  Converts the text of this GPathResult to a BigDecimal object.
  `BigInteger`
  `toBigInteger()`
  Converts the text of this GPathResult to a BigInteger object.
  `Double`
  `toDouble()`
  Converts the text of this GPathResult to a Double object.
  `Float`
  `toFloat()`
  Converts the text of this GPathResult to a Float object.
  `Integer`
  `toInteger()`
  Converts the text of this GPathResult to an Integer object.
  `Long`
  `toLong()`
  Converts the text of this GPathResult to a Long object.
  `Map<String,Object>`
  `toMap()`
  Converts this Node tree into a nested `Map<String, Object>`.
  `String`
  `toString()`
  `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`

- ## Field Details

  - ### TEXT_KEY

    public static final String TEXT_KEY
    The key used for text content when a node has both attributes and text.
    Since:
      6.0.0
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Node

    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

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

  - ### Node

    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

  - ### Node

    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 Details

  - ### clone

    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.
    Overrides:
      `clone` in class `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(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`

  - ### appendNode

    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`

  - ### appendNode

    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`

  - ### appendNode

    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`

  - ### 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, 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 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 Iterator iterator()
    Returns an `Iterator` of the children of the node.
    Returns:
      the iterator of the nodes children

  - ### children

    public List children()
    Returns a `List` of the nodes children.
    Returns:
      the nodes children

  - ### attributes

    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

  - ### attribute

    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

  - ### name

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

  - ### value

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

  - ### setValue

    public void setValue(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 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

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

  - ### depthFirst

    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

  - ### depthFirst

    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

  - ### depthFirst

    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

  - ### breadthFirst

    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

  - ### breadthFirst

    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

  - ### breadthFirst

    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

  - ### breadthFirst

    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

  - ### localText

    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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### print

    public void print(PrintWriter out)
    Writes the node to the specified `PrintWriter`.
    Parameters:
      `out` - the writer receiving the output

  - ### toInteger

    public Integer toInteger()
    Converts the text of this GPathResult to an Integer object.
    Returns:
      the GPathResult, converted to a `Integer`

  - ### toLong

    public Long toLong()
    Converts the text of this GPathResult to a Long object.
    Returns:
      the GPathResult, converted to a `Long`

  - ### toFloat

    public Float toFloat()
    Converts the text of this GPathResult to a Float object.
    Returns:
      the GPathResult, converted to a `Float`

  - ### toDouble

    public Double toDouble()
    Converts the text of this GPathResult to a Double object.
    Returns:
      the GPathResult, converted to a `Double`

  - ### toBigDecimal

    public BigDecimal toBigDecimal()
    Converts the text of this GPathResult to a BigDecimal object.
    Returns:
      the GPathResult, converted to a `BigDecimal`

  - ### toBigInteger

    public BigInteger toBigInteger()
    Converts the text of this GPathResult to a BigInteger object.
    Returns:
      the GPathResult, converted to a `BigInteger`

  - ### toMap

    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 "_text" key for the text.

    Returns:
      a Map representation of this Node
    Since:
      6.0.0