org.w3c.dom.Document Maven / Gradle / Ivy
/*
* Copyright (c) 2003 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;
/**
* DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.
*
* 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.
*
See also the Document Object Model (DOM) Level 3 Core Specification.
*/
public interface Document extends Node {
/**
* The Document Type Declaration (see DocumentType)
* associated with this document. For HTML documents as well as XML
* documents without a document type declaration this returns
* null.
*
This provides direct access to the DocumentType node,
* child node of this Document. This node can be set at
* document creation time and later changed through the use of child
* nodes manipulation methods, such as insertBefore, or
* replaceChild. Note, however, that while some
* implementations may instantiate different types of
* Document objects supporting additional features than the
* "Core", such as "HTML" [DOM Level 2 HTML]
* , based on the DocumentType specified at creation time,
* changing it afterwards is very unlikely to result in a change of the
* features supported.
* @version DOM Level 3
*/
public DocumentType getDoctype();
/**
* The 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.
*
This attribute represents the property [document element] defined
* in [XML Information set]
* .
*/
public Element getDocumentElement();
/**
* Creates an element of the type specified. Note that the instance
* returned implements the Element interface, so attributes
* can be specified directly on the returned object.
*
In addition, if there are known attributes with default values,
* Attr nodes representing them are automatically created
* and attached to the element.
*
To create an element with a qualified name and namespace URI, use
* the createElementNS method.
* @param tagName The name of the element type to instantiate. For XML,
* this is case-sensitive, otherwise it depends on the case-sentivity
* 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 Element object with the
* nodeName attribute set to tagName, and
* localName, prefix, and
* namespaceURI set to null.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
*/
public Element createElement(String tagName)
throws DOMException;
/**
* Creates an empty DocumentFragment object.
* @return A new DocumentFragment.
*/
public DocumentFragment createDocumentFragment();
/**
* Creates a Text node given the specified string.
* @param data The data for the node.
* @return The new Text object.
*/
public Text createTextNode(String data);
/**
* Creates a Comment node given the specified string.
* @param data The data for the node.
* @return The new Comment object.
*/
public Comment createComment(String data);
/**
* Creates a CDATASection node whose value is the specified
* string.
* @param data The data for the CDATASection contents.
* @return The new CDATASection object.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public CDATASection createCDATASection(String data)
throws DOMException;
/**
* Creates a ProcessingInstruction node given the specified
* name and data strings.
* @param target The target part of the processing instruction.
* @param data The data for the node.
* @return The new ProcessingInstruction object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified target contains an
* illegal character.
*
NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public ProcessingInstruction createProcessingInstruction(String target,
String data)
throws DOMException;
/**
* Creates an Attr of the given name. Note that the
* Attr instance can then be set on an Element
* using the setAttributeNode method.
*
To create an attribute with a qualified name and namespace URI, use
* the createAttributeNS method.
* @param name The name of the attribute.
* @return A new Attr object with the nodeName
* attribute set to name, and localName,
* prefix, and namespaceURI set to
* null. The value of the attribute is the empty string.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
*/
public Attr createAttribute(String name)
throws DOMException;
/**
* Creates an EntityReference object. In addition, if the
* referenced entity is known, the child list of the
* EntityReference node is made the same as that of the
* corresponding Entity node.
*
Note: If any descendant of the Entity node has
* an unbound namespace prefix, the corresponding descendant of the
* created EntityReference node is also unbound; (its
* 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.
* @return The new EntityReference object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
*
NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
*/
public EntityReference createEntityReference(String name)
throws DOMException;
/**
* Returns a 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, this is case-sensitive, otherwise it
* depends on the case-sentivity of the markup language in use.
* @return A new NodeList object containing all the matched
* Elements.
*/
public NodeList getElementsByTagName(String tagname);
/**
* Imports a node from another document to this document. The returned
* node has no parent; (parentNode is null).
* The source node is not altered or removed from the original document;
* this method creates a new copy of the source node.
*
For all nodes, importing a node creates a node object owned by the
* importing document, with attribute values identical to the source
* node's nodeName and nodeType, plus the
* attributes related to namespaces (prefix,
* localName, and namespaceURI). As in the
* cloneNode operation, the source node is not altered.
* User data associated to the imported node is not carried over.
* However, if any UserDataHandlers has been specified
* along with the associated data these handlers will be called with the
* appropriate parameters before this method returns.
*
Additional information is copied as appropriate to the
* 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.
*
* - ATTRIBUTE_NODE
* - The
ownerElement attribute
* is set to null and the specified flag is
* set to true on the generated Attr. The
* descendants of the source Attr are recursively imported
* and the resulting nodes reassembled to form the corresponding subtree.
* Note that the deep parameter has no effect on
* Attr nodes; they always carry their children with them
* when imported.
* - DOCUMENT_FRAGMENT_NODE
* - If the
deep option
* was set to true, the descendants of the source
* DocumentFragment are recursively imported and the
* resulting nodes reassembled under the imported
* DocumentFragment to form the corresponding subtree.
* Otherwise, this simply generates an empty
* DocumentFragment.
* - DOCUMENT_NODE
* Document
* nodes cannot be imported.- DOCUMENT_TYPE_NODE
* DocumentType
* nodes cannot be imported.- ELEMENT_NODE
* - Specified attribute nodes of the source element are imported, and the generated
*
Attr nodes are attached to the generated
* 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
* importNode deep parameter was set to
* true, the descendants of the source element are
* recursively imported and the resulting nodes reassembled to form the
* corresponding subtree.
* - ENTITY_NODE
* Entity nodes can be
* imported, however in the current release of the DOM the
* DocumentType is readonly. Ability to add these imported
* nodes to a DocumentType will be considered for addition
* to a future release of the DOM.On import, the publicId,
* systemId, and notationName attributes are
* copied. If a deep import is requested, the descendants
* of the the source Entity are recursively imported and
* the resulting nodes reassembled to form the corresponding subtree.-
* ENTITY_REFERENCE_NODE
* - Only the
EntityReference itself is
* copied, even if a 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.
* - NOTATION_NODE
* -
*
Notation nodes can be imported, however in the current
* release of the DOM the DocumentType is readonly. Ability
* to add these imported nodes to a DocumentType will be
* considered for addition to a future release of the DOM.On import, the
* publicId and systemId attributes are copied.
* Note that the deep parameter has no effect on this type
* of nodes since they cannot have any children.
* -
* PROCESSING_INSTRUCTION_NODE
* - The imported node copies its
*
target and data values from those of the
* source node.Note that the deep parameter has no effect
* on this type of nodes since they cannot have any children.
* - TEXT_NODE,
* CDATA_SECTION_NODE, COMMENT_NODE
* - These three types of nodes inheriting
* from
CharacterData copy their data and
* length attributes from those of the source node.Note
* that the deep parameter has no effect on these types of
* nodes since they cannot have any children.
*
* @param importedNode The node to import.
* @param deep If true, recursively import the subtree under
* the specified node; if false, import only the node
* itself, as explained above. This has no effect on nodes that cannot
* have any children, and on Attr, and
* EntityReference nodes.
* @return The imported node that belongs to this Document.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
* supported.
*
INVALID_CHARACTER_ERR: Raised if one the imported names contain
* an illegal character. This may happen when importing an XML 1.1 [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.
*
Per [XML Namespaces]
* , applications must use the value 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 Element object with the following
* attributes:
*
*
* Attribute
* Value
*
*
* Node.nodeName
* qualifiedName
*
*
* Node.namespaceURI
* namespaceURI
*
*
* Node.prefixprefix, extracted
* from qualifiedName, or null if there is
* no prefix
*
*
* Node.localNamelocal name, extracted from
* qualifiedName
*
*
* Element.tagName
* qualifiedName
*
*
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified
* qualifiedName contains an illegal character.
*
NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the qualifiedName has a
* prefix and the namespaceURI is null, or
* if the qualifiedName has a prefix that is "xml" and
* the namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace" [XML Namespaces]
* , or if the qualifiedName or its prefix is "xmlns" and
* the 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".
*
NOT_SUPPORTED_ERR: Always thrown if the current document does not
* support the "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.
*
Per [XML Namespaces]
* , applications must use the value null as the
* 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 Attr object with the following attributes:
*
*
*
* Attribute
* Value
*
*
* Node.nodeNamequalifiedName
*
*
*
* Node.namespaceURI
* namespaceURI
*
*
* Node.prefix
* prefix, extracted from
* qualifiedName, or null if there is no
* prefix
*
*
* Node.localNamelocal name, extracted from
* qualifiedName
*
*
* Attr.name
* qualifiedName
*
*
* Node.nodeValuethe empty
* string
*
*
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified
* qualifiedName contains an illegal character.
*
NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the qualifiedName has a
* prefix and the namespaceURI is null, if
* the qualifiedName has a prefix that is "xml" and the
* namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace", if the qualifiedName or its prefix is "xmlns" and the
* 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".
*
NOT_SUPPORTED_ERR: Always thrown if the current document does not
* support the "XML" feature, since namespaces were
* defined by XML.
* @since DOM Level 2
*/
public Attr createAttributeNS(String namespaceURI,
String qualifiedName)
throws DOMException;
/**
* Returns a 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 "*" matches all namespaces.
* @param localName The local name of the elements to match on. The
* special value "*" matches all local names.
* @return A new NodeList object containing all the matched
* Elements.
* @since DOM Level 2
*/
public NodeList getElementsByTagNameNS(String namespaceURI,
String localName);
/**
* Returns the Element that has an ID attribute with the
* given value. If no such element exists, this returns null
* . If more than one element has an ID attribute with that value, what
* is returned is undefined.
*
The DOM implementation needs to have information that says which
* attributes are of type ID. This information can come from validating
* the document against a grammar or from the use of the
* setIdAttribute method and its siblings on
* Element. To query whether an attribute is of type ID see
* isId on Attr.
* Note: Attributes with the name "ID" or "id" are not of type
* ID unless so defined.
* @param elementId The unique id value for an element.
* @return The matching element or null if there is none.
* @since DOM Level 2
*/
public Element getElementById(String elementId);
/**
* An attribute specifying the actual encoding of this document. This is
* null otherwise.
*
This attribute represents the property [character encoding scheme]
* defined in [XML Information set]
* .
* @since DOM Level 3
*/
public 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 [XML Information set]
* .
* @since DOM Level 3
*/
public void setActualEncoding(String actualEncoding);
/**
* An attribute specifying, as part of the XML declaration, the encoding
* of this document. This is null when unspecified.
* @since DOM Level 3
*/
public 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
*/
public void setEncoding(String encoding);
/**
* An attribute specifying, as part of the XML declaration, whether this
* document is standalone.
*
This attribute represents the property [standalone] defined in [XML Information set]
* .
* @since DOM Level 3
*/
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 [XML Information set]
* .
* @since DOM Level 3
*/
public void setStandalone(boolean standalone);
/**
* 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 [XML Information set]
* .
* @since DOM Level 3
*/
public 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 [XML Information set]
* .
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the version is set to a value that is
* not supported by this Document.
* @since DOM Level 3
*/
public void setVersion(String version)
throws DOMException;
/**
* An attribute specifying whether error 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 default.
* @since DOM Level 3
*/
public boolean getStrictErrorChecking();
/**
* An attribute specifying whether error 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 default.
* @since DOM Level 3
*/
public void setStrictErrorChecking(boolean strictErrorChecking);
/**
* The location of the document or null if undefined.
*
Beware that when the Document supports the feature
* "HTML" [DOM Level 2 HTML]
* , the href attribute of the HTML BASE element takes precedence over
* this attribute.
* @since DOM Level 3
*/
public String getDocumentURI();
/**
* The location of the document or null if undefined.
*
Beware that when the Document supports the feature
* "HTML" [DOM Level 2 HTML]
* , the href attribute of the HTML BASE element takes precedence over
* this attribute.
* @since DOM Level 3
*/
public void setDocumentURI(String documentURI);
/**
* 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.
* @param source The node to move into this document.
* @return The adopted node, or 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
* DOCUMENT, DOCUMENT_TYPE.
*
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 Document.normalizeDocument is
* invoked.
* @since DOM Level 3
*/
public DOMConfiguration getConfig();
/**
* 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 DOMConfiguration for details.
*
Noticeably this method normalizes Text nodes, makes
* the document "namespace wellformed", according to the algorithm
* described in , by adding missing namespace declaration attributes and
* adding or changing namespace prefixes, updates the replacement tree
* of EntityReference nodes, normalizes attribute values,
* etc.
*
Mutation events, when supported, are generated to reflect the
* changes occuring on the document.
*
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?Mutation events are fired
* as expected. (F2F 28 Feb 2002).
* @since DOM Level 3
*/
public void normalizeDocument();
/**
* Rename an existing node of type ELEMENT_NODE or
* ATTRIBUTE_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 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
* attached to the new node.
*
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 normalizeDocument() to guarantee these
* attributes are up-to-date.
*
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,
*
* - a user data event
NODE_RENAMED is fired,
*
* -
* when the implementation supports the feature "MutationEvents", each
* mutation operation involved in this method fires the appropriate
* event, and in the end the event
DOMElementNameChanged or
* DOMAttributeNameChanged is fired.
*
*
Should this throw a
* HIERARCHY_REQUEST_ERR?No. (F2F 28 Feb 2002).
* @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 ELEMENT_NODE nor ATTRIBUTE_NODE,
* or if the implementation does not support the renaming of the
* document element.
*
WRONG_DOCUMENT_ERR: Raised when the specified node was created
* from a different document than this document.
*
NAMESPACE_ERR: Raised if the qualifiedName is a
* malformed qualified name, if the qualifiedName has a
* prefix and the namespaceURI is null, or
* if the qualifiedName has a prefix that is "xml" and
* the namespaceURI is different from "
* http://www.w3.org/XML/1998/namespace" [XML Namespaces]
* . Also raised, when the node being renamed is an attribute, if the
* qualifiedName, or its prefix, is "xmlns" and the
* 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;
}