/* * Copyright (c) 2003 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.html2; import org.w3c.dom.Document; import org.w3c.dom.NodeList; import org.w3c.dom.DOMException; /** * An HTMLDocument is the root of the HTML hierarchy and holds * the entire content. Besides providing access to the hierarchy, it also * provides some convenience methods for accessing certain sets of * information from the document. *

The following properties have been deprecated in favor of the * corresponding ones for the BODY element:alinkColorbackground * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method * getElementById is inherited from the Document * interface where it was moved to. *

See also the Document Object Model (DOM) Level 2 HTML Specification. */ public interface HTMLDocument extends Document { /** * The title of a document as specified by the TITLE element * in the head of the document. */ public String getTitle(); /** * The title of a document as specified by the TITLE element * in the head of the document. */ public void setTitle(String title); /** * Returns the URI [IETF RFC 2396] of the page that linked to this page. The value is an * empty string if the user navigated to the page directly (not through * a link, but, for example, via a bookmark). */ public String getReferrer(); /** * The domain name of the server that served the document, or * null if the server cannot be identified by a domain * name. */ public String getDomain(); /** * The absolute URI [IETF RFC 2396] of the document. */ public String getURL(); /** * The element that contains the content for the document. In documents * with BODY contents, returns the BODY * element. In frameset documents, this returns the outermost * FRAMESET element. */ public HTMLElement getBody(); /** * The element that contains the content for the document. In documents * with BODY contents, returns the BODY * element. In frameset documents, this returns the outermost * FRAMESET element. */ public void setBody(HTMLElement body); /** * A collection of all the IMG elements in a document. The * behavior is limited to IMG elements for backwards * compatibility. As suggested by [HTML 4.01], to include images, authors may use * the OBJECT element or the IMG element. * Therefore, it is recommended not to use this attribute to find the * images in the document but getElementsByTagName with * HTML 4.01 or getElementsByTagNameNS with XHTML 1.0. */ public HTMLCollection getImages(); /** * A collection of all the OBJECT elements that include * applets and APPLET (deprecated) elements in a document. */ public HTMLCollection getApplets(); /** * A collection of all AREA elements and anchor ( * A) elements in a document with a value for the * href attribute. */ public HTMLCollection getLinks(); /** * A collection of all the forms of a document. */ public HTMLCollection getForms(); /** * A collection of all the anchor (A) elements in a document * with a value for the name attribute. For reasons of * backward compatibility, the returned set of anchors only contains * those anchors created with the name attribute, not those * created with the id attribute. Note that in [XHTML 1.0], the * name attribute (see section 4.10) has no semantics and * is only present for legacy user agents: the id attribute * is used instead. Users should prefer the iterator mechanisms provided * by [DOM Level 2 Traversal] instead. */ public HTMLCollection getAnchors(); /** * This mutable string attribute denotes persistent state information * that (1) is associated with the current frame or document and (2) is * composed of information described by the cookies * non-terminal of [IETF RFC 2965], Section 4.2.2. *
If no persistent state information is available for the current * frame or document document, then this property's value is an empty * string. *
When this attribute is read, all cookies are returned as a single * string, with each cookie's name-value pair concatenated into a list * of name-value pairs, each list item being separated by a ';' * (semicolon). *
When this attribute is set, the value it is set to should be a * string that adheres to the cookie non-terminal of [IETF RFC 2965]; that * is, it should be a single name-value pair followed by zero or more * cookie attribute values. If no domain attribute is specified, then * the domain attribute for the new value defaults to the host portion * of an absolute URI [IETF RFC 2396] of the current frame or document. If no path * attribute is specified, then the path attribute for the new value * defaults to the absolute path portion of the URI [IETF RFC 2396] of the current * frame or document. If no max-age attribute is specified, then the * max-age attribute for the new value defaults to a user agent defined * value. If a cookie with the specified name is already associated with * the current frame or document, then the new value as well as the new * attributes replace the old value and attributes. If a max-age * attribute of 0 is specified for the new value, then any existing * cookies of the specified name are removed from the cookie storage. * See [IETF RFC 2965] for the semantics of persistent state item attribute value * pairs. The precise nature of a user agent session is not defined by * this specification. */ public String getCookie(); /** * This mutable string attribute denotes persistent state information * that (1) is associated with the current frame or document and (2) is * composed of information described by the cookies * non-terminal of [IETF RFC 2965], Section 4.2.2. *
If no persistent state information is available for the current * frame or document document, then this property's value is an empty * string. *
When this attribute is read, all cookies are returned as a single * string, with each cookie's name-value pair concatenated into a list * of name-value pairs, each list item being separated by a ';' * (semicolon). *
When this attribute is set, the value it is set to should be a * string that adheres to the cookie non-terminal of [IETF RFC 2965]; that * is, it should be a single name-value pair followed by zero or more * cookie attribute values. If no domain attribute is specified, then * the domain attribute for the new value defaults to the host portion * of an absolute URI [IETF RFC 2396] of the current frame or document. If no path * attribute is specified, then the path attribute for the new value * defaults to the absolute path portion of the URI [IETF RFC 2396] of the current * frame or document. If no max-age attribute is specified, then the * max-age attribute for the new value defaults to a user agent defined * value. If a cookie with the specified name is already associated with * the current frame or document, then the new value as well as the new * attributes replace the old value and attributes. If a max-age * attribute of 0 is specified for the new value, then any existing * cookies of the specified name are removed from the cookie storage. * See [IETF RFC 2965] for the semantics of persistent state item attribute value * pairs. The precise nature of a user agent session is not defined by * this specification. * @exception DOMException * SYNTAX_ERR: If the new value does not adhere to the cookie syntax * specified by [IETF RFC 2965]. */ public void setCookie(String cookie) throws DOMException; /** * Open a document stream for writing. If a document exists in the target, * this method clears it. This method and the ones following allow a * user to add to or replace the structure model of a document using * strings of unparsed HTML. At the time of writing alternate methods * for providing similar functionality for both HTML and XML documents * were being considered (see [DOM Level 3 Load and Save]). */ public void open(); /** * Closes a document stream opened by open() and forces * rendering. */ public void close(); /** * Write a string of text to a document stream opened by * open(). Note that the function will produce a document * which is not necessarily driven by a DTD and therefore might be * produce an invalid result in the context of the document. * @param text The string to be parsed into some structure in the * document structure model. */ public void write(String text); /** * Write a string of text followed by a newline character to a document * stream opened by open(). Note that the function will * produce a document which is not necessarily driven by a DTD and * therefore might be produce an invalid result in the context of the * document * @param text The string to be parsed into some structure in the * document structure model. */ public void writeln(String text); /** * With [HTML 4.01] documents, this method returns the (possibly empty) collection * of elements whose name value is given by * elementName. In [XHTML 1.0] documents, this methods only return the * (possibly empty) collection of form controls with matching name. This * method is case sensitive. * @param elementName The name attribute value for an * element. * @return The matching elements. */ public NodeList getElementsByName(String elementName); }