| Frames | No Frames |
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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 99: 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: }