libjava/org/w3c/dom/Element.java

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