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

## gnu.xml.dom
Class DomDocument

    java.lang.Object
      |
      +--gnu.xml.dom.DomNode
            |
            +--gnu.xml.dom.DomDocument

All Implemented Interfaces:
  java.lang.Cloneable, Document, DocumentEvent, org.w3c.dom.traversal.DocumentTraversal, 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/11/20 04:53:46 $
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(char[] buf, int off, int len)` Returns a newly created CDATA section node with the specified value.
`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(char[] buf, int off, int len)` Returns a newly created text node with the specified value.
`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)`
`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".
`short` | `getNodeType()` DOM L1 Returns the constant DOCUMENT_NODE.
`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, compact, createEvent, dispatchEvent, getAttributes, getChildNodes, getElementsByTagName, getElementsByTagNameNS, getFirstChild, getLastChild, getLength, getLocalName, getNamespaceURI, getNextSibling, 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, 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.
  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`

### getNodeType

    public final short getNodeType()

  DOM L1 Returns the constant DOCUMENT_NODE.
  Specified by:
    `getNodeType` 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.

  Returns null unless `Consumer` was used to populate internal DTD declaration information, using package-private APIs. If that internal DTD information is available, the document may be searched for the element with that ID.

  Specified by:
    `getElementById` in interface `Document`
  Following copied from interface: `org.w3c.dom.Document`
  Parameters:
    `elementId` - The 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:
    `newChild` - The 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 or this node itself.
    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 previous parent of the node being inserted 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:
    `newChild` - The node to insert.
    `refChild` - The 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 or this node itself.
    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:
    `newChild` - The new node to put in the child list.
    `oldChild` - The 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 or this node itself.
    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:
    `tagName` - The 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:
    `namespaceURI` - The namespace URI of the element to create.
    `qualifiedName` - The qualified name of the element type to instantiate.
  Returns:
    A new `Element` object with the following attributes:

    Attribute | Value
    --- | ---
    `Node.nodeName` | `qualifiedName`
    `Node.namespaceURI` | `namespaceURI`
    `Node.prefix` | prefix, extracted from `qualifiedName`, or `null` if there is no prefix
    `Node.localName` | local name, extracted from `qualifiedName`
    `Element.tagName` | `qualifiedName`

  Throws:
    `DOMException` - INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character, per the XML 1.0 specification .
    NAMESPACE_ERR: Raised if the `qualifiedName` is malformed per the Namespaces in XML specification, 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" .
    NOT_SUPPORTED_ERR: Always thrown if the current document does not support the `"XML"` feature, since namespaces were defined by XML.

### 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:
    `data` - The data for the node.
  Returns:
    The new `Text` object.

### createTextNode

    public Text createTextNode(char[] buf,
                               int off,
                               int len)

  Returns a newly created text node with the specified value.

### 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:
    `data` - The 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:
    `data` - The data for the `CDATASection` contents.
  Returns:
    The new `CDATASection` object.
  Throws:
    `DOMException` - NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

### createCDATASection

    public CDATASection createCDATASection(char[] buf,
                                           int off,
                                           int len)

  Returns a newly created CDATA section node with the specified value.

### 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:
    `target` - The target part of the processing instruction.
    `data` - The 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:
    `name` - The 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:
    `namespaceURI` - The namespace URI of the attribute to create.
    `qualifiedName` - The qualified name of the attribute to instantiate.
  Returns:
    A new `Attr` object with the following attributes:

    Attribute | Value
    --- | ---
    `Node.nodeName` | qualifiedName
    `Node.namespaceURI` | `namespaceURI`
    `Node.prefix` | prefix, extracted from `qualifiedName`, or `null` if there is no prefix
    `Node.localName` | local name, extracted from `qualifiedName`
    `Attr.name` | `qualifiedName`
    `Node.nodeValue` | the empty string

  Throws:
    `DOMException` - INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character, per the XML 1.0 specification .
    NAMESPACE_ERR: Raised if the `qualifiedName` is malformed per the Namespaces in XML specification, 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`, or its prefix, is "xmlns" and the `namespaceURI` is different from " http://www.w3.org/2000/xmlns/".
    NOT_SUPPORTED_ERR: Always thrown if the current document does not support the `"XML"` feature, since namespaces were defined by XML.

### 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:
    `importedNode` - The node to import.
    `deep` - If `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)

  Specified by:
    `createTreeWalker` in interface `org.w3c.dom.traversal.DocumentTraversal`

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

Source code is under GPL (with library exception) in the JAXP project at http://www.gnu.org/software/classpathx/jaxp
This documentation was derived from that source code on 2001-11-20.