gnu.xml.dom
Class DomDocument

java.lang.Object
  |
  +--gnu.xml.dom.DomNode
        |
        +--gnu.xml.dom.DomDocument
All Implemented Interfaces:
java.lang.Cloneable, Document, org.w3c.dom.events.DocumentEvent, org.w3c.dom.traversal.DocumentTraversal, org.w3c.dom.events.EventTarget, Node, NodeList

public class DomDocument
extends DomNode
implements Document, org.w3c.dom.traversal.DocumentTraversal

"Document" and "DocumentTraversal" implementation.

Note that when this checks names for legality, it uses an approximation of the XML rules, not the real ones. Specifically, it uses Unicode rules, with sufficient tweaks to pass a majority of basic XML conformance tests. (The huge XML character tables are hairy to implement.)

Version:
$Date: 2001/06/20 21:30:05 $
Author:
David Brownell

Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
 
Constructor Summary
  DomDocument()
          Constructs a Document node, associating it with an instance of the DomImpl class.
protected DomDocument(DOMImplementation impl)
          Constructs a Document node, associating it with the specified implementation.
 
Method Summary
 Node appendChild(Node newChild)
          DOM L1 Appends the specified node to this node's list of children, enforcing the constraints that there be only one root element and one document type child.
 Attr createAttribute(java.lang.String name)
          DOM L1 Returns a newly created attribute with the specified name.
 Attr createAttributeNS(java.lang.String namespaceURI, java.lang.String name)
          DOM L2 Returns a newly created attribute with the specified name and namespace information.
 CDATASection createCDATASection(java.lang.String value)
          DOM L1 Returns a newly created CDATA section node with the specified value.
 Comment createComment(java.lang.String value)
          DOM L1 Returns a newly created comment node with the specified value.
 DocumentFragment createDocumentFragment()
          DOM L1 Returns a newly created document fragment.
 Element createElement(java.lang.String name)
          DOM L1 Returns a newly created element with the specified name.
 Element createElementNS(java.lang.String namespaceURI, java.lang.String name)
          DOM L2 Returns a newly created element with the specified name and namespace information.
 EntityReference createEntityReference(java.lang.String name)
          DOM L1 Returns a newly created reference to the specified entity.
 org.w3c.dom.traversal.NodeIterator createNodeIterator(Node root, int whatToShow, org.w3c.dom.traversal.NodeFilter filter, boolean expandEntities)
          DOM L2 (Traversal) Returns a newly created node iterator.
 ProcessingInstruction createProcessingInstruction(java.lang.String target, java.lang.String data)
          DOM L1 Returns a newly created processing instruction.
 Text createTextNode(java.lang.String value)
          DOM L1 Returns a newly created text node with the specified value.
 org.w3c.dom.traversal.TreeWalker createTreeWalker(Node root, int whatToShow, org.w3c.dom.traversal.NodeFilter filter, boolean entityReferenceExpansion)
          Create a new TreeWalker over the subtree rooted at the specified node.
 DocumentType getDoctype()
          DOM L1 Returns the document's DocumentType, or null.
 Element getDocumentElement()
          DOM L1 Returns the document's root element, or null.
 Element getElementById(java.lang.String id)
          DOM L1 (relocated in DOM L2) Returns the element with the specified "ID" attribute, or null.
 DOMImplementation getImplementation()
          DOM L1 Returns the document's DOMImplementation.
 java.lang.String getNodeName()
          DOM L1 Returns the constant "#document".
 Node importNode(Node copiedNode, boolean deep)
          DOM L2 Makes a copy of the specified node, with all nodes "owned" by this document and with children optionally copied.
 Node insertBefore(Node newChild, Node refChild)
          DOM L1 Inserts the specified node in this node's list of children, enforcing the constraints that there be only one root element and one document type child.
 boolean isCheckingCharacters()
          Returns true if certain expensive checks are performed.
 Node replaceChild(Node newChild, Node refChild)
          DOM L1 Replaces the specified node in this node's list of children, enforcing the constraints that there be only one root element and one document type child.
 void setCheckingCharacters(boolean value)
          Controls whether certain expensive checks, duplicating those that conformant XML parsers must perform, are made.
static void verifyXmlName(java.lang.String name)
          Throws a DOM exception if the specified name is not a legal XML 1.0 name.
 
Methods inherited from class gnu.xml.dom.DomNode
addEventListener, clone, cloneNode, createEvent, dispatchEvent, getAttributes, getChildNodes, getElementsByTagName, getElementsByTagNameNS, getFirstChild, getLastChild, getLength, getLocalName, getNamespaceURI, getNextSibling, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, isReadonly, isSupported, item, makeReadonly, nameAndTypeEquals, normalize, removeChild, removeEventListener, setNodeValue, setPrefix, trimToSize
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.w3c.dom.Document
getElementsByTagName, getElementsByTagNameNS
 
Methods inherited from interface org.w3c.dom.Node
cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, isSupported, normalize, removeChild, setNodeValue, setPrefix
 

Constructor Detail

DomDocument

public DomDocument()
Constructs a Document node, associating it with an instance of the DomImpl class.

