libjava/org/w3c/dom/Element.java

   1 /*\r
   2  * Copyright (c) 2000 World Wide Web Consortium,\r
   3  * (Massachusetts Institute of Technology, Institut National de\r
   4  * Recherche en Informatique et en Automatique, Keio University). All\r
   5  * Rights Reserved. This program is distributed under the W3C's Software\r
   6  * Intellectual Property License. This program is distributed in the\r
   7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even\r
   8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR\r
   9  * PURPOSE.\r
  10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.\r
  11  */\r
  12 \r
  13 package org.w3c.dom;\r
  14 \r
  15 /**\r
  16  * The <code>Element</code> interface represents an element in an HTML or XML \r
  17  * document. Elements may have attributes associated with them; since the \r
  18  * <code>Element</code> interface inherits from <code>Node</code>, the \r
  19  * generic <code>Node</code> interface attribute <code>attributes</code> may \r
  20  * be used to retrieve the set of all attributes for an element. There are \r
  21  * methods on the <code>Element</code> interface to retrieve either an \r
  22  * <code>Attr</code> object by name or an attribute value by name. In XML, \r
  23  * where an attribute value may contain entity references, an \r
  24  * <code>Attr</code> object should be retrieved to examine the possibly \r
  25  * fairly complex sub-tree representing the attribute value. On the other \r
  26  * hand, in HTML, where all attributes have simple string values, methods to \r
  27  * directly access an attribute value can safely be used as a convenience.In \r
  28  * DOM Level 2, the method <code>normalize</code> is inherited from the \r
  29  * <code>Node</code> interface where it was moved.\r
  30  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.\r
  31  */\r
  32 public interface Element extends Node {\r
  33     /**\r
  34      * The name of the element. For example, in: \r
  35      * <pre> &lt;elementExample \r
  36      * id="demo"&gt; ... &lt;/elementExample&gt; , </pre>\r
  37      *  <code>tagName</code> has \r
  38      * the value <code>"elementExample"</code>. Note that this is \r
  39      * case-preserving in XML, as are all of the operations of the DOM. The \r
  40      * HTML DOM returns the <code>tagName</code> of an HTML element in the \r
  41      * canonical uppercase form, regardless of the case in the source HTML \r
  42      * document. \r
  43      */\r
  44     public String getTagName();\r
  45 \r
  46     /**\r
  47      * Retrieves an attribute value by name.\r
  48      * @param nameThe name of the attribute to retrieve.\r
  49      * @return The <code>Attr</code> value as a string, or the empty string \r
  50      *   if that attribute does not have a specified or default value.\r
  51      */\r
  52     public String getAttribute(String name);\r
  53 \r
  54     /**\r
  55      * Adds a new attribute. If an attribute with that name is already present \r
  56      * in the element, its value is changed to be that of the value \r
  57      * parameter. This value is a simple string; it is not parsed as it is \r
  58      * being set. So any markup (such as syntax to be recognized as an \r
  59      * entity reference) is treated as literal text, and needs to be \r
  60      * appropriately escaped by the implementation when it is written out. \r
  61      * In order to assign an attribute value that contains entity \r
  62      * references, the user must create an <code>Attr</code> node plus any \r
  63      * <code>Text</code> and <code>EntityReference</code> nodes, build the \r
  64      * appropriate subtree, and use <code>setAttributeNode</code> to assign \r
  65      * it as the value of an attribute.\r
  66      * <br>To set an attribute with a qualified name and namespace URI, use \r
  67      * the <code>setAttributeNS</code> method.\r
  68      * @param nameThe name of the attribute to create or alter.\r
  69      * @param valueValue to set in string form.\r
  70      * @exception DOMException\r
  71      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an \r
  72      *   illegal character.\r
  73      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
  74      */\r
  75     public void setAttribute(String name, \r
  76                              String value)\r
  77                              throws DOMException;\r
  78 \r
  79     /**\r
  80      * Removes an attribute by name. If the removed attribute is known to have \r
  81      * a default value, an attribute immediately appears containing the \r
  82      * default value as well as the corresponding namespace URI, local name, \r
  83      * and prefix when applicable.\r
  84      * <br>To remove an attribute by local name and namespace URI, use the \r
  85      * <code>removeAttributeNS</code> method.\r
  86      * @param nameThe name of the attribute to remove.\r
  87      * @exception DOMException\r
  88      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
  89      */\r
  90     public void removeAttribute(String name)\r
  91                                 throws DOMException;\r
  92 \r
  93     /**\r
  94      * Retrieves an attribute node by name.\r
  95      * <br>To retrieve an attribute node by qualified name and namespace URI, \r
  96      * use the <code>getAttributeNodeNS</code> method.\r
  97      * @param nameThe name (<code>nodeName</code>) of the attribute to \r
  98      *   retrieve.\r
  99      * @return The <code>Attr</code> node with the specified name (\r
 100      *   <code>nodeName</code>) or <code>null</code> if there is no such \r
 101      *   attribute.\r
 102      */\r
 103     public Attr getAttributeNode(String name);\r
 104 \r
 105     /**\r
 106      * Adds a new attribute node. If an attribute with that name (\r
 107      * <code>nodeName</code>) is already present in the element, it is \r
 108      * replaced by the new one.\r
 109      * <br>To add a new attribute node with a qualified name and namespace \r
 110      * URI, use the <code>setAttributeNodeNS</code> method.\r
 111      * @param newAttrThe <code>Attr</code> node to add to the attribute list.\r
 112      * @return If the <code>newAttr</code> attribute replaces an existing \r
 113      *   attribute, the replaced <code>Attr</code> node is returned, \r
 114      *   otherwise <code>null</code> is returned.\r
 115      * @exception DOMException\r
 116      *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a \r
 117      *   different document than the one that created the element.\r
 118      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 119      *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an \r
 120      *   attribute of another <code>Element</code> object. The DOM user must \r
 121      *   explicitly clone <code>Attr</code> nodes to re-use them in other \r
 122      *   elements.\r
 123      */\r
 124     public Attr setAttributeNode(Attr newAttr)\r
 125                                  throws DOMException;\r
 126 \r
 127     /**\r
 128      * Removes the specified attribute node. If the removed <code>Attr</code> \r
 129      * has a default value it is immediately replaced. The replacing \r
 130      * attribute has the same namespace URI and local name, as well as the \r
 131      * original prefix, when applicable.\r
 132      * @param oldAttrThe <code>Attr</code> node to remove from the attribute \r
 133      *   list.\r
 134      * @return The <code>Attr</code> node that was removed.\r
 135      * @exception DOMException\r
 136      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 137      *   <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute \r
 138      *   of the element.\r
 139      */\r
 140     public Attr removeAttributeNode(Attr oldAttr)\r
 141                                     throws DOMException;\r
 142 \r
 143     /**\r
 144      * Returns a <code>NodeList</code> of all descendant <code>Elements</code> \r
 145      * with a given tag name, in the order in which they are encountered in \r
 146      * a preorder traversal of this <code>Element</code> tree.\r
 147      * @param nameThe name of the tag to match on. The special value "*" \r
 148      *   matches all tags.\r
 149      * @return A list of matching <code>Element</code> nodes.\r
 150      */\r
 151     public NodeList getElementsByTagName(String name);\r
 152 \r
 153     /**\r
 154      * Retrieves an attribute value by local name and namespace URI. HTML-only \r
 155      * DOM implementations do not need to implement this method.\r
 156      * @param namespaceURIThe namespace URI of the attribute to retrieve.\r
 157      * @param localNameThe local name of the attribute to retrieve.\r
 158      * @return The <code>Attr</code> value as a string, or the empty string \r
 159      *   if that attribute does not have a specified or default value.\r
 160      * @since DOM Level 2\r
 161      */\r
 162     public String getAttributeNS(String namespaceURI, \r
 163                                  String localName);\r
 164 \r
 165     /**\r
 166      * Adds a new attribute. If an attribute with the same local name and \r
 167      * namespace URI is already present on the element, its prefix is \r
 168      * changed to be the prefix part of the <code>qualifiedName</code>, and \r
 169      * its value is changed to be the <code>value</code> parameter. This \r
 170      * value is a simple string; it is not parsed as it is being set. So any \r
 171      * markup (such as syntax to be recognized as an entity reference) is \r
 172      * treated as literal text, and needs to be appropriately escaped by the \r
 173      * implementation when it is written out. In order to assign an \r
 174      * attribute value that contains entity references, the user must create \r
 175      * an <code>Attr</code> node plus any <code>Text</code> and \r
 176      * <code>EntityReference</code> nodes, build the appropriate subtree, \r
 177      * and use <code>setAttributeNodeNS</code> or \r
 178      * <code>setAttributeNode</code> to assign it as the value of an \r
 179      * attribute.\r
 180      * <br>HTML-only DOM implementations do not need to implement this method.\r
 181      * @param namespaceURIThe namespace URI of the attribute to create or \r
 182      *   alter.\r
 183      * @param qualifiedNameThe qualified name of the attribute to create or \r
 184      *   alter.\r
 185      * @param valueThe value to set in string form.\r
 186      * @exception DOMException\r
 187      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name \r
 188      *   contains an illegal character.\r
 189      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 190      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is \r
 191      *   malformed, if the <code>qualifiedName</code> has a prefix and the \r
 192      *   <code>namespaceURI</code> is <code>null</code>, if the \r
 193      *   <code>qualifiedName</code> has a prefix that is "xml" and the \r
 194      *   <code>namespaceURI</code> is different from "\r
 195      *   http://www.w3.org/XML/1998/namespace", or if the \r
 196      *   <code>qualifiedName</code> is "xmlns" and the \r
 197      *   <code>namespaceURI</code> is different from "\r
 198      *   http://www.w3.org/2000/xmlns/".\r
 199      * @since DOM Level 2\r
 200      */\r
 201     public void setAttributeNS(String namespaceURI, \r
 202                                String qualifiedName, \r
 203                                String value)\r
 204                                throws DOMException;\r
 205 \r
 206     /**\r
 207      * Removes an attribute by local name and namespace URI. If the removed \r
 208      * attribute has a default value it is immediately replaced. The \r
 209      * replacing attribute has the same namespace URI and local name, as \r
 210      * well as the original prefix.\r
 211      * <br>HTML-only DOM implementations do not need to implement this method.\r
 212      * @param namespaceURIThe namespace URI of the attribute to remove.\r
 213      * @param localNameThe local name of the attribute to remove.\r
 214      * @exception DOMException\r
 215      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 216      * @since DOM Level 2\r
 217      */\r
 218     public void removeAttributeNS(String namespaceURI, \r
 219                                   String localName)\r
 220                                   throws DOMException;\r
 221 \r
 222     /**\r
 223      * Retrieves an <code>Attr</code> node by local name and namespace URI. \r
 224      * HTML-only DOM implementations do not need to implement this method.\r
 225      * @param namespaceURIThe namespace URI of the attribute to retrieve.\r
 226      * @param localNameThe local name of the attribute to retrieve.\r
 227      * @return The <code>Attr</code> node with the specified attribute local \r
 228      *   name and namespace URI or <code>null</code> if there is no such \r
 229      *   attribute.\r
 230      * @since DOM Level 2\r
 231      */\r
 232     public Attr getAttributeNodeNS(String namespaceURI, \r
 233                                    String localName);\r
 234 \r
 235     /**\r
 236      * Adds a new attribute. If an attribute with that local name and that \r
 237      * namespace URI is already present in the element, it is replaced by \r
 238      * the new one.\r
 239      * <br>HTML-only DOM implementations do not need to implement this method.\r
 240      * @param newAttrThe <code>Attr</code> node to add to the attribute list.\r
 241      * @return If the <code>newAttr</code> attribute replaces an existing \r
 242      *   attribute with the same local name and namespace URI, the replaced \r
 243      *   <code>Attr</code> node is returned, otherwise <code>null</code> is \r
 244      *   returned.\r
 245      * @exception DOMException\r
 246      *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a \r
 247      *   different document than the one that created the element.\r
 248      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 249      *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an \r
 250      *   attribute of another <code>Element</code> object. The DOM user must \r
 251      *   explicitly clone <code>Attr</code> nodes to re-use them in other \r
 252      *   elements.\r
 253      * @since DOM Level 2\r
 254      */\r
 255     public Attr setAttributeNodeNS(Attr newAttr)\r
 256                                    throws DOMException;\r
 257 \r
 258     /**\r
 259      * Returns a <code>NodeList</code> of all the descendant \r
 260      * <code>Elements</code> with a given local name and namespace URI in \r
 261      * the order in which they are encountered in a preorder traversal of \r
 262      * this <code>Element</code> tree.\r
 263      * <br>HTML-only DOM implementations do not need to implement this method.\r
 264      * @param namespaceURIThe namespace URI of the elements to match on. The \r
 265      *   special value "*" matches all namespaces.\r
 266      * @param localNameThe local name of the elements to match on. The \r
 267      *   special value "*" matches all local names.\r
 268      * @return A new <code>NodeList</code> object containing all the matched \r
 269      *   <code>Elements</code>.\r
 270      * @since DOM Level 2\r
 271      */\r
 272     public NodeList getElementsByTagNameNS(String namespaceURI, \r
 273                                            String localName);\r
 274 \r
 275     /**\r
 276      * Returns <code>true</code> when an attribute with a given name is \r
 277      * specified on this element or has a default value, <code>false</code> \r
 278      * otherwise.\r
 279      * @param nameThe name of the attribute to look for.\r
 280      * @return <code>true</code> if an attribute with the given name is \r
 281      *   specified on this element or has a default value, <code>false</code>\r
 282      *    otherwise.\r
 283      * @since DOM Level 2\r
 284      */\r
 285     public boolean hasAttribute(String name);\r
 286 \r
 287     /**\r
 288      * Returns <code>true</code> when an attribute with a given local name and \r
 289      * namespace URI is specified on this element or has a default value, \r
 290      * <code>false</code> otherwise. HTML-only DOM implementations do not \r
 291      * need to implement this method.\r
 292      * @param namespaceURIThe namespace URI of the attribute to look for.\r
 293      * @param localNameThe local name of the attribute to look for.\r
 294      * @return <code>true</code> if an attribute with the given local name \r
 295      *   and namespace URI is specified or has a default value on this \r
 296      *   element, <code>false</code> otherwise.\r
 297      * @since DOM Level 2\r
 298      */\r
 299     public boolean hasAttributeNS(String namespaceURI, \r
 300                                   String localName);\r
 301 \r
 302 }\r