org.apache.xerces.dom3
Interface Document3

All Superinterfaces:
org.w3c.dom.Document, org.w3c.dom.Node

public interface Document3
extends org.w3c.dom.Document

The Document3 interface is an extension to the DOM Level 2 Document interface containing the DOM Level 3 additions.

See also the Document Object Model (DOM) Level 3 Core Specification.


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
 
Method Summary
 org.w3c.dom.Node adoptNode(org.w3c.dom.Node source)
          Changes the ownerDocument of a node, its children, as well as the attached attribute nodes if there are any.
 boolean canSetNormalizationFeature(java.lang.String name, boolean state)
          Query whether setting a feature to a specific value is supported.
 java.lang.String getActualEncoding()
          An attribute specifying the actual encoding of this document.
 java.lang.String getDocumentURI()
          The location of the document or null if undefined.
 java.lang.String getEncoding()
          An attribute specifying, as part of the XML declaration, the encoding of this document.
 DOMErrorHandler getErrorHandler()
          This attribute allows applications to specify a DOMErrorHandler to be called in the event that an error is encountered while performing an operation on a document.
 boolean getNormalizationFeature(java.lang.String name)
          Look up the value of a feature.
 boolean getStandalone()
          An attribute specifying, as part of the XML declaration, whether this document is standalone.
 boolean getStrictErrorChecking()
          An attribute specifying whether errors checking is enforced or not.
 java.lang.String getVersion()
          An attribute specifying, as part of the XML declaration, the version number of this document.
 void normalizeDocument()
          This method acts as if the document was going through a save and load cycle, putting the document in a "normal" form.
 org.w3c.dom.Node renameNode(org.w3c.dom.Node n, java.lang.String namespaceURI, java.lang.String name)
          Rename an existing node.
 void setActualEncoding(java.lang.String actualEncoding)
          An attribute specifying the actual encoding of this document.
 void setDocumentURI(java.lang.String documentURI)
          The location of the document or null if undefined.
 void setEncoding(java.lang.String encoding)
          An attribute specifying, as part of the XML declaration, the encoding of this document.
 void setErrorHandler(DOMErrorHandler errorHandler)
          This attribute allows applications to specify a DOMErrorHandler to be called in the event that an error is encountered while performing an operation on a document.
 void setNormalizationFeature(java.lang.String name, boolean state)
          Set the state of a feature.
 void setStandalone(boolean standalone)
          An attribute specifying, as part of the XML declaration, whether this document is standalone.
 void setStrictErrorChecking(boolean strictErrorChecking)
          An attribute specifying whether errors checking is enforced or not.
 void setVersion(java.lang.String version)
          An attribute specifying, as part of the XML declaration, the version number of this document.
 
Methods inherited from interface org.w3c.dom.Document
createAttribute, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createElement, createElementNS, createEntityReference, createProcessingInstruction, createTextNode, getDoctype, getDocumentElement, getElementById, getElementsByTagName, getElementsByTagNameNS, getImplementation, importNode
 
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix
 

Method Detail

getActualEncoding

public java.lang.String getActualEncoding()
An attribute specifying the actual encoding of this document. This is null otherwise.
This attribute represents the property [character encoding scheme] defined in .
Since:
DOM Level 3

setActualEncoding

public void setActualEncoding(java.lang.String actualEncoding)
An attribute specifying the actual encoding of this document. This is null otherwise.
This attribute represents the property [character encoding scheme] defined in .
Since:
DOM Level 3

getEncoding

public java.lang.String getEncoding()
An attribute specifying, as part of the XML declaration, the encoding of this document. This is null when unspecified.
Since:
DOM Level 3

setEncoding

public void setEncoding(java.lang.String encoding)
An attribute specifying, as part of the XML declaration, the encoding of this document. This is null when unspecified.
Since:
DOM Level 3

getStandalone

public boolean getStandalone()
An attribute specifying, as part of the XML declaration, whether this document is standalone.
This attribute represents the property [standalone] defined in .
Since:
DOM Level 3

setStandalone

public void setStandalone(boolean standalone)
An attribute specifying, as part of the XML declaration, whether this document is standalone.
This attribute represents the property [standalone] defined in .
Since:
DOM Level 3