Note that this constructor disables character checking. It is normally used when connecting a DOM to an XML parser, and duplicating such checks is undesirable. When used for purposes other than connecting to a parser, you should re-enable that checking.

See Also:
setCheckingCharacters(boolean)

DomDocument

protected DomDocument(DOMImplementation impl)
Constructs a Document node, associating it with the specified implementation. This should only be used in conjunction with a specialized implementation; it will normally be called by that implementation.

Note that this constructor enables character checking; this constructor is not normally used when connecting a DOM to an XML parser, so

See Also:
DomImpl, setCheckingCharacters(boolean)
Method Detail

getNodeName

public final java.lang.String getNodeName()
DOM L1 Returns the constant "#document".
Specified by:
getNodeName in interface Node

getDocumentElement

public final Element getDocumentElement()
DOM L1 Returns the document's root element, or null.
Specified by:
getDocumentElement in interface Document

getDoctype

public final DocumentType getDoctype()
DOM L1 Returns the document's DocumentType, or null.
Specified by:
getDoctype in interface Document

getImplementation

public final DOMImplementation getImplementation()
DOM L1 Returns the document's DOMImplementation.
Specified by:
getImplementation in interface Document

getElementById

public Element getElementById(java.lang.String id)
DOM L1 (relocated in DOM L2) Returns the element with the specified "ID" attribute, or null.

Since there is no nonproprietary way to associate the "ID" type with attributes (L3 should finally offer this functionality) this returns null unless it is overridden by some subclass accessing proprietary functionality, or (as with the XHTML DOM) hard-wiring such DTD knowledge in software.

Specified by:
getElementById in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
elementIdThe - unique id value for an element.
Returns:
The matching element.

appendChild

public Node appendChild(Node newChild)
DOM L1 Appends the specified node to this node's list of children, enforcing the constraints that there be only one root element and one document type child.
Specified by:
appendChild in interface Node
Overrides:
appendChild in class DomNode
Following copied from interface: org.w3c.dom.Node
Parameters:
newChildThe - node to add.If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node
Returns:
The node added.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

insertBefore

public Node insertBefore(Node newChild,
                         Node refChild)
DOM L1 Inserts the specified node in this node's list of children, enforcing the constraints that there be only one root element and one document type child.
Specified by:
insertBefore in interface Node
Overrides:
insertBefore in class DomNode
Following copied from interface: org.w3c.dom.Node
Parameters:
newChildThe - node to insert.
refChildThe - reference node, i.e., the node before which the new node must be inserted.
Returns:
The node being inserted.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the parent of the node being inserted is readonly.
NOT_FOUND_ERR: Raised if refChild is not a child of this node.

replaceChild

public Node replaceChild(Node newChild,
                         Node refChild)
DOM L1 Replaces the specified node in this node's list of children, enforcing the constraints that there be only one root element and one document type child.
Specified by:
replaceChild in interface Node
Overrides:
replaceChild in class DomNode
Following copied from interface: org.w3c.dom.Node
Parameters:
newChildThe - new node to put in the child list.
oldChildThe - node being replaced in the list.
Returns:
The node replaced.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the new node is readonly.
NOT_FOUND_ERR: Raised if oldChild is not a child of this node.

verifyXmlName

public static void verifyXmlName(java.lang.String name)
Throws a DOM exception if the specified name is not a legal XML 1.0 name. Actually this uses a very similar set of rules, closer to Unicode rules than to the rules encoded in the large table at the end of the XML 1.0 specification.
Throws:
DomException - INVALID_CHARACTER_ERR if the name isn't legal as an XML name.

setCheckingCharacters

public final void setCheckingCharacters(boolean value)
Controls whether certain expensive checks, duplicating those that conformant XML parsers must perform, are made.

isCheckingCharacters

public final boolean isCheckingCharacters()
Returns true if certain expensive checks are performed. Those checks are intended to reject illegal names, and characters that are illegal as XML characters.

createElement

public Element createElement(java.lang.String name)
DOM L1 Returns a newly created element with the specified name.
Specified by:
createElement in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
tagNameThe - name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.
Returns:
A new Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

createElementNS

public Element createElementNS(java.lang.String namespaceURI,
                               java.lang.String name)
DOM L2 Returns a newly created element with the specified name and namespace information.
Specified by:
createElementNS in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
namespaceURIThe - namespace URI of the element to create.
qualifiedNameThe - qualified name of the element type to instantiate.
Returns:
A new Element object with the following attributes:AttributeValueNode.nodeName qualifiedNameNode.namespaceURI namespaceURINode.prefixprefix, extracted from qualifiedName, or null if there is no prefixNode.localNamelocal name, extracted from qualifiedNameElement.tagName qualifiedName
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.
NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace" .

createDocumentFragment

public DocumentFragment createDocumentFragment()
DOM L1 Returns a newly created document fragment.
Specified by:
createDocumentFragment in interface Document
Following copied from interface: org.w3c.dom.Document
Returns:
A new DocumentFragment.

createTextNode

