XML for Java 2.0.15

com.ibm.xml.dom
Class DocumentImpl

java.lang.Object
  |
  +--com.ibm.xml.dom.NodeImpl
        |
        +--com.ibm.xml.dom.DocumentImpl
Direct Known Subclasses:
DeferredDocumentImpl

public class DocumentImpl
extends NodeImpl
implements Document

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

Note: When any node in the document is serialized, the entire document is serialized along with it.

Since:
PR-DOM-Level-1-19980818.
Version:
56 1.12 src/com/ibm/xml/dom/DocumentImpl.java, parser, xml4j2, xml4j2_0_15
See Also:
Serialized Form

Field Summary
protected  ElementImpl docElement
          Document element.
protected  DocumentTypeImpl docType
          Document type.
protected  java.util.Hashtable identifiers
          Identifiers.
 
Fields inherited from class com.ibm.xml.dom.NodeImpl
ELEMENT_DEFINITION_NODE, firstChild, kidOK, lastChild, name, nextSibling, ownerDocument, parentNode, previousSibling, readOnly, syncChildren, syncData, userData, value
 
Constructor Summary
DocumentImpl()
          NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.
 
Method Summary
 Node cloneNode(boolean deep)
          Deep-clone a document, including fixing ownerDoc for the cloned children.
 Attr createAttribute(java.lang.String name)
          Factory method; creates an Attribute having this Document as its OwnerDoc.
 CDATASection createCDATASection(java.lang.String data)
          Factory method; creates a CDATASection having this Document as its OwnerDoc.
 Comment createComment(java.lang.String data)
          Factory method; creates a Comment having this Document as its OwnerDoc.
 DocumentFragment createDocumentFragment()
          Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
 DocumentType createDocumentType(java.lang.String name)
          NON-DOM Factory method; creates a DocumentType having this Document as its OwnerDoc.
 Element createElement(java.lang.String tagName)
          Factory method; creates an Element having this Document as its OwnerDoc.
 ElementDefinitionImpl createElementDefinition(java.lang.String name)
          NON-DOM Factory method: creates an element definition.
 Entity createEntity(java.lang.String name)
          NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc.
 EntityReference createEntityReference(java.lang.String name)
          Factory method; creates an EntityReference having this Document as its OwnerDoc.
 Notation createNotation(java.lang.String name)
          NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc.
 ProcessingInstruction createProcessingInstruction(java.lang.String target, java.lang.String data)
          Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
 Text createTextNode(java.lang.String data)
          Factory method; creates a Text node having this Document as its OwnerDoc.
 DocumentType getDoctype()
          For XML, this provides access to the Document Type Definition.
 Element getDocumentElement()
          Convenience method, allowing direct access to the child node which is considered the root of the actual document content.
 NodeList getElementsByTagName(java.lang.String tagname)
          Return a live collection of all descendent Elements (not just immediate children) having the specified tag name.
 Element getIdentifier(java.lang.String idName)
          Returns a previously registered element with the specified identifier name, or null if no element is registered.
 java.util.Enumeration getIdentifiers()
          Returns an enumeration registered of identifier names.
 DOMImplementation getImplementation()
          Retrieve information describing the abilities of this particular DOM implementation.
 java.lang.String getNodeName()
          Returns the node name.
 short getNodeType()
          Returns the node type.
 java.lang.String getNodeValue()
          Returns the node value.
 Node importNode(Node source, boolean deep)
          NON-DOM: Copies data from the source node.
 Node insertBefore(Node newChild, Node refChild)
          Since a Document may contain at most one top-level Element child, and at most one DocumentType declaraction, we need to subclass our add-children methods to implement this constraint.
static boolean isXMLName(java.lang.String s)
          Check the string against XML's definition of acceptable names for elements and attributes and so on.
 void putIdentifier(java.lang.String idName, Element element)
          Registers an identifier name with a specified element node.
 Node removeChild(Node oldChild)
          Since insertBefore caches the docElement (and, currently, docType), removeChild has to know how to undo the cache
 void removeIdentifier(java.lang.String idName)
          Removes a previously registered element with the specified identifier name.
 void setNodeValue(java.lang.String x)
          Documents never have a nodeValue.
 
Methods inherited from class com.ibm.xml.dom.NodeImpl
appendChild, changed, getAttributes, getChildNodes, getFirstChild, getLastChild, getLength, getNextSibling, getOwnerDocument, getParentNode, getPreviousSibling, getReadOnly, getUserData, hasChildNodes, isKidOK, item, replaceChild, setReadOnly, setUserData, synchronizeChildren, synchronizeData, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

