nu.xom
Class ParentNode

java.lang.Object
  extended bynu.xom.Node
      extended bynu.xom.ParentNode
Direct Known Subclasses:
Document, Element

public abstract class ParentNode
extends Node

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

It provides methods to add and remove child nodes.

Version:
1.0d22
Author:
Elliotte Rusty Harold

Method Summary
 void appendChild(Node child)
           Appends a node to the children of this node.
protected  void checkInsertChild(Node child, int position)
           Subclasses can override this method to allow only certain nodes to be added in particular positions.
protected  void checkRemoveChild(Node child, int position)
           Subclasses can override this method to allow only certain nodes to be removed from particular positions.
 Node getChild(int position)
           Returns the child of this node at the specified position.
 int getChildCount()
           Returns the number of child nodes this node has.
 boolean hasChildren()
           This method returns true if and only if this node has child nodes.
 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(java.lang.String URI)
           Sets the URI from which this node was loaded, and against which relative URLs in this node will be resolved.
 
Methods inherited from class nu.xom.Node
checkDetach, copy, detach, equals, getBaseURI, getDocument, getParent, getValue, hashCode, toString, toXML
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

hasChildren

public boolean hasChildren()

This method returns true if and only if this node has child nodes. This is not the same question as whether this node contains child elements. This method may return true even if this node contains only comments, text nodes, and processing instructions.

Specified by:
hasChildren in class Node
Returns:
true if this node has children, false otherwise

getChildCount

public int getChildCount()

Returns the number of child nodes this node has. 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 positions 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 child of passed type
MultipleParentException - if child already has a parent
java.lang.NullPointerException - if child is null
java.lang.IndexOutOfBoundsException - if the position is negative or greater than the number of children of this node
XMLException - if the concrete subclass rejects this child

checkInsertChild

protected void checkInsertChild(Node child,
                                int position)

Subclasses can override this method to allow only certain nodes to be added in particular positions. By throwing an XMLException they can prevent the child from being added.

Parameters:
position - where to insert the child
child - the node to insert
Throws:
XMLException - if the subclass rejects the proposed child

appendChild

public final 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
java.lang.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:
java.lang.IndexOutOfBoundsException - if the index is negative or greater than the number of children of the node - 1

indexOf

public int indexOf(Node child)

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

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:
java.lang.IndexOutOfBoundsException - if the index is negative or greater than the number of children of this node - 1
XMLException - if the subclass rejects the removal

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.
XMLException - if the subclass rejects the removal

checkRemoveChild

protected void checkRemoveChild(Node child,
                                int position)

Subclasses can override this method to allow only certain nodes to be removed from particular positions. By throwing an XMLException they can prevent the child from being removed.

Parameters:
position - location of the node to be removed
child - the node to be removed
Throws:
XMLException - if the subclass rejects the removal

replaceChild

public final 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:
NoSuchChildException - if oldChild is not a child of this node
java.lang.NullPointerException - if newChild is null
IllegalAddException - if this node cannot have children of the type of newChild

setBaseURI

public abstract void setBaseURI(java.lang.String URI)

Sets the URI from which this node was loaded, and against which relative URLs 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 allowed. However, if the base URI on an element is relative, then getBaseURI will resolve the relative URI to a full absolute URI before returning using the algorithm specified in XML Base if possible.

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 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. To indicate that a node has a persistent lack of base URI, even if one of its ancestors does have a base URI, you can set the base URI to the empty string.

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


Copyright 2002-2004 Elliotte Rusty Harold
elharo@metalab.unc.edu