HTMLDocument


1   /*
2       GNU LESSER GENERAL PUBLIC LICENSE
3       Copyright (C) 2006 The Lobo Project
4   
5       This library is free software; you can redistribute it and/or
6       modify it under the terms of the GNU Lesser General Public
7       License as published by the Free Software Foundation; either
8       version 2.1 of the License, or (at your option) any later version.
9   
10      This library is distributed in the hope that it will be useful,
11      but WITHOUT ANY WARRANTY; without even the implied warranty of
12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13      Lesser General Public License for more details.
14  
15      You should have received a copy of the GNU Lesser General Public
16      License along with this library; if not, write to the Free Software
17      Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
18  
19      Contact info: xamjadmin@users.sourceforge.net
20  */
21  /*
22   * Copyright (c) 2003 World Wide Web Consortium,
23   * (Massachusetts Institute of Technology, Institut National de
24   * Recherche en Informatique et en Automatique, Keio University). All
25   * Rights Reserved. This program is distributed under the W3C's Software
26   * Intellectual Property License. This program is distributed in the
27   * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
28   * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
29   * PURPOSE.
30   * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
31   */
32  
33  package org.w3c.dom.html2;
34  
35  import org.w3c.dom.Document  ;
36  import org.w3c.dom.NodeList  ;
37  import org.w3c.dom.DOMException  ;
38  
39  /**
40   * An <code>HTMLDocument</code> is the root of the HTML hierarchy and holds 
41   * the entire content. Besides providing access to the hierarchy, it also 
42   * provides some convenience methods for accessing certain sets of 
43   * information from the document.
44   * <p>The following properties have been deprecated in favor of the 
45   * corresponding ones for the <code>BODY</code> element:alinkColorbackground
46   * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method 
47   * <code>getElementById</code> is inherited from the <code>Document</code> 
48   * interface where it was moved to.
49   * <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>.
50   */
51  public interface HTMLDocument extends Document   {
52      /**
53       * The title of a document as specified by the <code>TITLE</code> element 
54       * in the head of the document. 
55       */
56      public String   getTitle();
57      /**
58       * The title of a document as specified by the <code>TITLE</code> element 
59       * in the head of the document. 
60       */
61      public void setTitle(String   title);
62  
63      /**
64       * 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 
65       * empty string if the user navigated to the page directly (not through 
66       * a link, but, for example, via a bookmark). 
67       */
68      public String   getReferrer();
69  
70      /**
71       * The domain name of the server that served the document, or 
72       * <code>null</code> if the server cannot be identified by a domain 
73       * name. 
74       */
75      public String   getDomain();
76  
77      /**
78       * The absolute URI [<a HREF='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the document. 
79       */
80      public String   getURL();
81  
82      /**
83       * The element that contains the content for the document. In documents 
84       * with <code>BODY</code> contents, returns the <code>BODY</code> 
85       * element. In frameset documents, this returns the outermost 
86       * <code>FRAMESET</code> element. 
87       */
88      public HTMLElement getBody();
89      /**
90       * The element that contains the content for the document. In documents 
91       * with <code>BODY</code> contents, returns the <code>BODY</code> 
92       * element. In frameset documents, this returns the outermost 
93       * <code>FRAMESET</code> element. 
94       */
95      public void setBody(HTMLElement body);
96  
97      /**
98       * A collection of all the <code>IMG</code> elements in a document. The 
99       * behavior is limited to <code>IMG</code> elements for backwards 
100      * 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 
101      * the <code>OBJECT</code> element or the <code>IMG</code> element. 
102      * Therefore, it is recommended not to use this attribute to find the 
103      * images in the document but <code>getElementsByTagName</code> with 
104      * HTML 4.01 or <code>getElementsByTagNameNS</code> with XHTML 1.0.
105      */
106     public HTMLCollection getImages();
107 
108     /**
109      * A collection of all the <code>OBJECT</code> elements that include 
110      * applets and <code>APPLET</code> (deprecated) elements in a document. 
111      */
112     public HTMLCollection getApplets();
113 
114     /**
115      * A collection of all <code>AREA</code> elements and anchor (
116      * <code>A</code>) elements in a document with a value for the 
117      * <code>href</code> attribute. 
118      */
119     public HTMLCollection getLinks();
120 
121     /**
122      * A collection of all the forms of a document. 
123      */
124     public HTMLCollection getForms();
125 
126     /**
127      *  A collection of all the anchor (<code>A</code>) elements in a document 
128      * with a value for the <code>name</code> attribute. For reasons of 
129      * backward compatibility, the returned set of anchors only contains 
130      * those anchors created with the <code>name</code> attribute, not those 
131      * 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 
132      * <code>name</code> attribute (see section 4.10) has no semantics and 
133      * is only present for legacy user agents: the <code>id</code> attribute 
134      * is used instead. Users should prefer the iterator mechanisms provided 
135      * by [<a HREF='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal</a>] instead. 
136      */
137     public HTMLCollection getAnchors();
138 
139     /**
140      *  This mutable string attribute denotes persistent state information 
141      * that (1) is associated with the current frame or document and (2) is 
142      * composed of information described by the <code>cookies</code> 
143      * non-terminal of [<a HREF='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2. 
144      * <br> If no persistent state information is available for the current 
145      * frame or document document, then this property's value is an empty 
146      * string. 
147      * <br> When this attribute is read, all cookies are returned as a single 
148      * string, with each cookie's name-value pair concatenated into a list 
149      * of name-value pairs, each list item being separated by a ';' 
150      * (semicolon). 
151      * <br> When this attribute is set, the value it is set to should be a 
152      * 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 
153      * is, it should be a single name-value pair followed by zero or more 
154      * cookie attribute values. If no domain attribute is specified, then 
155      * the domain attribute for the new value defaults to the host portion 
156      * 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 
157      * attribute is specified, then the path attribute for the new value 
158      * 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 
159      * frame or document. If no max-age attribute is specified, then the 
160      * max-age attribute for the new value defaults to a user agent defined 
161      * value. If a cookie with the specified name is already associated with 
162      * the current frame or document, then the new value as well as the new 
163      * attributes replace the old value and attributes. If a max-age 
164      * attribute of 0 is specified for the new value, then any existing 
165      * cookies of the specified name are removed from the cookie storage.  
166      * See [<a HREF='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value 
167      * pairs.  The precise nature of a user agent session is not defined by 
168      * this specification. 
169      */
170     public String   getCookie();
171     /**
172      *  This mutable string attribute denotes persistent state information 
173      * that (1) is associated with the current frame or document and (2) is 
174      * composed of information described by the <code>cookies</code> 
175      * non-terminal of [<a HREF='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2. 
176      * <br> If no persistent state information is available for the current 
177      * frame or document document, then this property's value is an empty 
178      * string. 
179      * <br> When this attribute is read, all cookies are returned as a single 
180      * string, with each cookie's name-value pair concatenated into a list 
181      * of name-value pairs, each list item being separated by a ';' 
182      * (semicolon). 
183      * <br> When this attribute is set, the value it is set to should be a 
184      * 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 
185      * is, it should be a single name-value pair followed by zero or more 
186      * cookie attribute values. If no domain attribute is specified, then 
187      * the domain attribute for the new value defaults to the host portion 
188      * 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 
189      * attribute is specified, then the path attribute for the new value 
190      * 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 
191      * frame or document. If no max-age attribute is specified, then the 
192      * max-age attribute for the new value defaults to a user agent defined 
193      * value. If a cookie with the specified name is already associated with 
194      * the current frame or document, then the new value as well as the new 
195      * attributes replace the old value and attributes. If a max-age 
196      * attribute of 0 is specified for the new value, then any existing 
197      * cookies of the specified name are removed from the cookie storage.  
198      * See [<a HREF='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value 
199      * pairs.  The precise nature of a user agent session is not defined by 
200      * this specification. 
201      * @exception DOMException
202      *    SYNTAX_ERR: If the new value does not adhere to the cookie syntax 
203      *   specified by [<a HREF='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>]. 
204      */
205     public void setCookie(String   cookie)
206                                       throws DOMException  ;
207 
208     /**
209      * Open a document stream for writing. If a document exists in the target, 
210      * this method clears it. This method and the ones following allow a 
211      * user to add to or replace the structure model of a document using 
212      * strings of unparsed HTML. At the time of writing alternate methods 
213      * for providing similar functionality for both HTML and XML documents 
214      * 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>]).
215      */
216     public void open();
217 
218     /**
219      * Closes a document stream opened by <code>open()</code> and forces 
220      * rendering.
221      */
222     public void close();
223 
224     /**
225      * Write a string of text to a document stream opened by 
226      * <code>open()</code>. Note that the function will produce a document 
227      * which is not necessarily driven by a DTD and therefore might be 
228      * produce an invalid result in the context of the document.
229      * @param text The string to be parsed into some structure in the 
230      *   document structure model.
231      */
232     public void write(String   text);
233 
234     /**
235      * Write a string of text followed by a newline character to a document 
236      * stream opened by <code>open()</code>. Note that the function will 
237      * produce a document which is not necessarily driven by a DTD and 
238      * therefore might be produce an invalid result in the context of the 
239      * document
240      * @param text The string to be parsed into some structure in the 
241      *   document structure model.
242      */
243     public void writeln(String   text);
244 
245     /**
246      *  With [<a HREF='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>] documents, this method returns the (possibly empty) collection 
247      * of elements whose <code>name</code> value is given by 
248      * <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 
249      * (possibly empty) collection of form controls with matching name. This 
250      * method is case sensitive. 
251      * @param elementName The <code>name</code> attribute value for an 
252      *   element.
253      * @return The matching elements.
254      */
255     public NodeList   getElementsByName(String   elementName);
256 
257 }
258
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags