|
|
The Document.java Java example source code
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* This file is available under and governed by the GNU General Public
* License version 2 only, as published by the Free Software Foundation.
* However, the following notice accompanied the original version of this
* file and, per its terms, should not be removed:
*
* Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
* work is distributed under the W3C(r) Software License [1] in the hope that
* it will be useful, but WITHOUT ANY WARRANTY; without even the implied
* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
*
* [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
*/
package org.w3c.dom;
/**
* The <code>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.
* <p>Since elements, text nodes, comments, processing instructions, etc.
* cannot exist outside the context of a <code>Document, the
* <code>Document interface also contains the factory methods needed
* to create these objects. The <code>Node objects created have a
* <code>ownerDocument attribute which associates them with the
* <code>Document within whose context they were created.
* <p>See also the Document Object Model (DOM) Level 3 Core Specification.
*/
public interface Document extends Node {
/**
* The Document Type Declaration (see <code>DocumentType)
* associated with this document. For XML documents without a document
* type declaration this returns <code>null. For HTML documents,
* a <code>DocumentType object may be returned, independently of
* the presence or absence of document type declaration in the HTML
* document.
* <br>This provides direct access to the DocumentType node,
* child node of this <code>Document. This node can be set at
* document creation time and later changed through the use of child
* nodes manipulation methods, such as <code>Node.insertBefore,
* or <code>Node.replaceChild. Note, however, that while some
* implementations may instantiate different types of
* <code>Document objects supporting additional features than the
* "Core", such as "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML]
* , based on the <code>DocumentType specified at creation time,
* changing it afterwards is very unlikely to result in a change of the
* features supported.
*
* @since DOM Level 3
*/
public DocumentType getDoctype();
/**
* The <code>DOMImplementation object that handles this document. A
* DOM application may use objects from multiple implementations.
*/
public DOMImplementation getImplementation();
/**
* This is a convenience attribute that allows direct access to the child
* node that is the document element of the document.
*/
public Element getDocumentElement();
/**
* Creates an element of the type specified. Note that the instance
* returned implements the <code>Element interface, so attributes
* can be specified directly on the returned object.
* <br>In addition, if there are known attributes with default values,
* <code>Attr nodes representing them are automatically created
* and attached to the element.
* <br>To create an element with a qualified name and namespace URI, use
* the <code>createElementNS method.
* @param tagName The name of the element type to instantiate. For XML,
* this is case-sensitive, otherwise it depends on the
* case-sensitivity of the markup language in use. In that case, the
* name is mapped to the canonical form of that markup by the DOM
* implementation.
* @return A new <code>Element object with the
* <code>nodeName attribute set to tagName, and
* <code>localName, prefix, and
* <code>namespaceURI set to null.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
* name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute.
*/
public Element createElement(String tagName)
throws DOMException;
/**
* Creates an empty <code>DocumentFragment object.
* @return A new <code>DocumentFragment.
*/
public DocumentFragment createDocumentFragment();
/**
* Creates a <code>Text node given the specified string.
* @param data The data for the node.
* @return The new <code>Text object.
*/
public Text createTextNode(String data);
/**
* Creates a <code>Comment node given the specified string.
* @param data The data for the node.
* @return The new <code>Comment object.
*/
public Comment createComment(String data);
/**
* Creates a <code>CDATASection node whose value is the specified
* string.
* @param data The data for the <code>CDATASection contents.
* @return The new <code>CDATASection object.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public CDATASection createCDATASection(String data)
throws DOMException;
/**
* Creates a <code>ProcessingInstruction node given the specified
* name and data strings.
* @param target The target part of the processing instruction.Unlike
* <code>Document.createElementNS or
* <code>Document.createAttributeNS, no namespace well-formed
* checking is done on the target name. Applications should invoke
* <code>Document.normalizeDocument() with the parameter "
* namespaces" set to <code>true in order to ensure that the
* target name is namespace well-formed.
* @param data The data for the node.
* @return The new <code>ProcessingInstruction object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified target is not an XML
* name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute.
* <br>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public ProcessingInstruction createProcessingInstruction(String target,
String data)
throws DOMException;
/**
* Creates an <code>Attr of the given name. Note that the
* <code>Attr instance can then be set on an Element
* using the <code>setAttributeNode method.
* <br>To create an attribute with a qualified name and namespace URI, use
* the <code>createAttributeNS method.
* @param name The name of the attribute.
* @return A new <code>Attr object with the nodeName
* attribute set to <code>name, and localName,
* <code>prefix, and namespaceURI set to
* <code>null. The value of the attribute is the empty string.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
* name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute.
*/
public Attr createAttribute(String name)
throws DOMException;
/**
* Creates an <code>EntityReference object. In addition, if the
* referenced entity is known, the child list of the
* <code>EntityReference node is made the same as that of the
* corresponding <code>Entity node.
* <p >Note: If any descendant of the Entity node has
* an unbound namespace prefix, the corresponding descendant of the
* created <code>EntityReference node is also unbound; (its
* <code>namespaceURI is null). The DOM Level 2 and
* 3 do not support any mechanism to resolve namespace prefixes in this
* case.
* @param name The name of the entity to reference.Unlike
* <code>Document.createElementNS or
* <code>Document.createAttributeNS, no namespace well-formed
* checking is done on the entity name. Applications should invoke
* <code>Document.normalizeDocument() with the parameter "
* namespaces" set to <code>true in order to ensure that the
* entity name is namespace well-formed.
* @return The new <code>EntityReference object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
* name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute.
* <br>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public EntityReference createEntityReference(String name)
throws DOMException;
/**
* Returns a <code>NodeList of all the Elements in
* document order with a given tag name and are contained in the
* document.
* @param tagname The name of the tag to match on. The special value "*"
* matches all tags. For XML, the <code>tagname parameter is
* case-sensitive, otherwise it depends on the case-sensitivity of the
* markup language in use.
* @return A new <code>NodeList object containing all the matched
* <code>Elements.
*/
public NodeList getElementsByTagName(String tagname);
/**
* Imports a node from another document to this document, without altering
* or removing the source node from the original document; this method
* creates a new copy of the source node. The returned node has no
* parent; (<code>parentNode is null).
* <br>For all nodes, importing a node creates a node object owned by the
* importing document, with attribute values identical to the source
* node's <code>nodeName and nodeType, plus the
* attributes related to namespaces (<code>prefix,
* <code>localName, and namespaceURI). As in the
* <code>cloneNode operation, the source node is not altered.
* User data associated to the imported node is not carried over.
* However, if any <code>UserDataHandlers has been specified
* along with the associated data these handlers will be called with the
* appropriate parameters before this method returns.
* <br>Additional information is copied as appropriate to the
* <code>nodeType, attempting to mirror the behavior expected if
* a fragment of XML or HTML source was copied from one document to
* another, recognizing that the two documents may have different DTDs
* in the XML case. The following list describes the specifics for each
* type of node.
* <dl>
* <dt>ATTRIBUTE_NODE
* <dd>The ownerElement attribute
* is set to <code>null and the specified flag is
* set to <code>true on the generated Attr. The
* descendants of the source <code>Attr are recursively imported
* and the resulting nodes reassembled to form the corresponding subtree.
* Note that the <code>deep parameter has no effect on
* <code>Attr nodes; they always carry their children with them
* when imported.</dd>
* <dt>DOCUMENT_FRAGMENT_NODE
* <dd>If the deep option
* was set to <code>true, the descendants of the source
* <code>DocumentFragment are recursively imported and the
* resulting nodes reassembled under the imported
* <code>DocumentFragment to form the corresponding subtree.
* Otherwise, this simply generates an empty
* <code>DocumentFragment.
* <dt>DOCUMENT_NODE
* <dd>Document
* nodes cannot be imported.</dd>
* <dt>DOCUMENT_TYPE_NODE
* <dd>DocumentType
* nodes cannot be imported.</dd>
* <dt>ELEMENT_NODE
* <dd>Specified attribute nodes of the source element are imported, and the generated
* <code>Attr nodes are attached to the generated
* <code>Element. Default attributes are not copied, though if the document being imported into defines default
* attributes for this element name, those are assigned. If the
* <code>importNode deep parameter was set to
* <code>true, the descendants of the source element are
* recursively imported and the resulting nodes reassembled to form the
* corresponding subtree.</dd>
* <dt>ENTITY_NODE
* <dd>Entity nodes can be
* imported, however in the current release of the DOM the
* <code>DocumentType is readonly. Ability to add these imported
* nodes to a <code>DocumentType will be considered for addition
* to a future release of the DOM.On import, the <code>publicId,
* <code>systemId, and notationName attributes are
* copied. If a <code>deep import is requested, the descendants
* of the the source <code>Entity are recursively imported and
* the resulting nodes reassembled to form the corresponding subtree.</dd>
* <dt>
* ENTITY_REFERENCE_NODE</dt>
* <dd>Only the EntityReference itself is
* copied, even if a <code>deep import is requested, 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.</dd>
* <dt>NOTATION_NODE
* <dd>
* <code>Notation nodes can be imported, however in the current
* release of the DOM the <code>DocumentType is readonly. Ability
* to add these imported nodes to a <code>DocumentType will be
* considered for addition to a future release of the DOM.On import, the
* <code>publicId and systemId attributes are copied.
* Note that the <code>deep parameter has no effect on this type
* of nodes since they cannot have any children.</dd>
* <dt>
* PROCESSING_INSTRUCTION_NODE</dt>
* <dd>The imported node copies its
* <code>target and data values from those of the
* source node.Note that the <code>deep parameter has no effect
* on this type of nodes since they cannot have any children.</dd>
* <dt>TEXT_NODE,
* CDATA_SECTION_NODE, COMMENT_NODE</dt>
* <dd>These three types of nodes inheriting
* from <code>CharacterData copy their data and
* <code>length attributes from those of the source node.Note
* that the <code>deep parameter has no effect on these types of
* nodes since they cannot have any children.</dd>
* </dl>
* @param importedNode The node to import.
* @param deep If <code>true, recursively import the subtree under
* the specified node; if <code>false, import only the node
* itself, as explained above. This has no effect on nodes that cannot
* have any children, and on <code>Attr, and
* <code>EntityReference nodes.
* @return The imported node that belongs to this <code>Document.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
* supported.
* <br>INVALID_CHARACTER_ERR: Raised if one of the imported names is not
* an XML name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute. This may happen when
* importing an XML 1.1 [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1] element
* into an XML 1.0 document, for instance.
* @since DOM Level 2
*/
public Node importNode(Node importedNode,
boolean deep)
throws DOMException;
/**
* Creates an element of the given qualified name and namespace URI.
* <br>Per [XML Namespaces]
* , applications must use the value <code>null as the
* namespaceURI parameter for methods if they wish to have no namespace.
* @param namespaceURI The namespace URI of the element to create.
* @param qualifiedName The qualified name of the element type to
* instantiate.
* @return A new <code>Element object with the following
* attributes:
* <table border='1' cellpadding='3'>
* <tr>
* <th>Attribute
* <th>Value
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.nodeName |
* <td valign='top' rowspan='1' colspan='1'>
* <code>qualifiedName
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.namespaceURI
* <td valign='top' rowspan='1' colspan='1'>
* <code>namespaceURI
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.prefix
* <td valign='top' rowspan='1' colspan='1'>prefix, extracted
* from <code>qualifiedName, or null if there is
* no prefix</td>
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.localName
* <td valign='top' rowspan='1' colspan='1'>local name, extracted from
* <code>qualifiedName
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Element.tagName
* <td valign='top' rowspan='1' colspan='1'>
* <code>qualifiedName
* </tr>
* </table>
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified
* <code>qualifiedName is not an XML name according to the XML
* version in use specified in the <code>Document.xmlVersion
* attribute.
* <br>NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the <code>qualifiedName has a
* prefix and the <code>namespaceURI is null, or
* if the <code>qualifiedName has a prefix that is "xml" and
* the <code>namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace</a>" [XML Namespaces]
* , or if the <code>qualifiedName or its prefix is "xmlns" and
* the <code>namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".
* <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
* support the <code>"XML" feature, since namespaces were
* defined by XML.
* @since DOM Level 2
*/
public Element createElementNS(String namespaceURI,
String qualifiedName)
throws DOMException;
/**
* Creates an attribute of the given qualified name and namespace URI.
* <br>Per [XML Namespaces]
* , applications must use the value <code>null as the
* <code>namespaceURI parameter for methods if they wish to have
* no namespace.
* @param namespaceURI The namespace URI of the attribute to create.
* @param qualifiedName The qualified name of the attribute to
* instantiate.
* @return A new <code>Attr object with the following attributes:
* <table border='1' cellpadding='3'>
* <tr>
* <th>
* Attribute</th>
* <th>Value
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.nodeName
* <td valign='top' rowspan='1' colspan='1'>qualifiedName
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>
* <code>Node.namespaceURI
* <td valign='top' rowspan='1' colspan='1'>namespaceURI
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>
* <code>Node.prefix
* <td valign='top' rowspan='1' colspan='1'>prefix, extracted from
* <code>qualifiedName, or null if there is no
* prefix</td>
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.localName
* <td valign='top' rowspan='1' colspan='1'>local name, extracted from
* <code>qualifiedName
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Attr.name
* <td valign='top' rowspan='1' colspan='1'>
* <code>qualifiedName
* </tr>
* <tr>
* <td valign='top' rowspan='1' colspan='1'>Node.nodeValue
* <td valign='top' rowspan='1' colspan='1'>the empty
* string</td>
* </tr>
* </table>
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified
* <code>qualifiedName is not an XML name according to the XML
* version in use specified in the <code>Document.xmlVersion
* attribute.
* <br>NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the <code>qualifiedName has a
* prefix and the <code>namespaceURI is null, if
* the <code>qualifiedName has a prefix that is "xml" and the
* <code>namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace</a>", if the qualifiedName or its prefix is "xmlns" and the
* <code>namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".
* <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
* support the <code>"XML" feature, since namespaces were
* defined by XML.
* @since DOM Level 2
*/
public Attr createAttributeNS(String namespaceURI,
String qualifiedName)
throws DOMException;
/**
* Returns a <code>NodeList of all the Elements with a
* given local name and namespace URI in document order.
* @param namespaceURI The namespace URI of the elements to match on. The
* special value <code>"*" matches all namespaces.
* @param localName The local name of the elements to match on. The
* special value "*" matches all local names.
* @return A new <code>NodeList object containing all the matched
* <code>Elements.
* @since DOM Level 2
*/
public NodeList getElementsByTagNameNS(String namespaceURI,
String localName);
/**
* Returns the <code>Element that has an ID attribute with the
* given value. If no such element exists, this returns <code>null
* . If more than one element has an ID attribute with that value, what
* is returned is undefined.
* <br> The DOM implementation is expected to use the attribute
* <code>Attr.isId to determine if an attribute is of type ID.
* <p >Note: Attributes with the name "ID" or "id" are not of type
* ID unless so defined.
* @param elementId The unique <code>id value for an element.
* @return The matching element or <code>null if there is none.
* @since DOM Level 2
*/
public Element getElementById(String elementId);
/**
* An attribute specifying the encoding used for this document at the time
* of the parsing. This is <code>null when it is not known, such
* as when the <code>Document was created in memory.
* @since DOM Level 3
*/
public String getInputEncoding();
/**
* An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration, the encoding of this document. This is null when
* unspecified or when it is not known, such as when the
* <code>Document was created in memory.
* @since DOM Level 3
*/
public String getXmlEncoding();
/**
* An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration, whether this document is standalone. This is false when
* unspecified.
* <p >Note: No verification is done on the value when setting
* this attribute. Applications should use
* <code>Document.normalizeDocument() with the "validate"
* parameter to verify if the value matches the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#sec-rmd'>validity
* constraint for standalone document declaration</a> as defined in [XML 1.0].
* @since DOM Level 3
*/
public boolean getXmlStandalone();
/**
* An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration, whether this document is standalone. This is false when
* unspecified.
* <p >Note: No verification is done on the value when setting
* this attribute. Applications should use
* <code>Document.normalizeDocument() with the "validate"
* parameter to verify if the value matches the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#sec-rmd'>validity
* constraint for standalone document declaration</a> as defined in [XML 1.0].
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if this document does not support the
* "XML" feature.
* @since DOM Level 3
*/
public void setXmlStandalone(boolean xmlStandalone)
throws DOMException;
/**
* An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration, the version number of this document. If there is no declaration and if
* this document supports the "XML" feature, the value is
* <code>"1.0". If this document does not support the "XML"
* feature, the value is always <code>null. Changing this
* attribute will affect methods that check for invalid characters in
* XML names. Application should invoke
* <code>Document.normalizeDocument() in order to check for
* invalid characters in the <code>Nodes that are already part of
* this <code>Document.
* <br> DOM applications may use the
* <code>DOMImplementation.hasFeature(feature, version) method
* with parameter values "XMLVersion" and "1.0" (respectively) to
* determine if an implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0]. DOM
* applications may use the same method with parameter values
* "XMLVersion" and "1.1" (respectively) to determine if an
* implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1]. In both
* cases, in order to support XML, an implementation must also support
* the "XML" feature defined in this specification. <code>Document
* objects supporting a version of the "XMLVersion" feature must not
* raise a <code>NOT_SUPPORTED_ERR exception for the same version
* number when using <code>Document.xmlVersion.
* @since DOM Level 3
*/
public String getXmlVersion();
/**
* An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration, the version number of this document. If there is no declaration and if
* this document supports the "XML" feature, the value is
* <code>"1.0". If this document does not support the "XML"
* feature, the value is always <code>null. Changing this
* attribute will affect methods that check for invalid characters in
* XML names. Application should invoke
* <code>Document.normalizeDocument() in order to check for
* invalid characters in the <code>Nodes that are already part of
* this <code>Document.
* <br> DOM applications may use the
* <code>DOMImplementation.hasFeature(feature, version) method
* with parameter values "XMLVersion" and "1.0" (respectively) to
* determine if an implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0]. DOM
* applications may use the same method with parameter values
* "XMLVersion" and "1.1" (respectively) to determine if an
* implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1]. In both
* cases, in order to support XML, an implementation must also support
* the "XML" feature defined in this specification. <code>Document
* objects supporting a version of the "XMLVersion" feature must not
* raise a <code>NOT_SUPPORTED_ERR exception for the same version
* number when using <code>Document.xmlVersion.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the version is set to a value that is
* not supported by this <code>Document or if this document
* does not support the "XML" feature.
* @since DOM Level 3
*/
public void setXmlVersion(String xmlVersion)
throws DOMException;
/**
* An attribute specifying whether error checking is enforced or not. When
* set to <code>false, the implementation is free to not test
* every possible error case normally defined on DOM operations, and not
* raise any <code>DOMException on DOM operations or report
* errors while using <code>Document.normalizeDocument(). In case
* of error, the behavior is undefined. This attribute is
* <code>true by default.
* @since DOM Level 3
*/
public boolean getStrictErrorChecking();
/**
* An attribute specifying whether error checking is enforced or not. When
* set to <code>false, the implementation is free to not test
* every possible error case normally defined on DOM operations, and not
* raise any <code>DOMException on DOM operations or report
* errors while using <code>Document.normalizeDocument(). In case
* of error, the behavior is undefined. This attribute is
* <code>true by default.
* @since DOM Level 3
*/
public void setStrictErrorChecking(boolean strictErrorChecking);
/**
* The location of the document or <code>null if undefined or if
* the <code>Document was created using
* <code>DOMImplementation.createDocument. No lexical checking is
* performed when setting this attribute; this could result in a
* <code>null value returned when using Node.baseURI
* .
* <br> Beware that when the Document supports the feature
* "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML]
* , the href attribute of the HTML BASE element takes precedence over
* this attribute when computing <code>Node.baseURI.
* @since DOM Level 3
*/
public String getDocumentURI();
/**
* The location of the document or <code>null if undefined or if
* the <code>Document was created using
* <code>DOMImplementation.createDocument. No lexical checking is
* performed when setting this attribute; this could result in a
* <code>null value returned when using Node.baseURI
* .
* <br> Beware that when the Document supports the feature
* "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML]
* , the href attribute of the HTML BASE element takes precedence over
* this attribute when computing <code>Node.baseURI.
* @since DOM Level 3
*/
public void setDocumentURI(String documentURI);
/**
* Attempts to adopt a node from another document to this document. If
* supported, it changes the <code>ownerDocument 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 (unlike <code>importNode() which
* create a copy of the source node instead of moving it). When it
* fails, applications should use <code>Document.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.
* <dl>
* <dt>ATTRIBUTE_NODE
* <dd>The
* <code>ownerElement attribute is set to null and
* the <code>specified flag is set to true on the
* adopted <code>Attr. The descendants of the source
* <code>Attr are recursively adopted.
* <dt>DOCUMENT_FRAGMENT_NODE
* <dd>The
* descendants of the source node are recursively adopted.</dd>
* <dt>DOCUMENT_NODE
* <dd>
* <code>Document nodes cannot be adopted.
* <dt>DOCUMENT_TYPE_NODE
* <dd>
* <code>DocumentType nodes cannot be adopted.
* <dt>ELEMENT_NODE
* <dd>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.</dd>
* <dt>ENTITY_NODE
* <dd>
* <code>Entity nodes cannot be adopted.
* <dt>ENTITY_REFERENCE_NODE
* <dd>Only
* the <code>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.</dd>
* <dt>NOTATION_NODE
* <dd>Notation nodes cannot be
* adopted.</dd>
* <dt>PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE,
* COMMENT_NODE</dt>
* <dd>These nodes can all be adopted. No specifics.
* </dl>
* <p >Note: Since it does not create new nodes unlike the
* <code>Document.importNode() method, this method does not raise
* an <code>INVALID_CHARACTER_ERR exception, and applications
* should use the <code>Document.normalizeDocument() method to
* check if an imported name is not an XML name according to the XML
* version in use.
* @param source The node to move into this document.
* @return The adopted node, or <code>null if this operation
* fails, such as when the source node comes from a different
* implementation.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the source node is of type
* <code>DOCUMENT, DOCUMENT_TYPE.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is
* readonly.
* @since DOM Level 3
*/
public Node adoptNode(Node source)
throws DOMException;
/**
* The configuration used when <code>Document.normalizeDocument()
* is invoked.
* @since DOM Level 3
*/
public DOMConfiguration getDomConfig();
/**
* 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 of
* <code>EntityReference nodes and normalizes Text
* nodes, as defined in the method <code>Node.normalize().
* <br> Otherwise, the actual result depends on the features being set on
* the <code>Document.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 the
* <code>CDATASection nodes, etc. See
* <code>DOMConfiguration for details.
* <pre>// 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();</pre>
*
* <br>Mutation events, when supported, are generated to reflect the
* changes occurring on the document.
* <br> If errors occur during the invocation of this method, such as an
* attempt to update a read-only node or a <code>Node.nodeName
* contains an invalid character according to the XML version in use,
* errors or warnings (<code>DOMError.SEVERITY_ERROR or
* <code>DOMError.SEVERITY_WARNING) will be reported using the
* <code>DOMErrorHandler object associated with the "error-handler
* " parameter. Note this method might also report fatal errors (
* <code>DOMError.SEVERITY_FATAL_ERROR) if an implementation
* cannot recover from an error.
* @since DOM Level 3
*/
public void normalizeDocument();
/**
* Rename an existing node of type <code>ELEMENT_NODE or
* <code>ATTRIBUTE_NODE.
* <br>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.
* <br>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 an <code>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
* attached to the new node.
* <br>When the node being renamed is an Element 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 use <code>Document.normalizeDocument() to
* guarantee these attributes are up-to-date.
* <br>When the node being renamed is an Attr that is
* attached to an <code>Element, the node is first removed from
* the <code>Element attributes map. Then, once renamed, either
* by modifying the existing node or creating a new one as described
* above, it is put back.
* <br>In addition,
* <ul>
* <li> a user data event NODE_RENAMED is fired,
* </li>
* <li>
* when the implementation supports the feature "MutationNameEvents",
* each mutation operation involved in this method fires the appropriate
* event, and in the end the event {
* <code>http://www.w3.org/2001/xml-events,
* <code>DOMElementNameChanged} or {
* <code>http://www.w3.org/2001/xml-events,
* <code>DOMAttributeNameChanged} is fired.
* </li>
* </ul>
* @param n The node to rename.
* @param namespaceURI The new namespace URI.
* @param qualifiedName The new qualified name.
* @return The renamed node. This is either the specified node or the new
* node that was created to replace the specified node.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised when the type of the specified node is
* neither <code>ELEMENT_NODE nor ATTRIBUTE_NODE,
* or if the implementation does not support the renaming of the
* document element.
* <br>INVALID_CHARACTER_ERR: Raised if the new qualified name is not an
* XML name according to the XML version in use specified in the
* <code>Document.xmlVersion attribute.
* <br>WRONG_DOCUMENT_ERR: Raised when the specified node was created
* from a different document than this document.
* <br>NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the <code>qualifiedName has a
* prefix and the <code>namespaceURI is null, or
* if the <code>qualifiedName has a prefix that is "xml" and
* the <code>namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace</a>" [XML Namespaces]
* . Also raised, when the node being renamed is an attribute, if the
* <code>qualifiedName, or its prefix, is "xmlns" and the
* <code>namespaceURI is different from "http://www.w3.org/2000/xmlns/".
* @since DOM Level 3
*/
public Node renameNode(Node n,
String namespaceURI,
String qualifiedName)
throws DOMException;
}
Other Java examples (source code examples)
Here is a short list of links related to this Java Document.java source code file:
The search page
Other Java source code examples at this package level
Click here to learn more about this project
