## org.dom4j
Interface Branch

All Superinterfaces:
  Cloneable, Node

All Known Subinterfaces:
  Document, Element

All Known Implementing Classes:
  AbstractBranch, AbstractDocument, AbstractElement

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

Field Summary

Fields inherited from interface org.dom4j.Node
`ANY_NODE, ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, MAX_NODE_TYPE, NAMESPACE_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE, UNKNOWN_NODE`

Method Summary
`void` `add(Comment comment)` Adds the given `Comment` to this branch.
`void` `add(Element element)` Adds the given `Element` to this branch.
`void` `add(Node node)` Adds the given `Node` or throws `IllegalAddException` if the given node is not of a valid type.
`void` `add(ProcessingInstruction pi)` Adds the given `ProcessingInstruction` to this branch.
`Element` `addElement(QName qname)` Adds a new `Element` node with the given `QName`to this branch and returns a reference to the new node.
`Element` `addElement(String name)` Adds a new `Element` node with the given name to this branch and returns a reference to the new node.
`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.
`void` `appendContent(Branch branch)` Appends the content of the given branch to this branch instance.
`void` `clearContent()` Clears the content for this branch, removing any `Node` instances this branch may contain.
`List` `content()` Returns the content nodes of this branch as a backed `List`so that the content of this branch may be modified directly using the `List`interface.
`Element` `elementByID(String elementID)` Returns the element of the given ID attribute value.
`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.
`Node` `node(int index)` Returns the `Node` at the specified index position.
`int` `nodeCount()` Returns the number of `Node` instances that this branch contains.
`Iterator` `nodeIterator()` Returns an iterator through the content nodes of this branch
`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.
`ProcessingInstruction` `processingInstruction(String target)` DOCUMENT ME!
`List` `processingInstructions()` Returns a list of all the processing instructions in this branch.
`List` `processingInstructions(String target)` Returns a list of the processing instructions for the given target.
`boolean` `remove(Comment comment)` Removes the given `Comment` if the node is an immediate child of this branch.
`boolean` `remove(Element element)` Removes the given `Element` if the node is an immediate child of this branch.
`boolean` `remove(Node node)` Removes the given `Node` if the node is an immediate child of this branch.
`boolean` `remove(ProcessingInstruction pi)` Removes the given `ProcessingInstruction` if the node is an immediate child of this branch.
`boolean` `removeProcessingInstruction(String target)` Removes the processing instruction for the given target if it exists
`void` `setContent(List content)` Sets the contents of this branch as a `List` of `Node` instances.
`void` `setProcessingInstructions(List listOfPIs)` Sets all the processing instructions for this branch

Methods inherited from interface org.dom4j.Node
`accept, asXML, asXPathResult, clone, createXPath, detach, getDocument, getName, getNodeType, getNodeTypeName, getParent, getPath, getPath, getStringValue, getText, getUniquePath, getUniquePath, hasContent, isReadOnly, matches, numberValueOf, selectNodes, selectNodes, selectNodes, selectObject, selectSingleNode, setDocument, setName, setParent, setText, supportsParent, valueOf, write`

Method Detail

### node

    public Node node(int index)
              throws IndexOutOfBoundsException

  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 >= `nodeCount()`).

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

### nodeCount

    public int nodeCount()

  Returns the number of `Node` instances that this branch contains.

  Returns:
    the number of nodes this branch contains

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

### content

    public List content()

  Returns the content nodes of this branch as a backed `List`so that the content of this branch may be modified directly using the `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`

### nodeIterator

    public Iterator nodeIterator()

  Returns an iterator through the content nodes of this branch

  Returns:
    an iterator through the content nodes of this branch

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

### appendContent

    public void appendContent(Branch branch)

  Appends the content of the given branch to this branch instance. This method behaves like the `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.

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

### processingInstruction

    public ProcessingInstruction processingInstruction(String target)

  DOCUMENT ME!

  Parameters:
    `target` - DOCUMENT ME!
  Returns:
    the processing instruction for the given target

### setProcessingInstructions

    public void setProcessingInstructions(List listOfPIs)

  Sets all the processing instructions for this branch

  Parameters:
    `listOfPIs` - DOCUMENT ME!

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

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

### add

    public void add(Node node)

  Adds the given `Node` or throws `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

### 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 `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 `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 `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 `Node.detach()`method should be used instead.

  Parameters:
    `pi` - is the processing instruction to be removed
  Returns:
    true if the processing instruction was removed

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

Copyright © 2001-2005 MetaStuff Ltd.. All Rights Reserved.