ParentNode (XOM 1.2.4 API)
Date: 2009-12-11

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## nu.xom
Class ParentNode

    Object
      nu.xom.Node
          nu.xom.ParentNode

Direct Known Subclasses:
  Document, Element

    public abstract class ParentNode

extends Node

The generic superclass for nodes that have children. Not counting subclasses, there are exactly two such classes in XOM:

- `Document`
- `Element`

This class provides methods to add and remove child nodes.

Version:
  1.2.3
Author:
  Elliotte Rusty Harold

Method Summary
`void` | `appendChild(Node child)` Appends a node to the children of this node.
`Node` | `getChild(int position)` Returns the child of this node at the specified position.
`int` | `getChildCount()` Returns the number of child nodes this node contains.
`int` | `indexOf(Node child)` Returns the position of a node within the children of this node.
`void` | `insertChild(Node child, int position)` Inserts a child node at the specified position.
`Node` | `removeChild(int position)` Removes the child of this node at the specified position.
`Node` | `removeChild(Node child)` Removes the specified child of this node.
`void` | `replaceChild(Node oldChild, Node newChild)` Replaces an existing child with a new child node.
`abstract void` | `setBaseURI(String URI)` Sets the URI against which relative URIs in this node will be resolved.

Methods inherited from class nu.xom.Node
`copy, detach, equals, getBaseURI, getDocument, getParent, getValue, hashCode, query, query, toXML`

Methods inherited from class Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getChildCount

    public int getChildCount()

  Returns the number of child nodes this node contains. This is always greater than or equal to 0.

  Specified by:
    `getChildCount` in class `Node`
  Returns:
    the number of children of this node

### insertChild

    public void insertChild(Node child,
                            int position)

  Inserts a child node at the specified position. The child node previously at that position (if any) and all subsequent child nodes are moved up by one. That is, when inserting a node at 2, the old node at 2 is moved to 3, the old child at 3 is moved to 4, and so forth. Inserting at position 0 makes the child the first child of this node. Inserting at the position `getChildCount()` makes the child the last child of the node.

  All the other methods that add a node to the tree ultimately invoke this method.

  Parameters:
    `position` - where to insert the child
    `child` - the node to insert
  Throws:
    `IllegalAddException` - if this node cannot have a child of the argument's type
    `MultipleParentException` - if `child` already has a parent
    `NullPointerException` - if `child` is null
    `IndexOutOfBoundsException` - if the position is negative or greater than the number of children of this node

### appendChild

    public void appendChild(Node child)

  Appends a node to the children of this node.

  Parameters:
    `child` - node to append to this node
  Throws:
    `IllegalAddException` - if this node cannot have children of this type
    `MultipleParentException` - if child already has a parent
    `NullPointerException` - if `child` is null

### getChild

    public Node getChild(int position)

  Returns the child of this node at the specified position. Indexes begin at 0 and count up to one less than the number of children in this node.

  Specified by:
    `getChild` in class `Node`
  Parameters:
    `position` - index of the node to return
  Returns:
    the node at the requested position
  Throws:
    `IndexOutOfBoundsException` - if the index is negative or greater than or equal to the number of children of this node

### indexOf

    public int indexOf(Node child)

  Returns the position of a node within the children of this node. This is a number between 0 and one less than the number of children of this node. It returns -1 if `child` does not have this node as a parent.

  This method does a linear search through the node's children. On average, it executes in O(N) where N is the number of children of the node.

  Parameters:
    `child` - the node whose position is desired
  Returns:
    the position of the argument node among the children of this node

### removeChild

    public Node removeChild(int position)

  Removes the child of this node at the specified position. Indexes begin at 0 and count up to one less than the number of children in this node.

  Parameters:
    `position` - index of the node to remove
  Returns:
    the node which was removed
  Throws:
    `IndexOutOfBoundsException` - if the index is negative or greater than or equal to the number of children of this node

### removeChild

    public Node removeChild(Node child)

  Removes the specified child of this node.

  Parameters:
    `child` - child node to remove
  Returns:
    the node which was removed
  Throws:
    `NoSuchChildException` - if `child` is not in fact a child of this node

### replaceChild

    public void replaceChild(Node oldChild,
                             Node newChild)

  Replaces an existing child with a new child node. If `oldChild` is not a child of this node, then a `NoSuchChildException` is thrown.

  Parameters:
    `oldChild` - the node removed from the tree
    `newChild` - the node inserted into the tree
  Throws:
    `MultipleParentException` - if `newChild` already has a parent
    `NoSuchChildException` - if `oldChild` is not a child of this node
    `NullPointerException` - if either argument is null
    `IllegalAddException` - if this node cannot have children of the type of `newChild`

### setBaseURI

    public abstract void setBaseURI(String URI)

  Sets the URI against which relative URIs in this node will be resolved. Generally, it's only necessary to set this property if it's different from a node's parent's base URI, as it may be in a document assembled from multiple entities or by XInclude.

  Relative URIs are not allowed here. Base URIs must be absolute. However, the base URI may be set to null or the empty string to indicate that the node has no explicit base URI. In this case, it inherits the base URI of its parent node, if any.

  URIs with fragment identifiers are also not allowed. The value passed to this method must be a pure URI, not a URI reference.

  You can also add an `xml:base` attribute to an element in the same way you'd add any other namespaced attribute to an element. If an element's base URI conflicts with its `xml:base` attribute, then the value found in the `xml:base` attribute is used.

  If the base URI is null or the empty string and there is no `xml:base` attribute, then the base URI is determined by the nearest ancestor node which does have a base URI. Moving such a node from one location to another can change its base URI.

  Parameters:
    `URI` - the new base URI for this node
  Throws:
    `MalformedURIException` - if `URI` is not a legal RFC 3986 absolute URI

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2009 Elliotte Rusty Harold
elharo@ibiblio.org