nu.xom
Class Document

java.lang.Object
  extended bynu.xom.Node
      extended bynu.xom.ParentNode
          extended bynu.xom.Document

public class Document
extends ParentNode

The Document class represents a complete XML document including its root element, prolog, and epilog.

Version:
1.0d23
Author:
Elliotte Rusty Harold

Constructor Summary
Document(Document doc)
           Creates a copy of the Document.
Document(Element root)
           Creates a new Document object with the specified root element.
 
Method Summary
protected  void checkRoot(Element root)
           Subclasses can override this method to perform additional checks on the root element beyond what XML 1.0 requires.
 Node copy()
           Returns a complete copy of this document.
 java.lang.String getBaseURI()
           Returns the URI from which this document was loaded.
 DocType getDocType()
           Returns this document's document type declaration, or null if it doesn't have one.
 Element getRootElement()
           Returns this document's root element.
 java.lang.String getValue()
           Returns the value of the document as defined by XPath 1.0.
 void insertChild(Node child, int position)
           Inserts a child node at the specified position.
 Node removeChild(int position)
           Removes the child of this document at the specified position.
 Node removeChild(Node child)
           Removes the specified child from this node.
 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.
 void setDocType(DocType doctype)
           Sets this document's document type declaration.
 void setRootElement(Element root)
           Replaces the current root element with a different root element.
 java.lang.String toString()
           Returns a string representation of this node suitable for debugging and diagnosis.
 java.lang.String toXML()
           Returns the actual complete, well-formed XML document as a String.
 
Methods inherited from class nu.xom.ParentNode
appendChild, checkInsertChild, checkRemoveChild, getChild, getChildCount, hasChildren, indexOf, replaceChild
 
Methods inherited from class nu.xom.Node
checkDetach, detach, equals, getDocument, getParent, hashCode
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Document

public Document(Element root)

Creates a new Document object with the specified root element.

Parameters:
root - the root element of this document

Document

public Document(Document doc)

Creates a copy of the Document.

Parameters:
doc - the Document to copy
Method Detail

insertChild

public final void insertChild(Node child,
                              int position)

Inserts a child node at the specified position. 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.

Overrides:
insertChild in class ParentNode
Parameters:
position - where to insert the child
child - the node to insert
Throws:
IllegalAddException - if child is not a Comment, ProcessingInstruction, or DocType, or if child is a DocType but this document already has a DocType
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 the node.`

getDocType

public final DocType getDocType()

Returns this document's document type declaration, or null if it doesn't have one.

Returns:
the document type declaration
See Also:
setDocType(nu.xom.DocType)

setDocType

public final void setDocType(DocType doctype)

Sets this document's document type declaration. If this document already has a document type declaration, then it's inserted at that position. Otherwise, it's inserted at the beginning of the document.

Parameters:
doctype - the document type declaration
Throws:
MultipleParentException - if doctype belongs to another document
java.lang.NullPointerException - if doctype is null

getRootElement

public final Element getRootElement()

Returns this document's root element. This is guaranteed to be non-null.

Returns:
the root element

setRootElement

public final void setRootElement(Element root)

Replaces the current root element with a different root element.

Parameters:
root - the new root element
Throws:
MultipleParentException - if root has a parent
XMLException - if root is not legal for this subclass of Document
java.lang.NullPointerException - if root is null

checkRoot

protected void checkRoot(Element root)

Subclasses can override this method to perform additional checks on the root element beyond what XML 1.0 requires. For example, an XHTMLDocument subclass might throw an exception if the proposed root element were not an html element.

Parameters:
root - The new root element.
Throws:
XMLException - if the proposed root element does not satisfy the local constraints

removeChild

public final Node removeChild(int position)

Removes the child of this document at the specified position. Indexes begin at 0 and count up to one less than the number of children of this document. The root element cannot be removed. Instead, use setRootElement to replace the existing root element with a different element.

Overrides:
removeChild in class ParentNode
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 document - 1.
WellformednessException - if the index points to the root element.

removeChild

public final Node removeChild(Node child)

Removes the specified child from this node. It throws a NoSuchChildException if the node is not a child of this node. The root element cannot be removed. Instead, use setRootElement to replace the existing root element with a different element.

Overrides:
removeChild in class ParentNode
Parameters:
child - node to remove
Returns:
the node which was removed
Throws:
NoSuchChildException - if the node is not a child of this node.
WellformednessException - if child is the root element.

setBaseURI

public final 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.

Specified by:
setBaseURI in class ParentNode
Parameters:
URI - the base URI of this document
Throws:
MalformedURIException - if URI is not a legal IRI

getBaseURI

public final java.lang.String getBaseURI()

Returns the URI from which this document was loaded.

Overrides:
getBaseURI in class Node
Returns:
the base URI of this document

getValue

public final java.lang.String getValue()

Returns the value of the document as defined by XPath 1.0. This is the same as the value of the root element, which is the complete PCDATA content of the root element, without any tags, comments, or processing instructions after all entity and character references have been resolved.

Specified by:
getValue in class Node
Returns:
value of the root element of this document
See Also:
Node.getValue()

toXML

public final java.lang.String toXML()

Returns the actual complete, well-formed XML document as a String. Significant white space is preserved. Insignificant white space in tags, the prolog, the epilog, and the internal DTD subset is not preserved. Entity and character references are not preserved. The entire document is contained in this one string.

Specified by:
toXML in class Node
Returns:
a String containing this entire XML document
See Also:
Node.toXML()

copy

public Node copy()

Returns a complete copy of this document.

Specified by:
copy in class Node
Returns:
a complete, deep copy of this Document object
See Also:
Node.copy()

toString

public final java.lang.String toString()

Returns a string representation of this node suitable for debugging and diagnosis. This is not the XML representation of this document.

Specified by:
toString in class Node
Returns:
a non-XML string representation of this Document object
See Also:
Node.toString()


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