001    /*
002     * Copyright (c) 2003 World Wide Web Consortium,
003     * (Massachusetts Institute of Technology, Institut National de
004     * Recherche en Informatique et en Automatique, Keio University). All
005     * Rights Reserved. This program is distributed under the W3C's Software
006     * Intellectual Property License. This program is distributed in the
007     * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008     * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009     * PURPOSE.
010     * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011     */
012    
013    package org.w3c.dom.html2;
014    
015    import org.w3c.dom.Document;
016    import org.w3c.dom.NodeList;
017    import org.w3c.dom.DOMException;
018    
019    /**
020     * An <code>HTMLDocument</code> is the root of the HTML hierarchy and holds 
021     * the entire content. Besides providing access to the hierarchy, it also 
022     * provides some convenience methods for accessing certain sets of 
023     * information from the document.
024     * <p>The following properties have been deprecated in favor of the 
025     * corresponding ones for the <code>BODY</code> element:alinkColorbackground
026     * bgColorfgColorlinkColorvlinkColorIn DOM Level 2, the method 
027     * <code>getElementById</code> is inherited from the <code>Document</code> 
028     * interface where it was moved to.
029     * <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>.
030     */
031    public interface HTMLDocument extends Document {
032        /**
033         * The title of a document as specified by the <code>TITLE</code> element 
034         * in the head of the document. 
035         */
036        public String getTitle();
037        /**
038         * The title of a document as specified by the <code>TITLE</code> element 
039         * in the head of the document. 
040         */
041        public void setTitle(String title);
042    
043        /**
044         * 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 
045         * empty string if the user navigated to the page directly (not through 
046         * a link, but, for example, via a bookmark). 
047         */
048        public String getReferrer();
049    
050        /**
051         * The domain name of the server that served the document, or 
052         * <code>null</code> if the server cannot be identified by a domain 
053         * name. 
054         */
055        public String getDomain();
056    
057        /**
058         * The absolute URI [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>] of the document. 
059         */
060        public String getURL();
061    
062        /**
063         * The element that contains the content for the document. In documents 
064         * with <code>BODY</code> contents, returns the <code>BODY</code> 
065         * element. In frameset documents, this returns the outermost 
066         * <code>FRAMESET</code> element. 
067         */
068        public HTMLElement getBody();
069        /**
070         * The element that contains the content for the document. In documents 
071         * with <code>BODY</code> contents, returns the <code>BODY</code> 
072         * element. In frameset documents, this returns the outermost 
073         * <code>FRAMESET</code> element. 
074         */
075        public void setBody(HTMLElement body);
076    
077        /**
078         * A collection of all the <code>IMG</code> elements in a document. The 
079         * behavior is limited to <code>IMG</code> elements for backwards 
080         * 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 
081         * the <code>OBJECT</code> element or the <code>IMG</code> element. 
082         * Therefore, it is recommended not to use this attribute to find the 
083         * images in the document but <code>getElementsByTagName</code> with 
084         * HTML 4.01 or <code>getElementsByTagNameNS</code> with XHTML 1.0.
085         */
086        public HTMLCollection getImages();
087    
088        /**
089         * A collection of all the <code>OBJECT</code> elements that include 
090         * applets and <code>APPLET</code> (deprecated) elements in a document. 
091         */
092        public HTMLCollection getApplets();
093    
094        /**
095         * A collection of all <code>AREA</code> elements and anchor (
096         * <code>A</code>) elements in a document with a value for the 
097         * <code>href</code> attribute. 
098         */
099        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    }