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" }}`

Author:
  James Strachan, Paul King
See Also:
  - Serialized Form

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

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

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

### breadthFirst

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