docType

protected DocumentTypeImpl docType
Document type.

docElement

protected ElementImpl docElement
Document element.

identifiers

protected java.util.Hashtable identifiers
Identifiers.
Constructor Detail

DocumentImpl

public DocumentImpl()
NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.
Method Detail

getNodeType

public short getNodeType()
Returns the node type.
Overrides:
getNodeType in class NodeImpl

getNodeName

public java.lang.String getNodeName()
Returns the node name.
Overrides:
getNodeName in class NodeImpl

getNodeValue

public java.lang.String getNodeValue()
Returns the node value.
Overrides:
getNodeValue in class NodeImpl

cloneNode

public Node cloneNode(boolean deep)
Deep-clone a document, including fixing ownerDoc for the cloned children. Note that this requires bypassing the WRONG_DOCUMENT_ERR protection. I've chosen to implement it by calling importNode -- which is NON-DOM in Level 1, but which anticipates one likely direction the Level 2 DOM might take in solving this.
Parameters:
deep - boolean, iff true replicate children
Returns:
org.w3c.dom.Node
Overrides:
cloneNode in class NodeImpl

insertBefore

public Node insertBefore(Node newChild,
                         Node refChild)
                  throws DOMException
Since a Document may contain at most one top-level Element child, and at most one DocumentType declaraction, we need to subclass our add-children methods to implement this constraint. Since appendChild() is implemented as insertBefore(,null), altering the latter fixes both.

While I'm doing so, I've taken advantage of the opportunity to cache documentElement and docType so we don't have to search for them.

Overrides:
insertBefore in class NodeImpl

removeChild

public Node removeChild(Node oldChild)
                 throws DOMException
Since insertBefore caches the docElement (and, currently, docType), removeChild has to know how to undo the cache
Overrides:
removeChild in class NodeImpl

setNodeValue

public void setNodeValue(java.lang.String x)
                  throws DOMException
Documents never have a nodeValue.
Throws:
DOMException(NO_MODIFICATION_ALLOWED_ERR) -  
Overrides:
setNodeValue in class NodeImpl

createAttribute

public Attr createAttribute(java.lang.String name)
                     throws DOMException
Factory method; creates an Attribute having this Document as its OwnerDoc.
Specified by:
createAttribute in interface Document
Parameters:
name - The name of the attribute. Note that the attribute's value is _not_ established at the factory; remember to set it!
Throws:
DOMException(INVALID_NAME_ERR) - if the attribute name is not acceptable.

createCDATASection

public CDATASection createCDATASection(java.lang.String data)
                                throws DOMException
Factory method; creates a CDATASection having this Document as its OwnerDoc.
Specified by:
createCDATASection in interface Document
Parameters:
data - The initial contents of the CDATA
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents. (HTML not yet implemented.)

createComment

public Comment createComment(java.lang.String data)
Factory method; creates a Comment having this Document as its OwnerDoc.
Specified by:
createComment in interface Document
Parameters:
data - The initial contents of the Comment.

createDocumentFragment

public DocumentFragment createDocumentFragment()
Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
Specified by:
createDocumentFragment in interface Document

createElement

public Element createElement(java.lang.String tagName)
                      throws DOMException
Factory method; creates an Element having this Document as its OwnerDoc.
Specified by:
createElement in interface 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.
Throws:
DOMException(INVALID_NAME_ERR) - if the tag name is not acceptable.

createEntityReference

public EntityReference createEntityReference(java.lang.String name)
                                      throws DOMException
Factory method; creates an EntityReference having this Document as its OwnerDoc.
Specified by:
createEntityReference in interface Document
Parameters:
name - The name of the Entity we wish to refer to
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)

createProcessingInstruction

public ProcessingInstruction createProcessingInstruction(java.lang.String target,
                                                         java.lang.String data)
                                                  throws DOMException
Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
Specified by:
createProcessingInstruction in interface Document
Parameters:
target - The target "processor channel"
data - Parameter string to be passed to the target.
Throws:
DOMException(INVALID_NAME_ERR) - if the target name is not acceptable.
DOMException(NOT_SUPPORTED_ERR) - for HTML documents. (HTML not yet implemented.)

createTextNode

public Text createTextNode(java.lang.String data)
Factory method; creates a Text node having this Document as its OwnerDoc.
Specified by:
createTextNode in interface Document
Parameters:
data - The initial contents of the Text.

getDoctype

