View Javadoc
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&amp;#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&amp;#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&amp;lt;6"</pre>
140  * </td>
141  * <td valign='top' rowspan='1' colspan='1'>
142  * <pre>"y&lt;6"</pre>
143  * </td>
144  * <td valign='top' rowspan='1' colspan='1'>
145  * <pre>"y&amp;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&amp;#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&amp;#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  * &lt;!ENTITY e '...&amp;#10;...'&gt; [...]&gt; "x=5&amp;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 }