KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > 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²=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 JavaDoc {
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 JavaDoc 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 JavaDoc 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 JavaDoc value)
208                             throws DOMException JavaDoc;
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 JavaDoc 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 JavaDoc 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 }
276
Popular Tags