001 /* 002 * Copyright (c) 2003 World Wide Web Consortium, 003 * (Massachusetts Institute of Technology, Institut National de 004 * Recherche en Informatique et en Automatique, Keio University). All 005 * Rights Reserved. This program is distributed under the W3C's Software 006 * Intellectual Property License. This program is distributed in the 007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 009 * PURPOSE. 010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 011 */ 012 013 package org.w3c.dom.html2; 014 015 import org.w3c.dom.Document; 016 import org.w3c.dom.NodeList; 017 import org.w3c.dom.DOMException; 018 019 /** 020 * An <code>HTMLDocument</code> is the root of the HTML hierarchy and holds 021 * the entire content. Besides providing access to the hierarchy, it also 022 * provides some convenience methods for accessing certain sets of 023 * information from the document. 024 * <p>The following properties have been deprecated in favor of the 025 * corresponding ones for the <code>BODY</code> element:alinkColorbackground 026 * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method 027 * <code>getElementById</code> is inherited from the <code>Document</code> 028 * interface where it was moved to. 029 * <p>See also the <a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>Document Object Model (DOM) Level 2 HTML Specification</a>. 030 */ 031 public interface HTMLDocument extends Document { 032 /** 033 * The title of a document as specified by the <code>TITLE</code> element 034 * in the head of the document. 035 */ 036 public String getTitle(); 037 /** 038 * The title of a document as specified by the <code>TITLE</code> element 039 * in the head of the document. 040 */ 041 public void setTitle(String title); 042 043 /** 044 * Returns the URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the page that linked to this page. The value is an 045 * empty string if the user navigated to the page directly (not through 046 * a link, but, for example, via a bookmark). 047 */ 048 public String getReferrer(); 049 050 /** 051 * The domain name of the server that served the document, or 052 * <code>null</code> if the server cannot be identified by a domain 053 * name. 054 */ 055 public String getDomain(); 056 057 /** 058 * The absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the document. 059 */ 060 public String getURL(); 061 062 /** 063 * The element that contains the content for the document. In documents 064 * with <code>BODY</code> contents, returns the <code>BODY</code> 065 * element. In frameset documents, this returns the outermost 066 * <code>FRAMESET</code> element. 067 */ 068 public HTMLElement getBody(); 069 /** 070 * The element that contains the content for the document. In documents 071 * with <code>BODY</code> contents, returns the <code>BODY</code> 072 * element. In frameset documents, this returns the outermost 073 * <code>FRAMESET</code> element. 074 */ 075 public void setBody(HTMLElement body); 076 077 /** 078 * A collection of all the <code>IMG</code> elements in a document. The 079 * behavior is limited to <code>IMG</code> elements for backwards 080 * compatibility. As suggested by [<a href='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>], to include images, authors may use 081 * the <code>OBJECT</code> element or the <code>IMG</code> element. 082 * Therefore, it is recommended not to use this attribute to find the 083 * images in the document but <code>getElementsByTagName</code> with 084 * HTML 4.01 or <code>getElementsByTagNameNS</code> with XHTML 1.0. 085 */ 086 public HTMLCollection getImages(); 087 088 /** 089 * A collection of all the <code>OBJECT</code> elements that include 090 * applets and <code>APPLET</code> (deprecated) elements in a document. 091 */ 092 public HTMLCollection getApplets(); 093 094 /** 095 * A collection of all <code>AREA</code> elements and anchor ( 096 * <code>A</code>) elements in a document with a value for the 097 * <code>href</code> attribute. 098 */ 099 public HTMLCollection getLinks(); 100 101 /** 102 * A collection of all the forms of a document. 103 */ 104 public HTMLCollection getForms(); 105 106 /** 107 * A collection of all the anchor (<code>A</code>) elements in a document 108 * with a value for the <code>name</code> attribute. For reasons of 109 * backward compatibility, the returned set of anchors only contains 110 * those anchors created with the <code>name</code> attribute, not those 111 * created with the <code>id</code> attribute. Note that in [<a href='http://www.w3.org/TR/2002/REC-xhtml1-20020801'>XHTML 1.0</a>], the 112 * <code>name</code> attribute (see section 4.10) has no semantics and 113 * is only present for legacy user agents: the <code>id</code> attribute 114 * is used instead. Users should prefer the iterator mechanisms provided 115 * by [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal</a>] instead. 116 */ 117 public HTMLCollection getAnchors(); 118 119 /** 120 * This mutable string attribute denotes persistent state information 121 * that (1) is associated with the current frame or document and (2) is 122 * composed of information described by the <code>cookies</code> 123 * non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2. 124 * <br> If no persistent state information is available for the current 125 * frame or document document, then this property's value is an empty 126 * string. 127 * <br> When this attribute is read, all cookies are returned as a single 128 * string, with each cookie's name-value pair concatenated into a list 129 * of name-value pairs, each list item being separated by a ';' 130 * (semicolon). 131 * <br> When this attribute is set, the value it is set to should be a 132 * string that adheres to the <code>cookie</code> non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>]; that 133 * is, it should be a single name-value pair followed by zero or more 134 * cookie attribute values. If no domain attribute is specified, then 135 * the domain attribute for the new value defaults to the host portion 136 * of an absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the current frame or document. If no path 137 * attribute is specified, then the path attribute for the new value 138 * defaults to the absolute path portion of the URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the current 139 * frame or document. If no max-age attribute is specified, then the 140 * max-age attribute for the new value defaults to a user agent defined 141 * value. If a cookie with the specified name is already associated with 142 * the current frame or document, then the new value as well as the new 143 * attributes replace the old value and attributes. If a max-age 144 * attribute of 0 is specified for the new value, then any existing 145 * cookies of the specified name are removed from the cookie storage. 146 * See [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value 147 * pairs. The precise nature of a user agent session is not defined by 148 * this specification. 149 */ 150 public String getCookie(); 151 /** 152 * This mutable string attribute denotes persistent state information 153 * that (1) is associated with the current frame or document and (2) is 154 * composed of information described by the <code>cookies</code> 155 * non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2. 156 * <br> If no persistent state information is available for the current 157 * frame or document document, then this property's value is an empty 158 * string. 159 * <br> When this attribute is read, all cookies are returned as a single 160 * string, with each cookie's name-value pair concatenated into a list 161 * of name-value pairs, each list item being separated by a ';' 162 * (semicolon). 163 * <br> When this attribute is set, the value it is set to should be a 164 * string that adheres to the <code>cookie</code> non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>]; that 165 * is, it should be a single name-value pair followed by zero or more 166 * cookie attribute values. If no domain attribute is specified, then 167 * the domain attribute for the new value defaults to the host portion 168 * of an absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the current frame or document. If no path 169 * attribute is specified, then the path attribute for the new value 170 * defaults to the absolute path portion of the URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the current 171 * frame or document. If no max-age attribute is specified, then the 172 * max-age attribute for the new value defaults to a user agent defined 173 * value. If a cookie with the specified name is already associated with 174 * the current frame or document, then the new value as well as the new 175 * attributes replace the old value and attributes. If a max-age 176 * attribute of 0 is specified for the new value, then any existing 177 * cookies of the specified name are removed from the cookie storage. 178 * See [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value 179 * pairs. The precise nature of a user agent session is not defined by 180 * this specification. 181 * @exception DOMException 182 * SYNTAX_ERR: If the new value does not adhere to the cookie syntax 183 * specified by [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>]. 184 */ 185 public void setCookie(String cookie) 186 throws DOMException; 187 188 /** 189 * Open a document stream for writing. If a document exists in the target, 190 * this method clears it. This method and the ones following allow a 191 * user to add to or replace the structure model of a document using 192 * strings of unparsed HTML. At the time of writing alternate methods 193 * for providing similar functionality for both HTML and XML documents 194 * were being considered (see [<a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725'>DOM Level 3 Load and Save</a>]). 195 */ 196 public void open(); 197 198 /** 199 * Closes a document stream opened by <code>open()</code> and forces 200 * rendering. 201 */ 202 public void close(); 203 204 /** 205 * Write a string of text to a document stream opened by 206 * <code>open()</code>. Note that the function will produce a document 207 * which is not necessarily driven by a DTD and therefore might be 208 * produce an invalid result in the context of the document. 209 * @param text The string to be parsed into some structure in the 210 * document structure model. 211 */ 212 public void write(String text); 213 214 /** 215 * Write a string of text followed by a newline character to a document 216 * stream opened by <code>open()</code>. Note that the function will 217 * produce a document which is not necessarily driven by a DTD and 218 * therefore might be produce an invalid result in the context of the 219 * document 220 * @param text The string to be parsed into some structure in the 221 * document structure model. 222 */ 223 public void writeln(String text); 224 225 /** 226 * With [<a href='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>] documents, this method returns the (possibly empty) collection 227 * of elements whose <code>name</code> value is given by 228 * <code>elementName</code>. In [<a href='http://www.w3.org/TR/2002/REC-xhtml1-20020801'>XHTML 1.0</a>] documents, this methods only return the 229 * (possibly empty) collection of form controls with matching name. This 230 * method is case sensitive. 231 * @param elementName The <code>name</code> attribute value for an 232 * element. 233 * @return The matching elements. 234 */ 235 public NodeList getElementsByName(String elementName); 236 237 }