1 /* 2 * Copyright (c) 2003 World Wide Web Consortium, 3 * (Massachusetts Institute of Technology, Institut National de 4 * Recherche en Informatique et en Automatique, Keio University). All 5 * Rights Reserved. This program is distributed under the W3C's Software 6 * Intellectual Property License. This program is distributed in the 7 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 8 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 9 * PURPOSE. 10 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 11 */ 12 13 package org.w3c.dom.html2; 14 15 import org.w3c.dom.Document; 16 import org.w3c.dom.NodeList; 17 import org.w3c.dom.DOMException; 18 19 /** 20 * An <code>HTMLDocument</code> is the root of the HTML hierarchy and holds 21 * the entire content. Besides providing access to the hierarchy, it also 22 * provides some convenience methods for accessing certain sets of 23 * information from the document. 24 * <p>The following properties have been deprecated in favor of the 25 * corresponding ones for the <code>BODY</code> element:alinkColorbackground 26 * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method 27 * <code>getElementById</code> is inherited from the <code>Document</code> 28 * interface where it was moved to. 29 * <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>. 30 */ 31 public interface HTMLDocument extends Document { 32 /** 33 * The title of a document as specified by the <code>TITLE</code> element 34 * in the head of the document. 35 */ getTitle()36 public String getTitle(); 37 /** 38 * The title of a document as specified by the <code>TITLE</code> element 39 * in the head of the document. 40 */ setTitle(String title)41 public void setTitle(String title); 42 43 /** 44 * 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 45 * empty string if the user navigated to the page directly (not through 46 * a link, but, for example, via a bookmark). 47 */ getReferrer()48 public String getReferrer(); 49 50 /** 51 * The domain name of the server that served the document, or 52 * <code>null</code> if the server cannot be identified by a domain 53 * name. 54 */ getDomain()55 public String getDomain(); 56 57 /** 58 * The absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the document. 59 */ getURL()60 public String getURL(); 61 62 /** 63 * The element that contains the content for the document. In documents 64 * with <code>BODY</code> contents, returns the <code>BODY</code> 65 * element. In frameset documents, this returns the outermost 66 * <code>FRAMESET</code> element. 67 */ getBody()68 public HTMLElement getBody(); 69 /** 70 * The element that contains the content for the document. In documents 71 * with <code>BODY</code> contents, returns the <code>BODY</code> 72 * element. In frameset documents, this returns the outermost 73 * <code>FRAMESET</code> element. 74 */ setBody(HTMLElement body)75 public void setBody(HTMLElement body); 76 77 /** 78 * A collection of all the <code>IMG</code> elements in a document. The 79 * behavior is limited to <code>IMG</code> elements for backwards 80 * 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 81 * the <code>OBJECT</code> element or the <code>IMG</code> element. 82 * Therefore, it is recommended not to use this attribute to find the 83 * images in the document but <code>getElementsByTagName</code> with 84 * HTML 4.01 or <code>getElementsByTagNameNS</code> with XHTML 1.0. 85 */ getImages()86 public HTMLCollection getImages(); 87 88 /** 89 * A collection of all the <code>OBJECT</code> elements that include 90 * applets and <code>APPLET</code> (deprecated) elements in a document. 91 */ getApplets()92 public HTMLCollection getApplets(); 93 94 /** 95 * A collection of all <code>AREA</code> elements and anchor ( 96 * <code>A</code>) elements in a document with a value for the 97 * <code>href</code> attribute. 98 */ getLinks()99 public HTMLCollection getLinks(); 100 101 /** 102 * A collection of all the forms of a document. 103 */ getForms()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 */ getAnchors()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 */ getCookie()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 */ setCookie(String cookie)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 */ open()196 public void open(); 197 198 /** 199 * Closes a document stream opened by <code>open()</code> and forces 200 * rendering. 201 */ close()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 */ write(String text)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 */ writeln(String text)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 */ getElementsByName(String elementName)235 public NodeList getElementsByName(String elementName); 236 237 } 238