001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file and, per its terms, should not be removed:
030 *
031 * Copyright (c) 2004 World Wide Web Consortium,
032 *
033 * (Massachusetts Institute of Technology, European Research Consortium for
034 * Informatics and Mathematics, Keio University). All Rights Reserved. This
035 * work is distributed under the W3C(r) Software License [1] in the hope that
036 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
037 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
038 *
039 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
040 */
041
042 package org.w3c.dom;
043
044 /**
045 * The <code>Attr</code> interface represents an attribute in an
046 * <code>Element</code> object. Typically the allowable values for the
047 * attribute are defined in a schema associated with the document.
048 * <p><code>Attr</code> objects inherit the <code>Node</code> interface, but
049 * since they are not actually child nodes of the element they describe, the
050 * DOM does not consider them part of the document tree. Thus, the
051 * <code>Node</code> attributes <code>parentNode</code>,
052 * <code>previousSibling</code>, and <code>nextSibling</code> have a
053 * <code>null</code> value for <code>Attr</code> objects. The DOM takes the
054 * view that attributes are properties of elements rather than having a
055 * separate identity from the elements they are associated with; this should
056 * make it more efficient to implement such features as default attributes
057 * associated with all elements of a given type. Furthermore,
058 * <code>Attr</code> nodes may not be immediate children of a
059 * <code>DocumentFragment</code>. However, they can be associated with
060 * <code>Element</code> nodes contained within a
061 * <code>DocumentFragment</code>. In short, users and implementors of the
062 * DOM need to be aware that <code>Attr</code> nodes have some things in
063 * common with other objects inheriting the <code>Node</code> interface, but
064 * they also are quite distinct.
065 * <p>The attribute's effective value is determined as follows: if this
066 * attribute has been explicitly assigned any value, that value is the
067 * attribute's effective value; otherwise, if there is a declaration for
068 * this attribute, and that declaration includes a default value, then that
069 * default value is the attribute's effective value; otherwise, the
070 * attribute does not exist on this element in the structure model until it
071 * has been explicitly added. Note that the <code>Node.nodeValue</code>
072 * attribute on the <code>Attr</code> instance can also be used to retrieve
073 * the string version of the attribute's value(s).
074 * <p> If the attribute was not explicitly given a value in the instance
075 * document but has a default value provided by the schema associated with
076 * the document, an attribute node will be created with
077 * <code>specified</code> set to <code>false</code>. Removing attribute
078 * nodes for which a default value is defined in the schema generates a new
079 * attribute node with the default value and <code>specified</code> set to
080 * <code>false</code>. If validation occurred while invoking
081 * <code>Document.normalizeDocument()</code>, attribute nodes with
082 * <code>specified</code> equals to <code>false</code> are recomputed
083 * according to the default attribute values provided by the schema. If no
084 * default value is associate with this attribute in the schema, the
085 * attribute node is discarded.
086 * <p>In XML, where the value of an attribute can contain entity references,
087 * the child nodes of the <code>Attr</code> node may be either
088 * <code>Text</code> or <code>EntityReference</code> nodes (when these are
089 * in use; see the description of <code>EntityReference</code> for
090 * discussion).
091 * <p>The DOM Core represents all attribute values as simple strings, even if
092 * the DTD or schema associated with the document declares them of some
093 * specific type such as tokenized.
094 * <p>The way attribute value normalization is performed by the DOM
095 * implementation depends on how much the implementation knows about the
096 * schema in use. Typically, the <code>value</code> and
097 * <code>nodeValue</code> attributes of an <code>Attr</code> node initially
098 * returns the normalized value given by the parser. It is also the case
099 * 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 /**
222 * On retrieval, the value of the attribute is returned as a string.
223 * Character and general entity references are replaced with their
224 * values. See also the method <code>getAttribute</code> on the
225 * <code>Element</code> interface.
226 * <br>On setting, this creates a <code>Text</code> node with the unparsed
227 * contents of the string, i.e. any characters that an XML processor
228 * would recognize as markup are instead treated as literal text. See
229 * also the method <code>Element.setAttribute()</code>.
230 * <br> Some specialized implementations, such as some [<a href='http://www.w3.org/TR/2003/REC-SVG11-20030114/'>SVG 1.1</a>]
231 * implementations, may do normalization automatically, even after
232 * mutation; in such case, the value on retrieval may differ from the
233 * value on setting.
234 * @exception DOMException
235 * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
236 */
237 public void setValue(String value) 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 }
|