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>Attr</code> interface represents an attribute in an 
   17    * <code>Element</code> object. Typically the allowable values for the 
   18    * attribute are defined in a schema associated with the document.
   19    * <p><code>Attr</code> objects inherit the <code>Node</code> interface, but 
   20    * since they are not actually child nodes of the element they describe, the 
   21    * DOM does not consider them part of the document tree. Thus, the 
   22    * <code>Node</code> attributes <code>parentNode</code>, 
   23    * <code>previousSibling</code>, and <code>nextSibling</code> have a 
   24    * <code>null</code> value for <code>Attr</code> objects. The DOM takes the 
   25    * view that attributes are properties of elements rather than having a 
   26    * separate identity from the elements they are associated with; this should 
   27    * make it more efficient to implement such features as default attributes 
   28    * associated with all elements of a given type. Furthermore, 
   29    * <code>Attr</code> nodes may not be immediate children of a 
   30    * <code>DocumentFragment</code>. However, they can be associated with 
   31    * <code>Element</code> nodes contained within a 
   32    * <code>DocumentFragment</code>. In short, users and implementors of the 
   33    * DOM need to be aware that <code>Attr</code> nodes have some things in 
   34    * common with other objects inheriting the <code>Node</code> interface, but 
   35    * they also are quite distinct.
   36    * <p>The attribute's effective value is determined as follows: if this 
   37    * attribute has been explicitly assigned any value, that value is the 
   38    * attribute's effective value; otherwise, if there is a declaration for 
   39    * this attribute, and that declaration includes a default value, then that 
   40    * default value is the attribute's effective value; otherwise, the 
   41    * attribute does not exist on this element in the structure model until it 
   42    * has been explicitly added. Note that the <code>Node.nodeValue</code> 
   43    * attribute on the <code>Attr</code> instance can also be used to retrieve 
   44    * the string version of the attribute's value(s).
   45    * <p> If the attribute was not explicitly given a value in the instance 
   46    * document but has a default value provided by the schema associated with 
   47    * the document, an attribute node will be created with 
   48    * <code>specified</code> set to <code>false</code>. Removing attribute 
   49    * nodes for which a default value is defined in the schema generates a new 
   50    * attribute node with the default value and <code>specified</code> set to 
   51    * <code>false</code>. If validation occurred while invoking 
   52    * <code>Document.normalizeDocument()</code>, attribute nodes with 
   53    * <code>specified</code> equals to <code>false</code> are recomputed 
   54    * according to the default attribute values provided by the schema. If no 
   55    * default value is associate with this attribute in the schema, the 
   56    * attribute node is discarded. 
   57    * <p>In XML, where the value of an attribute can contain entity references, 
   58    * the child nodes of the <code>Attr</code> node may be either 
   59    * <code>Text</code> or <code>EntityReference</code> nodes (when these are 
   60    * in use; see the description of <code>EntityReference</code> for 
   61    * discussion). 
   62    * <p>The DOM Core represents all attribute values as simple strings, even if 
   63    * the DTD or schema associated with the document declares them of some 
   64    * specific type such as tokenized. 
   65    * <p>The way attribute value normalization is performed by the DOM 
   66    * implementation depends on how much the implementation knows about the 
   67    * schema in use. Typically, the <code>value</code> and 
   68    * <code>nodeValue</code> attributes of an <code>Attr</code> node initially 
   69    * returns the normalized value given by the parser. It is also the case 
   70    * after <code>Document.normalizeDocument()</code> is called (assuming the 
   71    * right options have been set). But this may not be the case after 
   72    * mutation, independently of whether the mutation is performed by setting 
   73    * the string value directly or by changing the <code>Attr</code> child 
   74    * nodes. In particular, this is true when <a href='http://www.w3.org/TR/2004/REC-xml-20040204#dt-charref'>character 
   75    * references</a> are involved, given that they are not represented in the DOM and they 
   76    * impact attribute value normalization. On the other hand, if the 
   77    * implementation knows about the schema in use when the attribute value is 
   78    * changed, and it is of a different type than CDATA, it may normalize it 
   79    * again at that time. This is especially true of specialized DOM 
   80    * implementations, such as SVG DOM implementations, which store attribute 
   81    * values in an internal form different from a string.
   82    * <p>The following table gives some examples of the relations between the 
   83    * attribute value in the original document (parsed attribute), the value as 
   84    * exposed in the DOM, and the serialization of the value: 
   85    * <table border='1' cellpadding='3'>
   86    * <tr>
   87    * <th>Examples</th>
   88    * <th>Parsed 
   89    * attribute value</th>
   90    * <th>Initial <code>Attr.value</code></th>
   91    * <th>Serialized attribute value</th>
   92    * </tr>
   93    * <tr>
   94    * <td valign='top' rowspan='1' colspan='1'>
   95    * Character reference</td>
   96    * <td valign='top' rowspan='1' colspan='1'>
   97    * <pre>"x&amp;#178;=5"</pre>
   98    * </td>
   99    * <td valign='top' rowspan='1' colspan='1'>
  100    * <pre>"x\u00b2=5"</pre>
  101    * </td>
  102    * <td valign='top' rowspan='1' colspan='1'>
  103    * <pre>"x&amp;#178;=5"</pre>
  104    * </td>
  105    * </tr>
  106    * <tr>
  107    * <td valign='top' rowspan='1' colspan='1'>Built-in 
  108    * character entity</td>
  109    * <td valign='top' rowspan='1' colspan='1'>
  110    * <pre>"y&amp;lt;6"</pre>
  111    * </td>
  112    * <td valign='top' rowspan='1' colspan='1'>
  113    * <pre>"y&lt;6"</pre>
  114    * </td>
  115    * <td valign='top' rowspan='1' colspan='1'>
  116    * <pre>"y&amp;lt;6"</pre>
  117    * </td>
  118    * </tr>
  119    * <tr>
  120    * <td valign='top' rowspan='1' colspan='1'>Literal newline between</td>
  121    * <td valign='top' rowspan='1' colspan='1'>
  122    * <pre>
  123    * "x=5&amp;#10;y=6"</pre>
  124    * </td>
  125    * <td valign='top' rowspan='1' colspan='1'>
  126    * <pre>"x=5 y=6"</pre>
  127    * </td>
  128    * <td valign='top' rowspan='1' colspan='1'>
  129    * <pre>"x=5&amp;#10;y=6"</pre>
  130    * </td>
  131    * </tr>
  132    * <tr>
  133    * <td valign='top' rowspan='1' colspan='1'>Normalized newline between</td>
  134    * <td valign='top' rowspan='1' colspan='1'>
  135    * <pre>"x=5 
  136    * y=6"</pre>
  137    * </td>
  138    * <td valign='top' rowspan='1' colspan='1'>
  139    * <pre>"x=5 y=6"</pre>
  140    * </td>
  141    * <td valign='top' rowspan='1' colspan='1'>
  142    * <pre>"x=5 y=6"</pre>
  143    * </td>
  144    * </tr>
  145    * <tr>
  146    * <td valign='top' rowspan='1' colspan='1'>Entity <code>e</code> with literal newline</td>
  147    * <td valign='top' rowspan='1' colspan='1'>
  148    * <pre>
  149    * &lt;!ENTITY e '...&amp;#10;...'&gt; [...]&gt; "x=5&amp;e;y=6"</pre>
  150    * </td>
  151    * <td valign='top' rowspan='1' colspan='1'><em>Dependent on Implementation and Load Options</em></td>
  152    * <td valign='top' rowspan='1' colspan='1'><em>Dependent on Implementation and Load/Save Options</em></td>
  153    * </tr>
  154    * </table>
  155    * <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>.
  156    */
  157   public interface Attr extends Node {
  158       /**
  159        * Returns the name of this attribute. If <code>Node.localName</code> is 
  160        * different from <code>null</code>, this attribute is a qualified name.
  161        */
  162       public String getName();
  163   
  164       /**
  165        *  <code>True</code> if this attribute was explicitly given a value in 
  166        * the instance document, <code>false</code> otherwise. If the 
  167        * application changed the value of this attribute node (even if it ends 
  168        * up having the same value as the default value) then it is set to 
  169        * <code>true</code>. The implementation may handle attributes with 
  170        * default values from other schemas similarly but applications should 
  171        * use <code>Document.normalizeDocument()</code> to guarantee this 
  172        * information is up-to-date. 
  173        */
  174       public boolean getSpecified();
  175   
  176       /**
  177        * On retrieval, the value of the attribute is returned as a string. 
  178        * Character and general entity references are replaced with their 
  179        * values. See also the method <code>getAttribute</code> on the 
  180        * <code>Element</code> interface.
  181        * <br>On setting, this creates a <code>Text</code> node with the unparsed 
  182        * contents of the string, i.e. any characters that an XML processor 
  183        * would recognize as markup are instead treated as literal text. See 
  184        * also the method <code>Element.setAttribute()</code>.
  185        * <br> Some specialized implementations, such as some [<a href='http://www.w3.org/TR/2003/REC-SVG11-20030114/'>SVG 1.1</a>] 
  186        * implementations, may do normalization automatically, even after 
  187        * mutation; in such case, the value on retrieval may differ from the 
  188        * value on setting. 
  189        */
  190       public String getValue();
  191       /**
  192        * On retrieval, the value of the attribute is returned as a string. 
  193        * Character and general entity references are replaced with their 
  194        * values. See also the method <code>getAttribute</code> on the 
  195        * <code>Element</code> interface.
  196        * <br>On setting, this creates a <code>Text</code> node with the unparsed 
  197        * contents of the string, i.e. any characters that an XML processor 
  198        * would recognize as markup are instead treated as literal text. See 
  199        * also the method <code>Element.setAttribute()</code>.
  200        * <br> Some specialized implementations, such as some [<a href='http://www.w3.org/TR/2003/REC-SVG11-20030114/'>SVG 1.1</a>] 
  201        * implementations, may do normalization automatically, even after 
  202        * mutation; in such case, the value on retrieval may differ from the 
  203        * value on setting. 
  204        * @exception DOMException
  205        *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
  206        */
  207       public void setValue(String value)
  208                               throws DOMException;
  209   
  210       /**
  211        * The <code>Element</code> node this attribute is attached to or 
  212        * <code>null</code> if this attribute is not in use.
  213        * @since DOM Level 2
  214        */
  215       public Element getOwnerElement();
  216   
  217       /**
  218        *  The type information associated with this attribute. While the type 
  219        * information contained in this attribute is guarantee to be correct 
  220        * after loading the document or invoking 
  221        * <code>Document.normalizeDocument()</code>, <code>schemaTypeInfo</code>
  222        *  may not be reliable if the node was moved. 
  223        * @since DOM Level 3
  224        */
  225       public TypeInfo getSchemaTypeInfo();
  226   
  227       /**
  228        *  Returns whether this attribute is known to be of type ID (i.e. to 
  229        * contain an identifier for its owner element) or not. When it is and 
  230        * its value is unique, the <code>ownerElement</code> of this attribute 
  231        * can be retrieved using the method <code>Document.getElementById</code>
  232        * . The implementation could use several ways to determine if an 
  233        * attribute node is known to contain an identifier: 
  234        * <ul>
  235        * <li> If validation 
  236        * occurred using an XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>]
  237        *  while loading the document or while invoking 
  238        * <code>Document.normalizeDocument()</code>, the post-schema-validation 
  239        * infoset contributions (PSVI contributions) values are used to 
  240        * determine if this attribute is a schema-determined ID attribute using 
  241        * the <a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/#term-sdi'>
  242        * schema-determined ID</a> definition in [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>]
  243        * . 
  244        * </li>
  245        * <li> If validation occurred using a DTD while loading the document or 
  246        * while invoking <code>Document.normalizeDocument()</code>, the infoset <b>[type definition]</b> value is used to determine if this attribute is a DTD-determined ID 
  247        * attribute using the <a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/#term-ddi'>
  248        * DTD-determined ID</a> definition in [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>]
  249        * . 
  250        * </li>
  251        * <li> from the use of the methods <code>Element.setIdAttribute()</code>, 
  252        * <code>Element.setIdAttributeNS()</code>, or 
  253        * <code>Element.setIdAttributeNode()</code>, i.e. it is an 
  254        * user-determined ID attribute; 
  255        * <p ><b>Note:</b>  XPointer framework (see section 3.2 in [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>]
  256        * ) consider the DOM user-determined ID attribute as being part of the 
  257        * XPointer externally-determined ID definition. 
  258        * </li>
  259        * <li> using mechanisms that 
  260        * are outside the scope of this specification, it is then an 
  261        * externally-determined ID attribute. This includes using schema 
  262        * languages different from XML schema and DTD. 
  263        * </li>
  264        * </ul>
  265        * <br> If validation occurred while invoking 
  266        * <code>Document.normalizeDocument()</code>, all user-determined ID 
  267        * attributes are reset and all attribute nodes ID information are then 
  268        * reevaluated in accordance to the schema used. As a consequence, if 
  269        * the <code>Attr.schemaTypeInfo</code> attribute contains an ID type, 
  270        * <code>isId</code> will always return true. 
  271        * @since DOM Level 3
  272        */
  273       public boolean isId();
  274   
  275   }

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