/* * 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 tagNameThe 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 dataThe data for the node. * @return The new Text object. */ public Text createTextNode(String data); /** * Creates a Comment node given the specified string. * @param dataThe 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 dataThe 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 targetThe target part of the processing instruction. * @param dataThe 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 nameThe 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 nameThe 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 tagnameThe 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.