org.dom4j

Interface Branch

public interface Branch extends Node

Branch interface defines the common behaviour for Nodes which can contain child nodes (content) such as XML elements and documents. This interface allows both elements and documents to be treated in a polymorphic manner when changing or navigating child nodes (content).

Version: $Revision: 1.32 $

Author: James Strachan

Method Summary
voidadd(Node node)
Adds the given Node or throws {@link IllegalAddException} if the given node is not of a valid type.
voidadd(Comment comment)
Adds the given Comment to this branch.
voidadd(Element element)
Adds the given Element to this branch.
voidadd(ProcessingInstruction pi)
Adds the given ProcessingInstruction to this branch.
ElementaddElement(String name)
Adds a new Element node with the given name to this branch and returns a reference to the new node.
ElementaddElement(QName qname)
Adds a new Element node with the given {@link QName}to this branch and returns a reference to the new node.
ElementaddElement(String qualifiedName, String namespaceURI)
Adds a new Element node with the given qualified name and namespace URI to this branch and returns a reference to the new node.
voidappendContent(Branch branch)
Appends the content of the given branch to this branch instance.
voidclearContent()
Clears the content for this branch, removing any Node instances this branch may contain.
Listcontent()

Returns the content nodes of this branch as a backed {@link List}so that the content of this branch may be modified directly using the {@link List}interface.

ElementelementByID(String elementID)
Returns the element of the given ID attribute value.
intindexOf(Node node)
Returns the index of the given node if it is a child node of this branch or -1 if the given node is not a child node.
Nodenode(int index)
Returns the Node at the specified index position.
intnodeCount()
Returns the number of Node instances that this branch contains.
IteratornodeIterator()
Returns an iterator through the content nodes of this branch
voidnormalize()
Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes.
ProcessingInstructionprocessingInstruction(String target)
DOCUMENT ME!
ListprocessingInstructions()

Returns a list of all the processing instructions in this branch.

ListprocessingInstructions(String target)

Returns a list of the processing instructions for the given target.

booleanremove(Node node)
Removes the given Node if the node is an immediate child of this branch.
booleanremove(Comment comment)
Removes the given Comment if the node is an immediate child of this branch.
booleanremove(Element element)
Removes the given Element if the node is an immediate child of this branch.
booleanremove(ProcessingInstruction pi)
Removes the given ProcessingInstruction if the node is an immediate child of this branch.
booleanremoveProcessingInstruction(String target)
Removes the processing instruction for the given target if it exists
voidsetContent(List content)
Sets the contents of this branch as a List of Node instances.
voidsetProcessingInstructions(List listOfPIs)
Sets all the processing instructions for this branch

Method Detail

add

public void add(Node node)
Adds the given Node or throws {@link IllegalAddException} if the given node is not of a valid type. This is a polymorphic method which will call the typesafe method for the node type such as add(Element) or add(Comment).

Parameters: node is the given node to add

add

public void add(Comment comment)
Adds the given Comment to this branch. If the given node already has a parent defined then an IllegalAddException will be thrown.

Parameters: comment is the comment to be added

add

public void add(Element element)
Adds the given Element to this branch. If the given node already has a parent defined then an IllegalAddException will be thrown.

Parameters: element is the element to be added

add

public void add(ProcessingInstruction pi)
Adds the given ProcessingInstruction to this branch. If the given node already has a parent defined then an IllegalAddException will be thrown.

Parameters: pi is the processing instruction to be added

addElement

public Element addElement(String name)
Adds a new Element node with the given name to this branch and returns a reference to the new node.

Parameters: name is the name for the Element node.

Returns: the newly added Element node.

addElement

public Element addElement(QName qname)
Adds a new Element node with the given {@link QName}to this branch and returns a reference to the new node.

Parameters: qname is the qualified name for the Element node.

Returns: the newly added Element node.

addElement

public Element addElement(String qualifiedName, String namespaceURI)
Adds a new Element node with the given qualified name and namespace URI to this branch and returns a reference to the new node.

Parameters: qualifiedName is the fully qualified name of the Element namespaceURI is the URI of the namespace to use

Returns: the newly added Element node.

appendContent

