Java Doc for CoreDocumentImpl.java in  » XML » xerces-2_9_1 » org » apache » xerces » dom » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

The CoreDocumentImpl class only implements the DOM Core. Additional modules are supported by the more complete DocumentImpl subclass.

Note: When any node in the document is serialized, the entire document is serialized along with it.
author:
   Arnaud Le Hors, IBM
author:
   Joe Kesselman, IBM
author:
   Andy Clark, IBM
author:
   Ralf Pfeiffer, IBM
version:
   $Id: CoreDocumentImpl.java 515302 2007-03-06 21:07:10Z mrglavas $
since:
   PR-DOM-Level-1-19980818.

Any method that alters the tree structure MUST cause or be accompanied by a call to changed(), to inform it that any outstanding NodeLists may have to be updated.

(Required because NodeList is simultaneously "live" and integer- indexed -- a bad decision in the DOM's design.)

Note that changes which do not affect the tree's structure -- changing the node's name, for example -- do _not_ have to call changed().

Alternative implementation would be to use a cryptographic Digest value rather than a count.

Any method that alters the tree structure MUST cause or be accompanied by a call to changed(), to inform it that any outstanding NodeLists may have to be updated.

(Required because NodeList is simultaneously "live" and integer- indexed -- a bad decision in the DOM's design.)

Note that changes which do not affect the tree's structure -- changing the node's name, for example -- do _not_ have to call changed().

Alternative implementation would be to use a cryptographic Digest value rather than a count. This would have the advantage that "harmless" changes (those producing equal() trees) would not force NodeList to resynchronize. Disadvantage is that it's slightly more prone to "false negatives", though that's the difference between "wildly unlikely" and "absurdly unlikely". IF we start maintaining digests, we should consider taking advantage of them. Note: This used to be done a node basis, so that we knew what subtree changed. But since only DeepNodeList really use this today, the gain appears to be really small compared to the cost of having an int on every (parent) node plus having to walk up the tree all the way to the root to mark the branch as changed everytime a node is changed. So we now have a single counter global to the document. It means that some objects may flush their cache more often than necessary, but this makes nodes smaller and only the document needs to be marked as changed.

Creates an attribute of the given qualified name and namespace URI. If the given namespaceURI is null or an empty string and the qualifiedName has a prefix that is "xml", the created element is bound to the predefined namespace "http://www.w3.org/XML/1998/namespace" [Namespaces].
Parameters:
  namespaceURI - The namespace URI of the attribute tocreate. When it is null or an empty string,this method behaves like createAttribute.
Parameters:
  qualifiedName - The qualified name of the attribute toinstantiate. Attr A new Attr object.
throws:
  DOMException - INVALID_CHARACTER_ERR: Raised if the specifiedname contains an invalid character.
since:
   WD-DOM-Level-2-19990923

Creates an element of the given qualified name and namespace URI. If the given namespaceURI is null or an empty string and the qualifiedName has a prefix that is "xml", the created element is bound to the predefined namespace "http://www.w3.org/XML/1998/namespace" [Namespaces].
Parameters:
  namespaceURI - The namespace URI of the element tocreate.
Parameters:
  qualifiedName - The qualified name of the element type toinstantiate. Element A new Element object with the following attributes:
throws:
  DOMException - INVALID_CHARACTER_ERR: Raised if the specifiedname contains an invalid character.
throws:
  DOMException - NAMESPACE_ERR: Raised if the qualifiedName has aprefix that is "xml" and the namespaceURI isneither null nor an empty string nor"http://www.w3.org/XML/1998/namespace", orif the qualifiedName has a prefix differentfrom "xml" and the namespaceURI is null or anempty string.
since:
   WD-DOM-Level-2-19990923

Note: The DOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.
See Also:   CoreDocumentImpl.getIdentifier

Returns a NodeList of all the Elements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the Document tree.
Parameters:
  namespaceURI - The namespace URI of the elements to matchon. The special value "*" matches allnamespaces. When it is null or an emptystring, this method behaves likegetElementsByTagName.
Parameters:
  localName - The local name of the elements to match on.The special value "*" matches all local names. NodeList A new NodeList object containing all the matchedElements.
since:
   WD-DOM-Level-2-19990923

According to the DOM specifications, document nodes cannot be imported and a NOT_SUPPORTED_ERR exception is thrown if attempted.

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. REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way

• Checking strings to make sure that all characters are legal XML characters
• Hierarchy checking such as allowed children, checks for cycles, etc.

Turning off error checking does not turn off the following checks:

• Read only checks
• Checks related to DOM events