001    /*
002     * Copyright (c) 2004 World Wide Web Consortium,
003     *
004     * (Massachusetts Institute of Technology, European Research Consortium for
005     * Informatics and Mathematics, Keio University). All Rights Reserved. This
006     * work is distributed under the W3C(r) Software License [1] in the hope that
007     * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008     * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009     *
010     * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011     */
012    
013    package org.w3c.dom;
014    
015    /**
016     * The <code>Element</code> interface represents an element in an HTML or XML 
017     * document. Elements may have attributes associated with them; since the 
018     * <code>Element</code> interface inherits from <code>Node</code>, the 
019     * generic <code>Node</code> interface attribute <code>attributes</code> may 
020     * be used to retrieve the set of all attributes for an element. There are 
021     * methods on the <code>Element</code> interface to retrieve either an 
022     * <code>Attr</code> object by name or an attribute value by name. In XML, 
023     * where an attribute value may contain entity references, an 
024     * <code>Attr</code> object should be retrieved to examine the possibly 
025     * fairly complex sub-tree representing the attribute value. On the other 
026     * hand, in HTML, where all attributes have simple string values, methods to 
027     * directly access an attribute value can safely be used as a convenience.
028     * <p ><b>Note:</b> In DOM Level 2, the method <code>normalize</code> is 
029     * inherited from the <code>Node</code> interface where it was moved.
030     * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>.
031     */
032    public interface Element extends Node {
033        /**
034         * The name of the element. If <code>Node.localName</code> is different 
035         * from <code>null</code>, this attribute is a qualified name. For 
036         * example, in: 
037         * <pre> &lt;elementExample id="demo"&gt; ... 
038         * &lt;/elementExample&gt; , </pre>
039         *  <code>tagName</code> has the value 
040         * <code>"elementExample"</code>. Note that this is case-preserving in 
041         * XML, as are all of the operations of the DOM. The HTML DOM returns 
042         * the <code>tagName</code> of an HTML element in the canonical 
043         * uppercase form, regardless of the case in the source HTML document.
044         */
045        public String getTagName();
046    
047        /**
048         * Retrieves an attribute value by name.
049         * @param name The name of the attribute to retrieve.
050         * @return The <code>Attr</code> value as a string, or the empty string 
051         *   if that attribute does not have a specified or default value.
052         */
053        public String getAttribute(String name);
054    
055        /**
056         * Adds a new attribute. If an attribute with that name is already present 
057         * in the element, its value is changed to be that of the value 
058         * parameter. This value is a simple string; it is not parsed as it is 
059         * being set. So any markup (such as syntax to be recognized as an 
060         * entity reference) is treated as literal text, and needs to be 
061         * appropriately escaped by the implementation when it is written out. 
062         * In order to assign an attribute value that contains entity 
063         * references, the user must create an <code>Attr</code> node plus any 
064         * <code>Text</code> and <code>EntityReference</code> nodes, build the 
065         * appropriate subtree, and use <code>setAttributeNode</code> to assign 
066         * it as the value of an attribute.
067         * <br>To set an attribute with a qualified name and namespace URI, use 
068         * the <code>setAttributeNS</code> method.
069         * @param name The name of the attribute to create or alter.
070         * @param value Value to set in string form.
071         * @exception DOMException
072         *   INVALID_CHARACTER_ERR: Raised if the specified name is not an XML 
073         *   name according to the XML version in use specified in the 
074         *   <code>Document.xmlVersion</code> attribute.
075         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
076         */
077        public void setAttribute(String name, 
078                                 String value)
079                                 throws DOMException;
080    
081        /**
082         * Removes an attribute by name. If a default value for the removed 
083         * attribute is defined in the DTD, a new attribute immediately appears 
084         * with the default value as well as the corresponding namespace URI, 
085         * local name, and prefix when applicable. The implementation may handle 
086         * default values from other schemas similarly but applications should 
087         * use <code>Document.normalizeDocument()</code> to guarantee this 
088         * information is up-to-date.
089         * <br>If no attribute with this name is found, this method has no effect.
090         * <br>To remove an attribute by local name and namespace URI, use the 
091         * <code>removeAttributeNS</code> method.
092         * @param name The name of the attribute to remove.
093         * @exception DOMException
094         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
095         */
096        public void removeAttribute(String name)
097                                    throws DOMException;
098    
099        /**
100         * Retrieves an attribute node by name.
101         * <br>To retrieve an attribute node by qualified name and namespace URI, 
102         * use the <code>getAttributeNodeNS</code> method.
103         * @param name The name (<code>nodeName</code>) of the attribute to 
104         *   retrieve.
105         * @return The <code>Attr</code> node with the specified name (
106         *   <code>nodeName</code>) or <code>null</code> if there is no such 
107         *   attribute.
108         */
109        public Attr getAttributeNode(String name);
110    
111        /**
112         * Adds a new attribute node. If an attribute with that name (
113         * <code>nodeName</code>) is already present in the element, it is 
114         * replaced by the new one. Replacing an attribute node by itself has no 
115         * effect.
116         * <br>To add a new attribute node with a qualified name and namespace 
117         * URI, use the <code>setAttributeNodeNS</code> method.
118         * @param newAttr The <code>Attr</code> node to add to the attribute list.
119         * @return If the <code>newAttr</code> attribute replaces an existing 
120         *   attribute, the replaced <code>Attr</code> node is returned, 
121         *   otherwise <code>null</code> is returned.
122         * @exception DOMException
123         *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a 
124         *   different document than the one that created the element.
125         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
126         *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an 
127         *   attribute of another <code>Element</code> object. The DOM user must 
128         *   explicitly clone <code>Attr</code> nodes to re-use them in other 
129         *   elements.
130         */
131        public Attr setAttributeNode(Attr newAttr)
132                                     throws DOMException;
133    
134        /**
135         * Removes the specified attribute node. If a default value for the 
136         * removed <code>Attr</code> node is defined in the DTD, a new node 
137         * immediately appears with the default value as well as the 
138         * corresponding namespace URI, local name, and prefix when applicable. 
139         * The implementation may handle default values from other schemas 
140         * similarly but applications should use 
141         * <code>Document.normalizeDocument()</code> to guarantee this 
142         * information is up-to-date.
143         * @param oldAttr The <code>Attr</code> node to remove from the attribute 
144         *   list.
145         * @return The <code>Attr</code> node that was removed.
146         * @exception DOMException
147         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
148         *   <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute 
149         *   of the element.
150         */
151        public Attr removeAttributeNode(Attr oldAttr)
152                                        throws DOMException;
153    
154        /**
155         * Returns a <code>NodeList</code> of all descendant <code>Elements</code> 
156         * with a given tag name, in document order.
157         * @param name The name of the tag to match on. The special value "*" 
158         *   matches all tags.
159         * @return A list of matching <code>Element</code> nodes.
160         */
161        public NodeList getElementsByTagName(String name);
162    
163        /**
164         * Retrieves an attribute value by local name and namespace URI.
165         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
166         * , applications must use the value <code>null</code> as the 
167         * <code>namespaceURI</code> parameter for methods if they wish to have 
168         * no namespace.
169         * @param namespaceURI The namespace URI of the attribute to retrieve.
170         * @param localName The local name of the attribute to retrieve.
171         * @return The <code>Attr</code> value as a string, or the empty string 
172         *   if that attribute does not have a specified or default value.
173         * @exception DOMException
174         *   NOT_SUPPORTED_ERR: May be raised if the implementation does not 
175         *   support the feature <code>"XML"</code> and the language exposed 
176         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
177         * @since DOM Level 2
178         */
179        public String getAttributeNS(String namespaceURI, 
180                                     String localName)
181                                     throws DOMException;
182    
183        /**
184         * Adds a new attribute. If an attribute with the same local name and 
185         * namespace URI is already present on the element, its prefix is 
186         * changed to be the prefix part of the <code>qualifiedName</code>, and 
187         * its value is changed to be the <code>value</code> parameter. This 
188         * value is a simple string; it is not parsed as it is being set. So any 
189         * markup (such as syntax to be recognized as an entity reference) is 
190         * treated as literal text, and needs to be appropriately escaped by the 
191         * implementation when it is written out. In order to assign an 
192         * attribute value that contains entity references, the user must create 
193         * an <code>Attr</code> node plus any <code>Text</code> and 
194         * <code>EntityReference</code> nodes, build the appropriate subtree, 
195         * and use <code>setAttributeNodeNS</code> or 
196         * <code>setAttributeNode</code> to assign it as the value of an 
197         * attribute.
198         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
199         * , applications must use the value <code>null</code> as the 
200         * <code>namespaceURI</code> parameter for methods if they wish to have 
201         * no namespace.
202         * @param namespaceURI The namespace URI of the attribute to create or 
203         *   alter.
204         * @param qualifiedName The qualified name of the attribute to create or 
205         *   alter.
206         * @param value The value to set in string form.
207         * @exception DOMException
208         *   INVALID_CHARACTER_ERR: Raised if the specified qualified name is not 
209         *   an XML name according to the XML version in use specified in the 
210         *   <code>Document.xmlVersion</code> attribute.
211         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
212         *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is 
213         *   malformed per the Namespaces in XML specification, if the 
214         *   <code>qualifiedName</code> has a prefix and the 
215         *   <code>namespaceURI</code> is <code>null</code>, if the 
216         *   <code>qualifiedName</code> has a prefix that is "xml" and the 
217         *   <code>namespaceURI</code> is different from "<a href='http://www.w3.org/XML/1998/namespace'>
218         *   http://www.w3.org/XML/1998/namespace</a>", if the <code>qualifiedName</code> or its prefix is "xmlns" and the 
219         *   <code>namespaceURI</code> is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if the <code>namespaceURI</code> is "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>" and neither the <code>qualifiedName</code> nor its prefix is "xmlns".
220         *   <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 
221         *   support the feature <code>"XML"</code> and the language exposed 
222         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
223         * @since DOM Level 2
224         */
225        public void setAttributeNS(String namespaceURI, 
226                                   String qualifiedName, 
227                                   String value)
228                                   throws DOMException;
229    
230        /**
231         * Removes an attribute by local name and namespace URI. If a default 
232         * value for the removed attribute is defined in the DTD, a new 
233         * attribute immediately appears with the default value as well as the 
234         * corresponding namespace URI, local name, and prefix when applicable. 
235         * The implementation may handle default values from other schemas 
236         * similarly but applications should use 
237         * <code>Document.normalizeDocument()</code> to guarantee this 
238         * information is up-to-date.
239         * <br>If no attribute with this local name and namespace URI is found, 
240         * this method has no effect.
241         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
242         * , applications must use the value <code>null</code> as the 
243         * <code>namespaceURI</code> parameter for methods if they wish to have 
244         * no namespace.
245         * @param namespaceURI The namespace URI of the attribute to remove.
246         * @param localName The local name of the attribute to remove.
247         * @exception DOMException
248         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
249         *   <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 
250         *   support the feature <code>"XML"</code> and the language exposed 
251         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
252         * @since DOM Level 2
253         */
254        public void removeAttributeNS(String namespaceURI, 
255                                      String localName)
256                                      throws DOMException;
257    
258        /**
259         * Retrieves an <code>Attr</code> node by local name and namespace URI.
260         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
261         * , applications must use the value <code>null</code> as the 
262         * <code>namespaceURI</code> parameter for methods if they wish to have 
263         * no namespace.
264         * @param namespaceURI The namespace URI of the attribute to retrieve.
265         * @param localName The local name of the attribute to retrieve.
266         * @return The <code>Attr</code> node with the specified attribute local 
267         *   name and namespace URI or <code>null</code> if there is no such 
268         *   attribute.
269         * @exception DOMException
270         *   NOT_SUPPORTED_ERR: May be raised if the implementation does not 
271         *   support the feature <code>"XML"</code> and the language exposed 
272         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
273         * @since DOM Level 2
274         */
275        public Attr getAttributeNodeNS(String namespaceURI, 
276                                       String localName)
277                                       throws DOMException;
278    
279        /**
280         * Adds a new attribute. If an attribute with that local name and that 
281         * namespace URI is already present in the element, it is replaced by 
282         * the new one. Replacing an attribute node by itself has no effect.
283         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
284         * , applications must use the value <code>null</code> as the 
285         * <code>namespaceURI</code> parameter for methods if they wish to have 
286         * no namespace.
287         * @param newAttr The <code>Attr</code> node to add to the attribute list.
288         * @return If the <code>newAttr</code> attribute replaces an existing 
289         *   attribute with the same local name and namespace URI, the replaced 
290         *   <code>Attr</code> node is returned, otherwise <code>null</code> is 
291         *   returned.
292         * @exception DOMException
293         *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a 
294         *   different document than the one that created the element.
295         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
296         *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an 
297         *   attribute of another <code>Element</code> object. The DOM user must 
298         *   explicitly clone <code>Attr</code> nodes to re-use them in other 
299         *   elements.
300         *   <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 
301         *   support the feature <code>"XML"</code> and the language exposed 
302         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
303         * @since DOM Level 2
304         */
305        public Attr setAttributeNodeNS(Attr newAttr)
306                                       throws DOMException;
307    
308        /**
309         * Returns a <code>NodeList</code> of all the descendant 
310         * <code>Elements</code> with a given local name and namespace URI in 
311         * document order.
312         * @param namespaceURI The namespace URI of the elements to match on. The 
313         *   special value "*" matches all namespaces.
314         * @param localName The local name of the elements to match on. The 
315         *   special value "*" matches all local names.
316         * @return A new <code>NodeList</code> object containing all the matched 
317         *   <code>Elements</code>.
318         * @exception DOMException
319         *   NOT_SUPPORTED_ERR: May be raised if the implementation does not 
320         *   support the feature <code>"XML"</code> and the language exposed 
321         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
322         * @since DOM Level 2
323         */
324        public NodeList getElementsByTagNameNS(String namespaceURI, 
325                                               String localName)
326                                               throws DOMException;
327    
328        /**
329         * Returns <code>true</code> when an attribute with a given name is 
330         * specified on this element or has a default value, <code>false</code> 
331         * otherwise.
332         * @param name The name of the attribute to look for.
333         * @return <code>true</code> if an attribute with the given name is 
334         *   specified on this element or has a default value, <code>false</code>
335         *    otherwise.
336         * @since DOM Level 2
337         */
338        public boolean hasAttribute(String name);
339    
340        /**
341         * Returns <code>true</code> when an attribute with a given local name and 
342         * namespace URI is specified on this element or has a default value, 
343         * <code>false</code> otherwise.
344         * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
345         * , applications must use the value <code>null</code> as the 
346         * <code>namespaceURI</code> parameter for methods if they wish to have 
347         * no namespace.
348         * @param namespaceURI The namespace URI of the attribute to look for.
349         * @param localName The local name of the attribute to look for.
350         * @return <code>true</code> if an attribute with the given local name 
351         *   and namespace URI is specified or has a default value on this 
352         *   element, <code>false</code> otherwise.
353         * @exception DOMException
354         *   NOT_SUPPORTED_ERR: May be raised if the implementation does not 
355         *   support the feature <code>"XML"</code> and the language exposed 
356         *   through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 
357         * @since DOM Level 2
358         */
359        public boolean hasAttributeNS(String namespaceURI, 
360                                      String localName)
361                                      throws DOMException;
362    
363        /**
364         *  The type information associated with this element. 
365         * @since DOM Level 3
366         */
367        public TypeInfo getSchemaTypeInfo();
368    
369        /**
370         *  If the parameter <code>isId</code> is <code>true</code>, this method 
371         * declares the specified attribute to be a user-determined ID attribute
372         * . This affects the value of <code>Attr.isId</code> and the behavior 
373         * of <code>Document.getElementById</code>, but does not change any 
374         * schema that may be in use, in particular this does not affect the 
375         * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 
376         * node. Use the value <code>false</code> for the parameter 
377         * <code>isId</code> to undeclare an attribute for being a 
378         * user-determined ID attribute. 
379         * <br> To specify an attribute by local name and namespace URI, use the 
380         * <code>setIdAttributeNS</code> method. 
381         * @param name The name of the attribute.
382         * @param isId Whether the attribute is a of type ID.
383         * @exception DOMException
384         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
385         *   <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 
386         *   of this element.
387         * @since DOM Level 3
388         */
389        public void setIdAttribute(String name, 
390                                   boolean isId)
391                                   throws DOMException;
392    
393        /**
394         *  If the parameter <code>isId</code> is <code>true</code>, this method 
395         * declares the specified attribute to be a user-determined ID attribute
396         * . This affects the value of <code>Attr.isId</code> and the behavior 
397         * of <code>Document.getElementById</code>, but does not change any 
398         * schema that may be in use, in particular this does not affect the 
399         * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 
400         * node. Use the value <code>false</code> for the parameter 
401         * <code>isId</code> to undeclare an attribute for being a 
402         * user-determined ID attribute. 
403         * @param namespaceURI The namespace URI of the attribute.
404         * @param localName The local name of the attribute.
405         * @param isId Whether the attribute is a of type ID.
406         * @exception DOMException
407         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
408         *   <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 
409         *   of this element.
410         * @since DOM Level 3
411         */
412        public void setIdAttributeNS(String namespaceURI, 
413                                     String localName, 
414                                     boolean isId)
415                                     throws DOMException;
416    
417        /**
418         *  If the parameter <code>isId</code> is <code>true</code>, this method 
419         * declares the specified attribute to be a user-determined ID attribute
420         * . This affects the value of <code>Attr.isId</code> and the behavior 
421         * of <code>Document.getElementById</code>, but does not change any 
422         * schema that may be in use, in particular this does not affect the 
423         * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 
424         * node. Use the value <code>false</code> for the parameter 
425         * <code>isId</code> to undeclare an attribute for being a 
426         * user-determined ID attribute. 
427         * @param idAttr The attribute node.
428         * @param isId Whether the attribute is a of type ID.
429         * @exception DOMException
430         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
431         *   <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 
432         *   of this element.
433         * @since DOM Level 3
434         */
435        public void setIdAttributeNode(Attr idAttr, 
436                                       boolean isId)
437                                       throws DOMException;
438    
439    }