getVersion

public java.lang.String getVersion()
An attribute specifying, as part of the XML declaration, the version number of this document. This is null when unspecified.
This attribute represents the property [version] defined in .
Since:
DOM Level 3

setVersion

public void setVersion(java.lang.String version)
An attribute specifying, as part of the XML declaration, the version number of this document. This is null when unspecified.
This attribute represents the property [version] defined in .
Since:
DOM Level 3

getStrictErrorChecking

public boolean getStrictErrorChecking()
An attribute specifying whether errors checking is enforced or not. When set to false, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any DOMException. In case of error, the behavior is undefined. This attribute is true by defaults.
Since:
DOM Level 3

setStrictErrorChecking

public void setStrictErrorChecking(boolean strictErrorChecking)
An attribute specifying whether errors checking is enforced or not. When set to false, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any DOMException. In case of error, the behavior is undefined. This attribute is true by defaults.
Since:
DOM Level 3

getErrorHandler

public DOMErrorHandler getErrorHandler()
This attribute allows applications to specify a DOMErrorHandler to be called in the event that an error is encountered while performing an operation on a document. Note that not all methods use this mechanism, see the description of each method for details.
Since:
DOM Level 3

setErrorHandler

public void setErrorHandler(DOMErrorHandler errorHandler)
This attribute allows applications to specify a DOMErrorHandler to be called in the event that an error is encountered while performing an operation on a document. Note that not all methods use this mechanism, see the description of each method for details.
Since:
DOM Level 3

getDocumentURI

public java.lang.String getDocumentURI()
The location of the document or null if undefined.
Beware that when the Document supports the feature "HTML" , the href attribute of the HTML BASE element takes precedence over this attribute.
Since:
DOM Level 3

setDocumentURI

public void setDocumentURI(java.lang.String documentURI)
The location of the document or null if undefined.
Beware that when the Document supports the feature "HTML" , the href attribute of the HTML BASE element takes precedence over this attribute.
Since:
DOM Level 3

adoptNode

public org.w3c.dom.Node adoptNode(org.w3c.dom.Node source)
                           throws org.w3c.dom.DOMException
Changes the ownerDocument of a node, its children, as well as the attached attribute nodes if there are any. If the node has a parent it is first removed from its parent child list. This effectively allows moving a subtree from one document to another. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the adopted Attr. The descendants of the source Attr are recursively adopted.
DOCUMENT_FRAGMENT_NODE
The descendants of the source node are recursively adopted.
DOCUMENT_NODE
Document nodes cannot be adopted.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be adopted.
ELEMENT_NODE
Specified attribute nodes of the source element are adopted, and the generated Attr nodes. Default attributes are discarded, though if the document being adopted into defines default attributes for this element name, those are assigned. The descendants of the source element are recursively adopted.
ENTITY_NODE
Entity nodes cannot be adopted.
ENTITY_REFERENCE_NODE
Only the EntityReference node itself is adopted, the descendants are discarded, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes cannot be adopted.
PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These nodes can all be adopted. No specifics.
Should this method simply return null when it fails? How "exceptional" is failure for this method?Stick with raising exceptions only in exceptional circumstances, return null on failure (F2F 19 Jun 2000).Can an entity node really be adopted?No, neither can Notation nodes (Telcon 13 Dec 2000).Does this affect keys and hashCode's of the adopted subtree nodes?If so, what about readonly-ness of key and hashCode?if not, would appendChild affect keys/hashCodes or would it generate exceptions if key's are duplicate? Both keys and hashcodes have been dropped.
Parameters:
source - The node to move into this document.
Returns:
The adopted node, or null if this operation fails, such as when the source node comes from a different implementation.
Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised if the source node is of type DOCUMENT, DOCUMENT_TYPE.
NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is readonly.
Since:
DOM Level 3

normalizeDocument

