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    }