summaryrefslogtreecommitdiff
path: root/libjava/classpath/external/w3c_dom/org/w3c/dom/html2/HTMLDocument.java
blob: b038783f6713cd7f3fdce209a7b560cde2da83bd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
/*
 * Copyright (c) 2003 World Wide Web Consortium,
 * (Massachusetts Institute of Technology, Institut National de
 * Recherche en Informatique et en Automatique, Keio University). All
 * Rights Reserved. This program is distributed under the W3C's Software
 * Intellectual Property License. This program is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.
 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
 */

package org.w3c.dom.html2;

import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import org.w3c.dom.DOMException;

/**
 * An <code>HTMLDocument</code> is the root of the HTML hierarchy and holds
 * the entire content. Besides providing access to the hierarchy, it also
 * provides some convenience methods for accessing certain sets of
 * information from the document.
 * <p>The following properties have been deprecated in favor of the
 * corresponding ones for the <code>BODY</code> element:alinkColorbackground
 * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method
 * <code>getElementById</code> is inherited from the <code>Document</code>
 * interface where it was moved to.
 * <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>.
 */
public interface HTMLDocument extends Document {
    /**
     * The title of a document as specified by the <code>TITLE</code> element
     * in the head of the document.
     */
    public String getTitle();
    /**
     * The title of a document as specified by the <code>TITLE</code> element
     * in the head of the document.
     */
    public void setTitle(String title);

    /**
     * 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
     * empty string if the user navigated to the page directly (not through
     * a link, but, for example, via a bookmark).
     */
    public String getReferrer();

    /**
     * The domain name of the server that served the document, or
     * <code>null</code> if the server cannot be identified by a domain
     * name.
     */
    public String getDomain();

    /**
     * The absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the document.
     */
    public String getURL();

    /**
     * The element that contains the content for the document. In documents
     * with <code>BODY</code> contents, returns the <code>BODY</code>
     * element. In frameset documents, this returns the outermost
     * <code>FRAMESET</code> element.
     */
    public HTMLElement getBody();
    /**
     * The element that contains the content for the document. In documents
     * with <code>BODY</code> contents, returns the <code>BODY</code>
     * element. In frameset documents, this returns the outermost
     * <code>FRAMESET</code> element.
     */
    public void setBody(HTMLElement body);

    /**
     * A collection of all the <code>IMG</code> elements in a document. The
     * behavior is limited to <code>IMG</code> elements for backwards
     * 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
     * the <code>OBJECT</code> element or the <code>IMG</code> element.
     * Therefore, it is recommended not to use this attribute to find the
     * images in the document but <code>getElementsByTagName</code> with
     * HTML 4.01 or <code>getElementsByTagNameNS</code> with XHTML 1.0.
     */
    public HTMLCollection getImages();

    /**
     * A collection of all the <code>OBJECT</code> elements that include
     * applets and <code>APPLET</code> (deprecated) elements in a document.
     */
    public HTMLCollection getApplets();

    /**
     * A collection of all <code>AREA</code> elements and anchor (
     * <code>A</code>) elements in a document with a value for the
     * <code>href</code> attribute.
     */
    public HTMLCollection getLinks();

    /**
     * A collection of all the forms of a document.
     */
    public HTMLCollection getForms();

    /**
     *  A collection of all the anchor (<code>A</code>) elements in a document
     * with a value for the <code>name</code> attribute. For reasons of
     * backward compatibility, the returned set of anchors only contains
     * those anchors created with the <code>name</code> attribute, not those
     * 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
     * <code>name</code> attribute (see section 4.10) has no semantics and
     * is only present for legacy user agents: the <code>id</code> attribute
     * is used instead. Users should prefer the iterator mechanisms provided
     * by [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal</a>] instead.
     */
    public HTMLCollection getAnchors();