public void normalizeDocument()
This method acts as if the document was going through a save and load cycle, putting the document in a "normal" form. The actual result depends on the features being set and governing what operations actually take place. See setNormalizeFeature for details.
Noticeably this method normalizes Text nodes, makes the document "namespace wellformed", according to the algorithm described below in pseudo code, by adding missing namespace declaration attributes and adding or changing namespace prefixes, updates the replacement tree of EntityReference nodes, normalizes attribute values, etc.
See for details on how namespace declaration attributes and prefixes are normalized.Any other name? Joe proposes normalizeNamespaces.normalizeDocument. (F2F 26 Sep 2001)How specific should this be? Should we not even specify that this should be done by walking down the tree?Very. See above.What does this do on attribute nodes?Doesn't do anything (F2F 1 Aug 2000).How does it work with entity reference subtree which may be broken?This doesn't affect entity references which are not visited in this operation (F2F 1 Aug 2000).Should this really be on Node?Yes, but this only works on Document, Element, and DocumentFragment. On other types it is a no-op. (F2F 1 Aug 2000).No. Now that it does much more than simply fixing namespaces it only makes sense on Document (F2F 26 Sep 2001). What happens with read-only nodes?What/how errors should be reported? Are there any?Through the error reporter.Should this be optional?No. What happens with regard to mutation events?
Since:
DOM Level 3

canSetNormalizationFeature

public boolean canSetNormalizationFeature(java.lang.String name,
                                          boolean state)
Query whether setting a feature to a specific value is supported.
The feature name has the same form as a DOM hasFeature string.
Parameters:
name - The name of the feature to check.
state - The requested state of the feature (true or false).
Returns:
true if the feature could be successfully set to the specified value, or false if the feature is not recognized or the requested value is not supported. This does not change the current value of the feature itself.
Since:
DOM Level 3

setNormalizationFeature

public void setNormalizationFeature(java.lang.String name,
                                    boolean state)
                             throws org.w3c.dom.DOMException
Set the state of a feature.
The feature name has the same form as a DOM hasFeature string.
It is possible for a Document to recognize a feature name but to be unable to set its value.Need to specify the list of features.
Parameters:
name - The name of the feature to set.
state - The requested state of the feature (true or false).
Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised when the feature name is recognized but the requested value cannot be set.
NOT_FOUND_ERR: Raised when the feature name is not recognized.
Since:
DOM Level 3

getNormalizationFeature

public boolean getNormalizationFeature(java.lang.String name)
                                throws org.w3c.dom.DOMException
Look up the value of a feature.
The feature name has the same form as a DOM hasFeature string
Parameters:
name - The name of the feature to look up.
Returns:
The current state of the feature (true or false).
Throws:
org.w3c.dom.DOMException - NOT_FOUND_ERR: Raised when the feature name is not recognized.
Since:
DOM Level 3

renameNode

public org.w3c.dom.Node renameNode(org.w3c.dom.Node n,
                                   java.lang.String namespaceURI,
                                   java.lang.String name)
                            throws org.w3c.dom.DOMException
Rename an existing node. When possible this simply changes the name of the given node, otherwise this creates a new node with the specified name and replaces the existing node with the new node as described below. This only applies to nodes of type ELEMENT_NODE and ATTRIBUTE_NODE.
When a new node is created, the following operations are performed: the new node is created, any registered event listener is registered on the new node, any user data attached to the old node is removed from that node, the old node is removed from its parent if it has one, the children are moved to the new node, if the renamed node is an Element its attributes are moved to the new node, the new node is inserted at the position the old node used to have in its parent's child nodes list if it has one, the user data that was attached to the old node is attach to the new node, the user data event NODE_RENAMED is fired.
When the node being renamed is an Attr that is attached to an Element, the node is first removed from the Element attributes map. Then, once renamed, either by modifying the existing node or creating a new one as described above, it is put back.
In addition, when the implementation supports the feature "MutationEvents", each mutation operation involved in this method fires the appropriate event, and in the end the event ElementNameChanged or AttributeNameChanged is fired.Should this throw a HIERARCHY_REQUEST_ERR?
Parameters:
n - The node to rename.
namespaceURI - The new namespaceURI.
name - The new qualified name.
Returns:
The renamed node. This is either the specified node or the new node that was created to replace the specified node.
Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised when the type of the specified node is neither ELEMENT_NODE nor ATTRIBUTE_NODE.
Since:
DOM Level 3


Copyright © 1999-2002 Apache XML Project. All Rights Reserved.