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