KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > w3c > dom > html2 > 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 JavaDoc;
36 import org.w3c.dom.NodeList JavaDoc;
37 import org.w3c.dom.DOMException JavaDoc;
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 JavaDoc {
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc cookie)
206                                       throws DOMException JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc getElementsByName(String JavaDoc elementName);
256
257 }
258
Popular Tags