|
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 border='1' cellpadding='3'> |
|
115 * <tr> |
|
116 * <th>Examples</th> |
|
117 * <th>Parsed |
|
118 * attribute value</th> |
|
119 * <th>Initial <code>Attr.value</code></th> |
|
120 * <th>Serialized attribute value</th> |
|
121 * </tr> |
|
122 * <tr> |
|
123 * <td valign='top' rowspan='1' colspan='1'> |
|
124 * Character reference</td> |
|
125 * <td valign='top' rowspan='1' colspan='1'> |
|
126 * <pre>"x&#178;=5"</pre> |
|
127 * </td> |
|
128 * <td valign='top' rowspan='1' colspan='1'> |
|
129 * <pre>"x\u00b2=5"</pre> |
|
130 * </td> |
|
131 * <td valign='top' rowspan='1' colspan='1'> |
|
132 * <pre>"x&#178;=5"</pre> |
|
133 * </td> |
|
134 * </tr> |
|
135 * <tr> |
|
136 * <td valign='top' rowspan='1' colspan='1'>Built-in |
|
137 * character entity</td> |
|
138 * <td valign='top' rowspan='1' colspan='1'> |
|
139 * <pre>"y&lt;6"</pre> |
|
140 * </td> |
|
141 * <td valign='top' rowspan='1' colspan='1'> |
|
142 * <pre>"y<6"</pre> |
|
143 * </td> |
|
144 * <td valign='top' rowspan='1' colspan='1'> |
|
145 * <pre>"y&lt;6"</pre> |
|
146 * </td> |
|
147 * </tr> |
|
148 * <tr> |
|
149 * <td valign='top' rowspan='1' colspan='1'>Literal newline between</td> |
|
150 * <td valign='top' rowspan='1' colspan='1'> |
|
151 * <pre> |
|
152 * "x=5&#10;y=6"</pre> |
|
153 * </td> |
|
154 * <td valign='top' rowspan='1' colspan='1'> |
|
155 * <pre>"x=5 y=6"</pre> |
|
156 * </td> |
|
157 * <td valign='top' rowspan='1' colspan='1'> |
|
158 * <pre>"x=5&#10;y=6"</pre> |
|
159 * </td> |
|
160 * </tr> |
|
161 * <tr> |
|
162 * <td valign='top' rowspan='1' colspan='1'>Normalized newline between</td> |
|
163 * <td valign='top' rowspan='1' colspan='1'> |
|
164 * <pre>"x=5 |
|
165 * y=6"</pre> |
|
166 * </td> |
|
167 * <td valign='top' rowspan='1' colspan='1'> |
|
168 * <pre>"x=5 y=6"</pre> |
|
169 * </td> |
|
170 * <td valign='top' rowspan='1' colspan='1'> |
|
171 * <pre>"x=5 y=6"</pre> |
|
172 * </td> |
|
173 * </tr> |
|
174 * <tr> |
|
175 * <td valign='top' rowspan='1' colspan='1'>Entity <code>e</code> with literal newline</td> |
|
176 * <td valign='top' rowspan='1' colspan='1'> |
|
177 * <pre> |
|
178 * <!ENTITY e '...&#10;...'> [...]> "x=5&e;y=6"</pre> |
|
179 * </td> |
|
180 * <td valign='top' rowspan='1' colspan='1'><em>Dependent on Implementation and Load Options</em></td> |
|
181 * <td valign='top' rowspan='1' colspan='1'><em>Dependent on Implementation and Load/Save Options</em></td> |
|
182 * </tr> |
|
183 * </table> |
|
184 * <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>. |
|
185 */ |
|
186 public interface Attr extends Node { |
|
187 /** |
|
188 * Returns the name of this attribute. If <code>Node.localName</code> is |
|
189 * different from <code>null</code>, this attribute is a qualified name. |
|
190 */ |
|
191 public String getName(); |
|
192 |
|
193 /** |
|
194 * <code>True</code> if this attribute was explicitly given a value in |
|
195 * the instance document, <code>false</code> otherwise. If the |
|
196 * application changed the value of this attribute node (even if it ends |
|
197 * up having the same value as the default value) then it is set to |
|
198 * <code>true</code>. The implementation may handle attributes with |
|
199 * default values from other schemas similarly but applications should |
|
200 * use <code>Document.normalizeDocument()</code> to guarantee this |
|
201 * information is up-to-date. |
|
202 */ |
|
203 public boolean getSpecified(); |
|
204 |
|
205 /** |
|
206 * On retrieval, the value of the attribute is returned as a string. |
|
207 * Character and general entity references are replaced with their |
|
208 * values. See also the method <code>getAttribute</code> on the |
|
209 * <code>Element</code> interface. |
|
210 * <br>On setting, this creates a <code>Text</code> node with the unparsed |
|
211 * contents of the string, i.e. any characters that an XML processor |
|
212 * would recognize as markup are instead treated as literal text. See |
|
213 * also the method <code>Element.setAttribute()</code>. |
|
214 * <br> Some specialized implementations, such as some [<a href='http://www.w3.org/TR/2003/REC-SVG11-20030114/'>SVG 1.1</a>] |
|
215 * implementations, may do normalization automatically, even after |
|
216 * mutation; in such case, the value on retrieval may differ from the |
|
217 * value on setting. |
|
218 */ |
|
219 public String getValue(); |
|
220 /** |
|
221 * On retrieval, the value of the attribute is returned as a string. |
|
222 * Character and general entity references are replaced with their |
|
223 * values. See also the method <code>getAttribute</code> on the |
|
224 * <code>Element</code> interface. |
|
225 * <br>On setting, this creates a <code>Text</code> node with the unparsed |
|
226 * contents of the string, i.e. any characters that an XML processor |
|
227 * would recognize as markup are instead treated as literal text. See |
|
228 * also the method <code>Element.setAttribute()</code>. |
|
229 * <br> Some specialized implementations, such as some [<a href='http://www.w3.org/TR/2003/REC-SVG11-20030114/'>SVG 1.1</a>] |
|
230 * implementations, may do normalization automatically, even after |
|
231 * mutation; in such case, the value on retrieval may differ from the |
|
232 * value on setting. |
|
233 * @exception DOMException |
|
234 * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. |
|
235 */ |
|
236 public void setValue(String value) |
|
237 throws DOMException; |
|
238 |
|
239 /** |
|
240 * The <code>Element</code> node this attribute is attached to or |
|
241 * <code>null</code> if this attribute is not in use. |
|
242 * @since DOM Level 2 |
|
243 */ |
|
244 public Element getOwnerElement(); |
|
245 |
|
246 /** |
|
247 * The type information associated with this attribute. While the type |
|
248 * information contained in this attribute is guarantee to be correct |
|
249 * after loading the document or invoking |
|
250 * <code>Document.normalizeDocument()</code>, <code>schemaTypeInfo</code> |
|
251 * may not be reliable if the node was moved. |
|
252 * @since DOM Level 3 |
|
253 */ |
|
254 public TypeInfo getSchemaTypeInfo(); |
|
255 |
|
256 /** |
|
257 * Returns whether this attribute is known to be of type ID (i.e. to |
|
258 * contain an identifier for its owner element) or not. When it is and |
|
259 * its value is unique, the <code>ownerElement</code> of this attribute |
|
260 * can be retrieved using the method <code>Document.getElementById</code> |
|
261 * . The implementation could use several ways to determine if an |
|
262 * attribute node is known to contain an identifier: |
|
263 * <ul> |
|
264 * <li> If validation |
|
265 * occurred using an XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] |
|
266 * while loading the document or while invoking |
|
267 * <code>Document.normalizeDocument()</code>, the post-schema-validation |
|
268 * infoset contributions (PSVI contributions) values are used to |
|
269 * determine if this attribute is a schema-determined ID attribute using |
|
270 * the <a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/#term-sdi'> |
|
271 * schema-determined ID</a> definition in [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>] |
|
272 * . |
|
273 * </li> |
|
274 * <li> If validation occurred using a DTD while loading the document or |
|
275 * 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 |
|
276 * attribute using the <a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/#term-ddi'> |
|
277 * DTD-determined ID</a> definition in [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>] |
|
278 * . |
|
279 * </li> |
|
280 * <li> from the use of the methods <code>Element.setIdAttribute()</code>, |
|
281 * <code>Element.setIdAttributeNS()</code>, or |
|
282 * <code>Element.setIdAttributeNode()</code>, i.e. it is an |
|
283 * user-determined ID attribute; |
|
284 * <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>] |
|
285 * ) consider the DOM user-determined ID attribute as being part of the |
|
286 * XPointer externally-determined ID definition. |
|
287 * </li> |
|
288 * <li> using mechanisms that |
|
289 * are outside the scope of this specification, it is then an |
|
290 * externally-determined ID attribute. This includes using schema |
|
291 * languages different from XML schema and DTD. |
|
292 * </li> |
|
293 * </ul> |
|
294 * <br> If validation occurred while invoking |
|
295 * <code>Document.normalizeDocument()</code>, all user-determined ID |
|
296 * attributes are reset and all attribute nodes ID information are then |
|
297 * reevaluated in accordance to the schema used. As a consequence, if |
|
298 * the <code>Attr.schemaTypeInfo</code> attribute contains an ID type, |
|
299 * <code>isId</code> will always return true. |
|
300 * @since DOM Level 3 |
|
301 */ |
|
302 public boolean isId(); |
|
303 |
|
304 } |