Home » xml-commons-external-1.4.01-src » org.w3c » dom » [javadoc | source]

    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   }

Home » xml-commons-external-1.4.01-src » org.w3c » dom » [javadoc | source]