public DocumentType getDoctype()
For XML, this provides access to the Document Type Definition. For HTML documents, and XML documents which don't specify a DTD, it will be null.
Specified by:
getDoctype in interface Document

getDocumentElement

public Element getDocumentElement()
Convenience method, allowing direct access to the child node which is considered the root of the actual document content. For HTML, where it is legal to have more than one Element at the top level of the document, we pick the one with the tagName "HTML". For XML there should be only one top-level (HTML not yet supported.)
Specified by:
getDocumentElement in interface Document

getElementsByTagName

public NodeList getElementsByTagName(java.lang.String tagname)
Return a live collection of all descendent Elements (not just immediate children) having the specified tag name.
Specified by:
getElementsByTagName in interface Document
Parameters:
tagname - The type of Element we want to gather. "*" will be taken as a wildcard, meaning "all elements in the document."
See Also:
com.ibm.domimpl.DeepNodeListImpl

getImplementation

public DOMImplementation getImplementation()
Retrieve information describing the abilities of this particular DOM implementation. Intended to support applications that may be using DOMs retrieved from several different sources, potentially with different underlying representations.
Specified by:
getImplementation in interface Document

createDocumentType

public DocumentType createDocumentType(java.lang.String name)
                                throws DOMException
NON-DOM Factory method; creates a DocumentType having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:
name - The name of the Entity we wish to provide a value for.
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where DTDs are not permitted. (HTML not yet implemented.)

createEntity

public Entity createEntity(java.lang.String name)
                    throws DOMException
NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:
name - The name of the Entity we wish to provide a value for.
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)

createNotation

public Notation createNotation(java.lang.String name)
                        throws DOMException
NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:
name - The name of the Notation we wish to describe
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where notations are not permitted. (HTML not yet implemented.)

createElementDefinition

public ElementDefinitionImpl createElementDefinition(java.lang.String name)
                                              throws DOMException
NON-DOM Factory method: creates an element definition. Element definitions hold default attribute values.

importNode

public Node importNode(Node source,
                       boolean deep)
                throws DOMException
NON-DOM: Copies data from the source node. Unlike cloneNode, this _can_ copy data from another document. If the source document is also based on com.ibm.domimpl, we will attempt to preserve the domimpl- internal data by doing a clone-and-reparent. If not, we will use the source's public methods, and this document's Factory methods, to copy data defined by the DOM interfaces. Its behavior is otherwise similar to that of cloneNode. Attempting to import a Document into another Document is meaningless -- a new Document would not improve matters much, and a DocumentFragment couldn't carry the DocumentType child (if any). Best thing we can do is throw a HIERARCHY_REQUEST_ERR. ????? Should we push some of this down to copy-ctors, so subclassed DOMs have the option of special-casing each other (as we do for ourself)?

putIdentifier

public void putIdentifier(java.lang.String idName,
                          Element element)
Registers an identifier name with a specified element node. If the identifier is already registered, the new element node replaces the previous node. If the specified element node is null, removeIdentifier() is called.
See Also:
getIdentifier(java.lang.String), removeIdentifier(java.lang.String)

getIdentifier

public Element getIdentifier(java.lang.String idName)
Returns a previously registered element with the specified identifier name, or null if no element is registered.
See Also:
putIdentifier(java.lang.String, org.w3c.dom.Element), removeIdentifier(java.lang.String)

removeIdentifier

public void removeIdentifier(java.lang.String idName)
Removes a previously registered element with the specified identifier name.
See Also:
putIdentifier(java.lang.String, org.w3c.dom.Element), getIdentifier(java.lang.String)

getIdentifiers

public java.util.Enumeration getIdentifiers()
Returns an enumeration registered of identifier names.

isXMLName

public static boolean isXMLName(java.lang.String s)
Check the string against XML's definition of acceptable names for elements and attributes and so on. From the XML spec:

[Definition:] A Name is a token beginning with a letter or one of a few punctuation characters, and continuing with letters, digits, hyphens,underscores, colons, or full stops, together known as name characters.

Unfortunately, that spec goes on to say that after the first character, names may use "combining characters" and "extender characters", which are explicitly listed rather than defined in terms of Java's Unicode character types... and which in fact can't be expressed solely in terms of those types.

I've empirically derived some tests which are partly based on the Java Unicode space (which simplifies them considerably), but they still wind up having to be further qualified. This may not remain valid if future extensions of Java and/or Unicode introduce other characters having these type numbers.

Suggestions for alternative implementations would be welcome.


XML for Java 2.0.15