    /**
     *  This mutable string attribute denotes persistent state information
     * that (1) is associated with the current frame or document and (2) is
     * composed of information described by the <code>cookies</code>
     * non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2.
     * <br> If no persistent state information is available for the current
     * frame or document document, then this property's value is an empty
     * string.
     * <br> When this attribute is read, all cookies are returned as a single
     * string, with each cookie's name-value pair concatenated into a list
     * of name-value pairs, each list item being separated by a ';'
     * (semicolon).
     * <br> When this attribute is set, the value it is set to should be a
     * 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
     * is, it should be a single name-value pair followed by zero or more
     * cookie attribute values. If no domain attribute is specified, then
     * the domain attribute for the new value defaults to the host portion
     * 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
     * attribute is specified, then the path attribute for the new value
     * 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
     * frame or document. If no max-age attribute is specified, then the
     * max-age attribute for the new value defaults to a user agent defined
     * value. If a cookie with the specified name is already associated with
     * the current frame or document, then the new value as well as the new
     * attributes replace the old value and attributes. If a max-age
     * attribute of 0 is specified for the new value, then any existing
     * cookies of the specified name are removed from the cookie storage.
     * See [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value
     * pairs.  The precise nature of a user agent session is not defined by
     * this specification.
     */
    public String getCookie();
    /**
     *  This mutable string attribute denotes persistent state information
     * that (1) is associated with the current frame or document and (2) is
     * composed of information described by the <code>cookies</code>
     * non-terminal of [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>], Section 4.2.2.
     * <br> If no persistent state information is available for the current
     * frame or document document, then this property's value is an empty
     * string.
     * <br> When this attribute is read, all cookies are returned as a single
     * string, with each cookie's name-value pair concatenated into a list
     * of name-value pairs, each list item being separated by a ';'
     * (semicolon).
     * <br> When this attribute is set, the value it is set to should be a
     * 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
     * is, it should be a single name-value pair followed by zero or more
     * cookie attribute values. If no domain attribute is specified, then
     * the domain attribute for the new value defaults to the host portion
     * 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
     * attribute is specified, then the path attribute for the new value
     * 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
     * frame or document. If no max-age attribute is specified, then the
     * max-age attribute for the new value defaults to a user agent defined
     * value. If a cookie with the specified name is already associated with
     * the current frame or document, then the new value as well as the new
     * attributes replace the old value and attributes. If a max-age
     * attribute of 0 is specified for the new value, then any existing
     * cookies of the specified name are removed from the cookie storage.
     * See [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>] for the semantics of persistent state item attribute value
     * pairs.  The precise nature of a user agent session is not defined by
     * this specification.
     * @exception DOMException
     *    SYNTAX_ERR: If the new value does not adhere to the cookie syntax
     *   specified by [<a href='http://www.ietf.org/rfc/rfc2965.txt'>IETF RFC 2965</a>].
     */
    public void setCookie(String cookie)
                                      throws DOMException;

    /**
     * Open a document stream for writing. If a document exists in the target,
     * this method clears it. This method and the ones following allow a
     * user to add to or replace the structure model of a document using
     * strings of unparsed HTML. At the time of writing alternate methods
     * for providing similar functionality for both HTML and XML documents
     * 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>]).
     */
    public void open();

    /**
     * Closes a document stream opened by <code>open()</code> and forces
     * rendering.
     */
    public void close();

    /**
     * Write a string of text to a document stream opened by
     * <code>open()</code>. Note that the function will produce a document
     * which is not necessarily driven by a DTD and therefore might be
     * produce an invalid result in the context of the document.
     * @param text The string to be parsed into some structure in the
     *   document structure model.
     */
    public void write(String text);

    /**
     * Write a string of text followed by a newline character to a document
     * stream opened by <code>open()</code>. Note that the function will
     * produce a document which is not necessarily driven by a DTD and
     * therefore might be produce an invalid result in the context of the
     * document
     * @param text The string to be parsed into some structure in the
     *   document structure model.
     */
    public void writeln(String text);

    /**
     *  With [<a href='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>] documents, this method returns the (possibly empty) collection
     * of elements whose <code>name</code> value is given by
     * <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
     * (possibly empty) collection of form controls with matching name. This
     * method is case sensitive.
     * @param elementName The <code>name</code> attribute value for an
     *   element.
     * @return The matching elements.
     */
    public NodeList getElementsByName(String elementName);

}