lib/classpath/external/w3c_dom/org/w3c/dom/Element.java

   1 /*
   2  * Copyright (c) 2004 World Wide Web Consortium,
   3  *
   4  * (Massachusetts Institute of Technology, European Research Consortium for
   5  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6  * work is distributed under the W3C(r) Software License [1] in the hope that
   7  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11  */
  12
  13 package org.w3c.dom;
  14
  15 /**
  16  * The <code>Element</code> interface represents an element in an HTML or XML
  17  * document. Elements may have attributes associated with them; since the
  18  * <code>Element</code> interface inherits from <code>Node</code>, the
  19  * generic <code>Node</code> interface attribute <code>attributes</code> may
  20  * be used to retrieve the set of all attributes for an element. There are
  21  * methods on the <code>Element</code> interface to retrieve either an
  22  * <code>Attr</code> object by name or an attribute value by name. In XML,
  23  * where an attribute value may contain entity references, an
  24  * <code>Attr</code> object should be retrieved to examine the possibly
  25  * fairly complex sub-tree representing the attribute value. On the other
  26  * hand, in HTML, where all attributes have simple string values, methods to
  27  * directly access an attribute value can safely be used as a convenience.
  28  * <p ><b>Note:</b> In DOM Level 2, the method <code>normalize</code> is
  29  * inherited from the <code>Node</code> interface where it was moved.
  30  * <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>.
  31  */
  32 public interface Element extends Node {
  33     /**
  34      * The name of the element. If <code>Node.localName</code> is different
  35      * from <code>null</code>, this attribute is a qualified name. For
  36      * example, in:
  37      * <pre> &lt;elementExample id="demo"&gt; ...
  38      * &lt;/elementExample&gt; , </pre>
  39      *  <code>tagName</code> has the value
  40      * <code>"elementExample"</code>. Note that this is case-preserving in
  41      * XML, as are all of the operations of the DOM. The HTML DOM returns
  42      * the <code>tagName</code> of an HTML element in the canonical
  43      * uppercase form, regardless of the case in the source HTML document.
  44      */
  45     public String getTagName();
  46
  47     /**
  48      * Retrieves an attribute value by name.
  49      * @param name The name of the attribute to retrieve.
  50      * @return The <code>Attr</code> value as a string, or the empty string
  51      *   if that attribute does not have a specified or default value.
  52      */
  53     public String getAttribute(String name);
  54
  55     /**
  56      * Adds a new attribute. If an attribute with that name is already present
  57      * in the element, its value is changed to be that of the value
  58      * parameter. This value is a simple string; it is not parsed as it is
  59      * being set. So any markup (such as syntax to be recognized as an
  60      * entity reference) is treated as literal text, and needs to be
  61      * appropriately escaped by the implementation when it is written out.
  62      * In order to assign an attribute value that contains entity
  63      * references, the user must create an <code>Attr</code> node plus any
  64      * <code>Text</code> and <code>EntityReference</code> nodes, build the
  65      * appropriate subtree, and use <code>setAttributeNode</code> to assign
  66      * it as the value of an attribute.
  67      * <br>To set an attribute with a qualified name and namespace URI, use
  68      * the <code>setAttributeNS</code> method.
  69      * @param name The name of the attribute to create or alter.
  70      * @param value Value to set in string form.
  71      * @exception DOMException
  72      *   INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
  73      *   name according to the XML version in use specified in the
  74      *   <code>Document.xmlVersion</code> attribute.
  75      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
  76      */
  77     public void setAttribute(String name,
  78                              String value)
  79                              throws DOMException;
  80
  81     /**
  82      * Removes an attribute by name. If a default value for the removed
  83      * attribute is defined in the DTD, a new attribute immediately appears
  84      * with the default value as well as the corresponding namespace URI,
  85      * local name, and prefix when applicable. The implementation may handle
  86      * default values from other schemas similarly but applications should
  87      * use <code>Document.normalizeDocument()</code> to guarantee this
  88      * information is up-to-date.
  89      * <br>If no attribute with this name is found, this method has no effect.
  90      * <br>To remove an attribute by local name and namespace URI, use the
  91      * <code>removeAttributeNS</code> method.
  92      * @param name The name of the attribute to remove.
  93      * @exception DOMException
  94      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
  95      */
  96     public void removeAttribute(String name)
  97                                 throws DOMException;
  98
  99     /**
 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 }