lib/classpath/external/w3c_dom/org/w3c/dom/html2/HTMLDocument.java

   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 }