public Text createTextNode(java.lang.String value)
DOM L1 Returns a newly created text node with the specified value.
Specified by:
createTextNode in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
dataThe - data for the node.
Returns:
The new Text object.

createComment

public Comment createComment(java.lang.String value)
DOM L1 Returns a newly created comment node with the specified value.
Specified by:
createComment in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
dataThe - data for the node.
Returns:
The new Comment object.

createCDATASection

public CDATASection createCDATASection(java.lang.String value)
DOM L1 Returns a newly created CDATA section node with the specified value.
Specified by:
createCDATASection in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
dataThe - data for the CDATASection contents.
Returns:
The new CDATASection object.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createProcessingInstruction

public ProcessingInstruction createProcessingInstruction(java.lang.String target,
                                                         java.lang.String data)
DOM L1 Returns a newly created processing instruction.
Specified by:
createProcessingInstruction in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
targetThe - target part of the processing instruction.
dataThe - data for the node.
Returns:
The new ProcessingInstruction object.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified target contains an illegal character.
NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createAttribute

public Attr createAttribute(java.lang.String name)
DOM L1 Returns a newly created attribute with the specified name.
Specified by:
createAttribute in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
nameThe - name of the attribute.
Returns:
A new Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null. The value of the attribute is the empty string.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

createAttributeNS

public Attr createAttributeNS(java.lang.String namespaceURI,
                              java.lang.String name)
DOM L2 Returns a newly created attribute with the specified name and namespace information.
Specified by:
createAttributeNS in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
namespaceURIThe - namespace URI of the attribute to create.
qualifiedNameThe - qualified name of the attribute to instantiate.
Returns:
A new Attr object with the following attributes: AttributeValueNode.nodeNamequalifiedName Node.namespaceURInamespaceURI Node.prefixprefix, extracted from qualifiedName, or null if there is no prefixNode.localNamelocal name, extracted from qualifiedNameAttr.name qualifiedNameNode.nodeValuethe empty string
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.
NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace", or if the qualifiedName is "xmlns" and the namespaceURI is different from " http://www.w3.org/2000/xmlns/".

createEntityReference

public EntityReference createEntityReference(java.lang.String name)
DOM L1 Returns a newly created reference to the specified entity. The caller should populate this with the appropriate children and then mark it as readonly.
Specified by:
createEntityReference in interface Document
See Also:
DomNode.makeReadonly()

importNode

public Node importNode(Node copiedNode,
                       boolean deep)
DOM L2 Makes a copy of the specified node, with all nodes "owned" by this document and with children optionally copied. This type of standard utility has become, well, a standard utility.

Note that EntityReference nodes created through this method (either directly, or recursively) never have children, and that there is no portable way to associate them with such children.

Note also that there is no requirement that the specified node be associated with a different document. This differs from the cloneNode operation in that the node itself is not given an opportunity to participate, so that any information managed by node subclasses will be lost.

Specified by:
importNode in interface Document
Following copied from interface: org.w3c.dom.Document
Parameters:
importedNodeThe - node to import.
deepIf - true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This has no effect on Attr , EntityReference, and Notation nodes.
Returns:
The imported node that belongs to this Document.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

createNodeIterator

public org.w3c.dom.traversal.NodeIterator createNodeIterator(Node root,
                                                             int whatToShow,
                                                             org.w3c.dom.traversal.NodeFilter filter,
                                                             boolean expandEntities)
DOM L2 (Traversal) Returns a newly created node iterator. Don't forget to detach this iterator when you're done using it!
Specified by:
createNodeIterator in interface org.w3c.dom.traversal.DocumentTraversal
See Also:
DomIterator

createTreeWalker

public org.w3c.dom.traversal.TreeWalker createTreeWalker(Node root,
                                                         int whatToShow,
                                                         org.w3c.dom.traversal.NodeFilter filter,
                                                         boolean entityReferenceExpansion)
Description copied from interface: org.w3c.dom.traversal.DocumentTraversal
Create a new TreeWalker over the subtree rooted at the specified node.
Specified by:
createTreeWalker in interface org.w3c.dom.traversal.DocumentTraversal
Following copied from interface: org.w3c.dom.traversal.DocumentTraversal
Parameters:
rootThe - node which will serve as the root for the TreeWalker. The whatToShow flags and the NodeFilter are not considered when setting this value; any node type will be accepted as the root. The currentNode of the TreeWalker is initialized to this node, whether or not it is visible. The root functions as a stopping point for traversal methods that look upward in the document structure, such as parentNode and nextNode. The root must not be null.
whatToShowThis - flag specifies which node types may appear in the logical view of the tree presented by the tree-walker. See the description of NodeFilter for the set of possible SHOW_ values.These flags can be combined using OR.
filterThe - NodeFilter to be used with this TreeWalker, or null to indicate no filter.
entityReferenceExpansionIf - this flag is false, the contents of EntityReference nodes are not presented in the logical view.
Returns:
The newly created TreeWalker.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the specified root is null.

Source code is GPL'd in the JAXP subproject at http://savannah.gnu.org/projects/classpathx
This documentation was derived from that source code on 2001-07-12.