org.w3c.dom.Document Maven / Gradle / Ivy
/*
* Copyright (c) 2000 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program 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 W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom;
/**
* 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 2 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. The DOM Level 2 does not support editing the
* Document Type Declaration. docType cannot be altered in
* any way, including through the use of methods inherited from the
* Node interface, such as insertNode or
* removeNode.
*/
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 root element of the document. For HTML documents,
* this is the element with the tagName "HTML".
*/
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. For HTML, the tagName
* parameter may be provided in any case, but it must be mapped to the
* canonical uppercase form 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.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 does not support any mechanism to
* resolve namespace prefixes.
* @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 with a
* given tag name in the order in which they are encountered in a
* preorder traversal of the Document tree.
* @param tagname The name of the tag to match on. The special value "*"
* matches all tags.
* @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 on a Node, the source
* node is not altered.
*
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 element
* are recursively imported and the resulting nodes reassembled 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
* Notation nodes since they never have any children.
* -
* PROCESSING_INSTRUCTION_NODE
* - The imported node copies its
*
target and data values from those of the
* source node.
* - 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.
*
* @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 Attr
* , EntityReference, and Notation 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.
* @since DOM Level 2
*/
public Node importNode(Node importedNode,
boolean deep)
throws DOMException;
/**
* Creates an element of the given qualified name and namespace URI.
* @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 qualified name
* contains an illegal character, per the XML 1.0 specification .
*
NAMESPACE_ERR: Raised if the qualifiedName is
* malformed per the Namespaces in XML specification, 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" .
*
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.
* @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 qualified name
* contains an illegal character, per the XML 1.0 specification .
*
NAMESPACE_ERR: Raised if the qualifiedName is
* malformed per the Namespaces in XML specification, 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", or if the
* qualifiedName, or its prefix, is "xmlns" and the
* namespaceURI is different from "
* http://www.w3.org/2000/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 the order in which they are
* encountered in a preorder traversal of the Document tree.
* @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 whose ID is given by
* elementId. If no such element exists, returns
* null. Behavior is not defined if more than one element
* has this ID. The DOM implementation must have
* information that says which attributes are of type ID. Attributes
* with the name "ID" are not of type ID unless so defined.
* Implementations that do not know whether attributes are of type ID or
* not are expected to return null.
* @param elementId The unique id value for an element.
* @return The matching element.
* @since DOM Level 2
*/
public Element getElementById(String elementId);
}