org.jboss.forge.parser.xml
Class Node

java.lang.Object
  org.jboss.forge.parser.xml.Node

public class Node
extends Object

Node is a data structure representing a container in a classic tree. May sometimes be synonymous with the term "Element" in XML. It may contain a Map of attributes (Strings), a reference to a List of child Nodes, and text data.

Version:

$Revision: $

Author:

Aslak Knutsen, Lincoln Baxter, III, ALR

Constructor Summary

Node(String name)
Creates a root Node

Node(String name, Node parent)
Creates a Node

Method Summary

Node	attribute(String name, Object value) Add or override a named attribute. value will be converted to String using String.valueOf(value);
Node	attribute(String name, String value) Add or override a named attribute.
Node	createChild(Pattern... patterns)
Node	createChild(String name) Create a new Node with given name.
List<Node>	get(Pattern... patterns) Get all children matching the specified query.
List<Node>	get(String name) Get all children with a specific name.
String	getAttribute(String name) Get a named attribute.
Map<String,String>	getAttributes() Get all defined attributes for this Node in an immutable view
List<Node>	getChildren() Get all the defined children for this node in an immutable view.
String	getName() Get the Nodes name.
Node	getOrCreate(Pattern... patterns)
Node	getOrCreate(String name) Get or create a named child node.
Node	getParent() Get the Nodes parent.
Node	getRoot() Obtains the root Node for this reference
Node	getSingle(Pattern... patterns)
Node	getSingle(String name) Get a single child node. If multiple children are found with same name it is considered a IllegalArgumentException.
String	getText() Get the Nodes text body.
String	getTextValueForPatternName(String name) Get the text value of the element found at the given query name.
List<String>	getTextValuesForPatternName(String name) Get the text values of all elements found at the given query name.
boolean	isComment() Returns whether or not this Node represents a comment
boolean	isRoot() Returns whether or not this Node is a root
String	removeAttribute(String name) Remove a named attribute.
boolean	removeChild(Node child) Remove a single child from this Node
Node	removeChild(String name) Remove a single child from this Node
List<Node>	removeChildren(Pattern pattern, Pattern... patterns) Remove all child nodes found at the given Patterns.
List<Node>	removeChildren(String name) Remove all child nodes found at the given query.
void	setComment(boolean comment) Marks this Node as a comment
Node	text(Object text) Set the Nodes text body. text will be converted to String using String.valueOf(text);
Node	text(String text) Set the Nodes text body.
String	toString()
String	toString(boolean verbose) Returns a multiline String format of this Node and all children

Methods inherited from class java.lang.Object

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

Constructor Detail

Node

public Node(String name)
     throws IllegalArgumentException

Creates a root Node

Parameters:

name - The name of the node

Throws:

IllegalArgumentException

Node

public Node(String name,
            Node parent)
     throws IllegalArgumentException

Creates a Node

Parameters:

name - The name of the node

parent - The parent node. Use null to denote a root.

Throws:

IllegalArgumentException - If the name is not specified or contains any space characters

Method Detail

attribute

public Node attribute(String name,
                      Object value)

Add or override a named attribute.

value will be converted to String using String.valueOf(value);

Parameters:

name - The attribute name

value - The given value

Returns:

This Node

See Also:

attribute(String, String)

attribute

public Node attribute(String name,
                      String value)

Add or override a named attribute.

Parameters:

name - The attribute name

value - The given value

Returns:

This Node

getAttribute

public String getAttribute(String name)

Get a named attribute.

Parameters:

name - The attribute name

Returns:

The attribute value or null of none defined.

removeAttribute

public String removeAttribute(String name)
                       throws IllegalArgumentException

Remove a named attribute.

Parameters:

name - The attribute name

Returns:

The attribute value that was removed, or null if the attribute with the given name was not found.

Throws:

IllegalArgumentException - If the name is not specified

getAttributes

public Map<String,String> getAttributes()

Get all defined attributes for this Node in an immutable view

Returns:

All defined attributes.

isComment

public boolean isComment()

Returns whether or not this Node represents a comment

Returns:

setComment

public void setComment(boolean comment)
                throws IllegalArgumentException

Marks this Node as a comment

Parameters:

comment - Whether or not this is a comment

Throws:

IllegalArgumentException - If this node has children

getRoot

public Node getRoot()

Obtains the root Node for this reference

Returns:

isRoot

public boolean isRoot()

Returns whether or not this Node is a root

Returns:

createChild

public Node createChild(String name)
                 throws IllegalArgumentException

Create a new Node with given name.

The new Node will have this as parent.

Parameters:

name - The name of the Node.

Returns:

A new child Node

Throws:

IllegalArgumentException - If the name is not specified

createChild

public Node createChild(Pattern... patterns)

getOrCreate

public Node getOrCreate(String name)

Get or create a named child node.

If a named node is found using getSingle(String) it is returned, else a new child node is created.

Parameters:

name - The child node name.

Returns:

The existing node or a new node, never null.

Throws:

IllegalArgumentException - if multiple children with name exists.

See Also:

getSingle(String), createChild(String)

getOrCreate

public Node getOrCreate(Pattern... patterns)

getSingle

public Node getSingle(String name)

Get a single child node.

If multiple children are found with same name it is considered a IllegalArgumentException.

Parameters:

name - The child node name

Returns:

The named child node or null if non found

Throws:

IllegalArgumentException - if multiple children with name exists.

getSingle

public Node getSingle(Pattern... patterns)

get

public List<Node> get(String name)

Get all children with a specific name.

Parameters:

name - The child node name.

Returns:

All found children, or empty list if none found.

get

public List<Node> get(Pattern... patterns)

Get all children matching the specified query.

Parameters:

query - The query to use for finding relevant child nodes

Returns:

All found children, or empty list if none found.

removeChildren

public List<Node> removeChildren(String name)
                          throws IllegalArgumentException

Remove all child nodes found at the given query.

Returns:

the List of removed children.

Throws:

IllegalArgumentException - If the specified name is not specified

removeChildren

public List<Node> removeChildren(Pattern pattern,
                                 Pattern... patterns)

Remove all child nodes found at the given Patterns.

Returns:

the List of removed children.

Throws:

IllegalArgumentException - If pattern is not specified

removeChild

public boolean removeChild(Node child)

Remove a single child from this Node

Returns:

true if this node contained the given child

removeChild

public Node removeChild(String name)

Remove a single child from this Node

Returns:

true if this node contained the given child

Throws:

IllegalArgumentException - if multiple children with name exist.

text

public Node text(Object text)

Set the Nodes text body.

text will be converted to String using String.valueOf(text);

Parameters:

text -

Returns:

See Also:

text(String)

text

public Node text(String text)

Set the Nodes text body.

Parameters:

text - The text content

Returns:

This

getText

public String getText()

Get the Nodes text body.

Returns:

Set body or null if none.

getTextValueForPatternName

public String getTextValueForPatternName(String name)

Get the text value of the element found at the given query name. If no element is found, or no text exists, return null;

getTextValuesForPatternName

public List<String> getTextValuesForPatternName(String name)

Get the text values of all elements found at the given query name. If no elements are found, or no text exists, return an empty list;

getName

public String getName()

Get the Nodes name.

Returns:

Given name.

getParent

public Node getParent()

Get the Nodes parent.

Returns:

The given parent or null if root node.

getChildren

public List<Node> getChildren()

Get all the defined children for this node in an immutable view.

Returns:

All children or empty list if none.

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

toString

public String toString(boolean verbose)

Returns a multiline String format of this Node and all children

Parameters:

verbose -

Returns: