Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
gnu.xml.dom.DomNode
gnu.xml.dom.DomDocument
public class DomDocument
extends DomNode
implements Document, DocumentTraversal, org.w3c.dom.xpath.XPathEvaluator
Constructor Summary | |
| |
|
Method Summary | |
Node | |
Node |
|
Attr |
|
Attr |
|
CDATASection |
|
CDATASection |
|
Comment |
|
DocumentFragment |
|
Element |
|
Element |
|
EntityReference |
|
org.w3c.dom.xpath.XPathExpression |
|
org.w3c.dom.xpath.XPathNSResolver |
|
NodeIterator |
|
ProcessingInstruction |
|
Text |
|
Text |
|
TreeWalker |
|
Object | |
String | |
DocumentType |
|
Element |
|
String |
|
DOMConfiguration |
|
Element |
|
DOMImplementation |
|
String |
|
String |
|
boolean |
|
String |
|
boolean |
|
String |
|
Node |
|
Node |
|
boolean |
|
String |
|
String |
|
void |
|
Node |
|
Node |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
static void |
|
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:
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
,DomDocument
public Node adoptNode(Node source)
Attempts to adopt a node from another document to this document. If supported, it changes theownerDocument
of the source node, its children, as well as the attached attribute nodes if there are any. If the source node has a parent it is first removed from the child list of its parent. This effectively allows moving a subtree from one document to another (unlikeimportNode()
which create a copy of the source node instead of moving it). When it fails, applications should useDocument.importNode()
instead. Note that if the adopted node is already part of this document (i.e. the source and target document are the same), this method still has the effect of removing the source node from the child list of its parent, if any. The following list describes the specifics for each type of node.Note: Since it does not create new nodes unlike the
- ATTRIBUTE_NODE
- The
ownerElement
attribute is set tonull
and thespecified
flag is set totrue
on the adoptedAttr
. The descendants of the sourceAttr
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. 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.
Document.importNode()
method, this method does not raise anINVALID_CHARACTER_ERR
exception, and applications should use theDocument.normalizeDocument()
method to check if an imported name is not an XML name according to the XML version in use.
- 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.
- Since:
- DOM Level 3
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 interface DomNode
public Attr createAttribute(String name)
DOM L1 Returns a newly created attribute with the specified name.
- Specified by:
- createAttribute in interface Document
public Attr createAttributeNS(String namespaceURI, String name)
DOM L2 Returns a newly created attribute with the specified name and namespace information.
- Specified by:
- createAttributeNS in interface Document
public CDATASection createCDATASection(String value)
DOM L1 Returns a newly created CDATA section node with the specified value.
- Specified by:
- createCDATASection in interface Document
public CDATASection createCDATASection(char[] buf, int off, int len)
Returns a newly created CDATA section node with the specified value.
public Comment createComment(String value)
DOM L1 Returns a newly created comment node with the specified value.
- Specified by:
- createComment in interface Document
public DocumentFragment createDocumentFragment()
DOM L1 Returns a newly created document fragment.
- Specified by:
- createDocumentFragment in interface Document
public Element createElement(String name)
DOM L1 Returns a newly created element with the specified name.
- Specified by:
- createElement in interface Document
public Element createElementNS(String namespaceURI, String name)
DOM L2 Returns a newly created element with the specified name and namespace information.
- Specified by:
- createElementNS in interface Document
public EntityReference createEntityReference(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()
public org.w3c.dom.xpath.XPathExpression createExpression(String expression, org.w3c.dom.xpath.XPathNSResolver resolver) throws org.w3c.dom.xpath.XPathException, DOMException
- Specified by:
- createExpression in interface org.w3c.dom.xpath.XPathEvaluator
public org.w3c.dom.xpath.XPathNSResolver createNSResolver(Node nodeResolver)
- Specified by:
- createNSResolver in interface org.w3c.dom.xpath.XPathEvaluator
public NodeIterator createNodeIterator(Node root, int whatToShow, 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 DocumentTraversal
- See Also:
DomIterator
public ProcessingInstruction createProcessingInstruction(String target, String data)
DOM L1 Returns a newly created processing instruction.
- Specified by:
- createProcessingInstruction in interface Document
public Text createTextNode(String value)
DOM L1 Returns a newly created text node with the specified value.
- Specified by:
- createTextNode in interface Document
public Text createTextNode(char[] buf, int off, int len)
Returns a newly created text node with the specified value.
public TreeWalker createTreeWalker(Node root, int whatToShow, NodeFilter filter, boolean expandEntities)
Create a newTreeWalker
over the subtree rooted at the specified node.
- Specified by:
- createTreeWalker in interface DocumentTraversal
- Parameters:
root
- The node which will serve as theroot
for theTreeWalker
. ThewhatToShow
flags and theNodeFilter
are not considered when setting this value; any node type will be accepted as theroot
. ThecurrentNode
of theTreeWalker
is initialized to this node, whether or not it is visible. Theroot
functions as a stopping point for traversal methods that look upward in the document structure, such asparentNode
and nextNode. Theroot
must not benull
.whatToShow
- This flag specifies which node types may appear in the logical view of the tree presented by theTreeWalker
. See the description ofNodeFilter
for the set of possibleSHOW_
values.These flags can be combined usingOR
.filter
- TheNodeFilter
to be used with thisTreeWalker
, ornull
to indicate no filter.
- Returns:
- The newly created
TreeWalker
.
public Object evaluate(String expression, Node contextNode, org.w3c.dom.xpath.XPathNSResolver resolver, short type, Object result) throws org.w3c.dom.xpath.XPathException, DOMException
- Specified by:
- evaluate in interface org.w3c.dom.xpath.XPathEvaluator
public String getBaseURI()
- Specified by:
- getBaseURI in interface Node
- Overrides:
- getBaseURI in interface DomNode
public final DocumentType getDoctype()
DOM L1 Returns the document's DocumentType, or null.
- Specified by:
- getDoctype in interface Document
public final Element getDocumentElement()
DOM L1 Returns the document's root element, or null.
- Specified by:
- getDocumentElement in interface Document
public String getDocumentURI()
The location of the document ornull
if undefined or if theDocument
was created usingDOMImplementation.createDocument
. No lexical checking is performed when setting this attribute; this could result in anull
value returned when usingNode.baseURI
.
Beware that when theDocument
supports the feature "HTML" [DOM Level 2 HTML] , the href attribute of the HTML BASE element takes precedence over this attribute when computingNode.baseURI
.
- Specified by:
- getDocumentURI in interface Document
- Since:
- DOM Level 3
public DOMConfiguration getDomConfig()
The configuration used whenDocument.normalizeDocument()
is invoked.
- Specified by:
- getDomConfig in interface Document
- Since:
- DOM Level 3
public Element getElementById(String id)
DOM L1 (relocated in DOM L2) Returns the element with the specified "ID" attribute, or null. Returns null unlessConsumer
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
public final DOMImplementation getImplementation()
DOM L1 Returns the document's DOMImplementation.
- Specified by:
- getImplementation in interface Document
public String getInputEncoding()
DOM L3
- Specified by:
- getInputEncoding in interface Document
public final String getNodeName()
DOM L1 Returns the constant "#document".
- Specified by:
- getNodeName in interface Node
- Overrides:
- getNodeName in interface DomNode
public boolean getStrictErrorChecking()
An attribute specifying whether error checking is enforced or not. When set tofalse
, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise anyDOMException
on DOM operations or report errors while usingDocument.normalizeDocument()
. In case of error, the behavior is undefined. This attribute istrue
by default.
- Specified by:
- getStrictErrorChecking in interface Document
- Since:
- DOM Level 3
public String getXmlEncoding()
DOM L3
- Specified by:
- getXmlEncoding in interface Document
public boolean getXmlStandalone()
An attribute specifying, as part of the XML declaration, whether this document is standalone. This isfalse
when unspecified. Note: No verification is done on the value when setting this attribute. Applications should useDocument.normalizeDocument()
with the "validate" parameter to verify if the value matches the validity constraint for standalone document declaration as defined in [XML 1.0].
- Specified by:
- getXmlStandalone in interface Document
- Since:
- DOM Level 3
public String getXmlVersion()
An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is"1.0"
. If this document does not support the "XML" feature, the value is alwaysnull
. Changing this attribute will affect methods that check for invalid characters in XML names. Application should invokeDocument.normalizeDocument()
in order to check for invalid characters in theNode
s that are already part of thisDocument
.
DOM applications may use theDOMImplementation.hasFeature(feature, version)
method with parameter values "XMLVersion" and "1.0" (respectively) to determine if an implementation supports [XML 1.0]. DOM applications may use the same method with parameter values "XMLVersion" and "1.1" (respectively) to determine if an implementation supports [XML 1.1]. In both cases, in order to support XML, an implementation must also support the "XML" feature defined in this specification.Document
objects supporting a version of the "XMLVersion" feature must not raise aNOT_SUPPORTED_ERR
exception for the same version number when usingDocument.xmlVersion
.
- Specified by:
- getXmlVersion in interface Document
- Since:
- DOM Level 3
public Node importNode(Node src, 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
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 interface DomNode
public boolean isDefaultNamespace(String namespaceURI)
- Specified by:
- isDefaultNamespace in interface Node
- Overrides:
- isDefaultNamespace in interface DomNode
public String lookupNamespaceURI(String prefix)
- Specified by:
- lookupNamespaceURI in interface Node
- Overrides:
- lookupNamespaceURI in interface DomNode
public String lookupPrefix(String namespaceURI)
- Specified by:
- lookupPrefix in interface Node
- Overrides:
- lookupPrefix in interface DomNode
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. As a consequence, this method updates the replacement tree ofEntityReference
nodes and normalizesText
nodes, as defined in the methodNode.normalize()
.
Otherwise, the actual result depends on the features being set on theDocument.domConfig
object and governing what operations actually take place. Noticeably this method could also make the document namespace well-formed according to the algorithm described in , check the character normalization, remove theCDATASection
nodes, etc. SeeDOMConfiguration
for details.// Keep in the document the information defined // in the XML Information Set (Java example) DOMConfiguration docConfig = myDocument.getDomConfig(); docConfig.setParameter("infoset", Boolean.TRUE); myDocument.normalizeDocument();
Mutation events, when supported, are generated to reflect the changes occurring on the document.
If errors occur during the invocation of this method, such as an attempt to update a read-only node or aNode.nodeName
contains an invalid character according to the XML version in use, errors or warnings (DOMError.SEVERITY_ERROR
orDOMError.SEVERITY_WARNING
) will be reported using theDOMErrorHandler
object associated with the "error-handler " parameter. Note this method might also report fatal errors (DOMError.SEVERITY_FATAL_ERROR
) if an implementation cannot recover from an error.
- Specified by:
- normalizeDocument in interface Document
- Since:
- DOM Level 3
public Node renameNode(Node n, String namespaceURI, String qualifiedName) throws DOMException
Rename an existing node of typeELEMENT_NODE
orATTRIBUTE_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.
If simply changing the name of the given node is not possible, the following operations are performed: a 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 anElement
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 attached to the new node.
When the node being renamed is anElement
only the specified attributes are moved, default attributes originated from the DTD are updated according to the new element name. In addition, the implementation may update default attributes from other schemas. Applications should useDocument.normalizeDocument()
to guarantee these attributes are up-to-date.
When the node being renamed is anAttr
that is attached to anElement
, the node is first removed from theElement
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,
- a user data event
NODE_RENAMED
is fired,- when the implementation supports the feature "MutationNameEvents", each mutation operation involved in this method fires the appropriate event, and in the end the event {
http://www.w3.org/2001/xml-events
,DOMElementNameChanged
} or {http://www.w3.org/2001/xml-events
,DOMAttributeNameChanged
} is fired.
- Specified by:
- renameNode in interface Document
- Parameters:
n
- The node to rename.namespaceURI
- The new namespace URI.qualifiedName
- 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:
DOMException
- NOT_SUPPORTED_ERR: Raised when the type of the specified node is neitherELEMENT_NODE
norATTRIBUTE_NODE
, or if the implementation does not support the renaming of the document element.
INVALID_CHARACTER_ERR: Raised if the new qualified name is not an XML name according to the XML version in use specified in theDocument.xmlVersion
attribute.
WRONG_DOCUMENT_ERR: Raised when the specified node was created from a different document than this document.
NAMESPACE_ERR: Raised if thequalifiedName
is a malformed qualified name, if thequalifiedName
has a prefix and thenamespaceURI
isnull
, or if thequalifiedName
has a prefix that is "xml" and thenamespaceURI
is different from " http://www.w3.org/XML/1998/namespace" [XML Namespaces] . Also raised, when the node being renamed is an attribute, if thequalifiedName
, or its prefix, is "xmlns" and thenamespaceURI
is different from "http://www.w3.org/2000/xmlns/".
- Since:
- DOM Level 3
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 interface DomNode
public void setBuilding(boolean flag)
Sets thebuilding
flag. Mutation events in the document are not reported.
public void setCheckWellformedness(boolean flag)
Sets whether to check for document well-formedness. If true, an exception will be raised if a second doctype or root element node is added to the document.
public void setDocumentURI(String documentURI)
The location of the document ornull
if undefined or if theDocument
was created usingDOMImplementation.createDocument
. No lexical checking is performed when setting this attribute; this could result in anull
value returned when usingNode.baseURI
.
Beware that when theDocument
supports the feature "HTML" [DOM Level 2 HTML] , the href attribute of the HTML BASE element takes precedence over this attribute when computingNode.baseURI
.
- Specified by:
- setDocumentURI in interface Document
- Since:
- DOM Level 3
public void setInputEncoding(String inputEncoding)
public void setStrictErrorChecking(boolean strictErrorChecking)
An attribute specifying whether error checking is enforced or not. When set tofalse
, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise anyDOMException
on DOM operations or report errors while usingDocument.normalizeDocument()
. In case of error, the behavior is undefined. This attribute istrue
by default.
- Specified by:
- setStrictErrorChecking in interface Document
- Since:
- DOM Level 3
public void setXmlEncoding(String encoding)
public void setXmlStandalone(boolean xmlStandalone)
An attribute specifying, as part of the XML declaration, whether this document is standalone. This isfalse
when unspecified. Note: No verification is done on the value when setting this attribute. Applications should useDocument.normalizeDocument()
with the "validate" parameter to verify if the value matches the validity constraint for standalone document declaration as defined in [XML 1.0].
- Specified by:
- setXmlStandalone in interface Document
- Since:
- DOM Level 3
public void setXmlVersion(String xmlVersion)
An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is"1.0"
. If this document does not support the "XML" feature, the value is alwaysnull
. Changing this attribute will affect methods that check for invalid characters in XML names. Application should invokeDocument.normalizeDocument()
in order to check for invalid characters in theNode
s that are already part of thisDocument
.
DOM applications may use theDOMImplementation.hasFeature(feature, version)
method with parameter values "XMLVersion" and "1.0" (respectively) to determine if an implementation supports [XML 1.0]. DOM applications may use the same method with parameter values "XMLVersion" and "1.1" (respectively) to determine if an implementation supports [XML 1.1]. In both cases, in order to support XML, an implementation must also support the "XML" feature defined in this specification.Document
objects supporting a version of the "XMLVersion" feature must not raise aNOT_SUPPORTED_ERR
exception for the same version number when usingDocument.xmlVersion
.
- Specified by:
- setXmlVersion in interface Document
- Since:
- DOM Level 3
public static void verifyXmlName(String name)
Deprecated. This method is deprecated and may be removed in future versions of GNU JAXP
Throws a DOM exception if the specified name is not a legal XML 1.0 Name.