Source for org.w3c.dom.Attr

   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: }