Source for org.w3c.dom.html2.HTMLDocument

   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: }