public void appendContent(Branch branch)
Appends the content of the given branch to this branch instance. This method behaves like the {@link java.util.Collection#addAll(java.util.Collection)} method.

Parameters: branch is the branch whose content will be added to me.

clearContent

public void clearContent()
Clears the content for this branch, removing any Node instances this branch may contain.

content

public List content()

Returns the content nodes of this branch as a backed {@link List}so that the content of this branch may be modified directly using the {@link List}interface. The List is backed by the Branch so that changes to the list are reflected in the branch and vice versa.

Returns: the nodes that this branch contains as a List

elementByID

public Element elementByID(String elementID)
Returns the element of the given ID attribute value. If this tree is capable of understanding which attribute value should be used for the ID then it should be used, otherwise this method should return null.

Parameters: elementID DOCUMENT ME!

Returns: DOCUMENT ME!

indexOf

public int indexOf(Node node)
Returns the index of the given node if it is a child node of this branch or -1 if the given node is not a child node.

Parameters: node the content child node to find.

Returns: the index of the given node starting at 0 or -1 if the node is not a child node of this branch

node

public Node node(int index)
Returns the Node at the specified index position.

Parameters: index the index of the node to return.

Returns: the Node at the specified position.

Throws: IndexOutOfBoundsException if the index is out of range (index < 0 || index >= {@link Branch#nodeCount()}).

nodeCount

public int nodeCount()
Returns the number of Node instances that this branch contains.

Returns: the number of nodes this branch contains

nodeIterator

public Iterator nodeIterator()
Returns an iterator through the content nodes of this branch

Returns: an iterator through the content nodes of this branch

normalize

public void normalize()
Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on a particular document tree structure are to be used.In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

Since: DOM Level 2

processingInstruction

public ProcessingInstruction processingInstruction(String target)
DOCUMENT ME!

Parameters: target DOCUMENT ME!

Returns: the processing instruction for the given target

processingInstructions

public List processingInstructions()

Returns a list of all the processing instructions in this branch. The list is backed by this branch so that changes to the list will be reflected in the branch but the reverse is not the case.

Returns: a backed list of the processing instructions

processingInstructions

public List processingInstructions(String target)

Returns a list of the processing instructions for the given target. The list is backed by this branch so that changes to the list will be reflected in the branch but the reverse is not the case.

Parameters: target DOCUMENT ME!

Returns: a backed list of the processing instructions

remove

public boolean remove(Node node)
Removes the given Node if the node is an immediate child of this branch. If the given node is not an immediate child of this branch then the {@link Node#detach()}method should be used instead. This is a polymorphic method which will call the typesafe method for the node type such as remove(Element) or remove(Comment).

Parameters: node is the given node to be removed

Returns: true if the node was removed

remove

public boolean remove(Comment comment)
Removes the given Comment if the node is an immediate child of this branch. If the given node is not an immediate child of this branch then the {@link Node#detach()}method should be used instead.

Parameters: comment is the comment to be removed

Returns: true if the comment was removed

remove

public boolean remove(Element element)
Removes the given Element if the node is an immediate child of this branch. If the given node is not an immediate child of this branch then the {@link Node#detach()}method should be used instead.

Parameters: element is the element to be removed

Returns: true if the element was removed

remove

public boolean remove(ProcessingInstruction pi)
Removes the given ProcessingInstruction if the node is an immediate child of this branch. If the given node is not an immediate child of this branch then the {@link Node#detach()}method should be used instead.

Parameters: pi is the processing instruction to be removed

Returns: true if the processing instruction was removed

removeProcessingInstruction

public boolean removeProcessingInstruction(String target)
Removes the processing instruction for the given target if it exists

Parameters: target DOCUMENT ME!

Returns: true if a processing instruction was removed else false

setContent

public void setContent(List content)
Sets the contents of this branch as a List of Node instances.

Parameters: content is the list of nodes to use as the content for this branch.

setProcessingInstructions

public void setProcessingInstructions(List listOfPIs)
Sets all the processing instructions for this branch

Parameters: listOfPIs DOCUMENT ME!

Copyright B) 2005 MetaStuff Ltd. All Rights Reserved. Hosted by

SourceForge