001    /*
002     * Copyright (c) 2004 World Wide Web Consortium,
003     *
004     * (Massachusetts Institute of Technology, European Research Consortium for
005     * Informatics and Mathematics, Keio University). All Rights Reserved. This
006     * work is distributed under the W3C(r) Software License [1] in the hope that
007     * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008     * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009     *
010     * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011     */
012    
013    package org.w3c.dom;
014    
015    /**
016     * The <code>Attr</code> interface represents an attribute in an 
017     * <code>Element</code> object. Typically the allowable values for the 
018     * attribute are defined in a schema associated with the document.
019     * <p><code>Attr</code> objects inherit the <code>Node</code> interface, but 
020     * since they are not actually child nodes of the element they describe, the 
021     * DOM does not consider them part of the document tree. Thus, the 
022     * <code>Node</code> attributes <code>parentNode</code>, 
023     * <code>previousSibling</code>, and <code>nextSibling</code> have a 
024     * <code>null</code> value for <code>Attr</code> objects. The DOM takes the 
025     * view that attributes are properties of elements rather than having a 
026     * separate identity from the elements they are associated with; this should 
027     * make it more efficient to implement such features as default attributes 
028     * associated with all elements of a given type. Furthermore, 
029     * <code>Attr</code> nodes may not be immediate children of a 
030     * <code>DocumentFragment</code>. However, they can be associated with 
031     * <code>Element</code> nodes contained within a 
032     * <code>DocumentFragment</code>. In short, users and implementors of the 
033     * DOM need to be aware that <code>Attr</code> nodes have some things in 
034     * common with other objects inheriting the <code>Node</code> interface, but 
035     * they also are quite distinct.
036     * <p>The attribute's effective value is determined as follows: if this 
037     * attribute has been explicitly assigned any value, that value is the 
038     * attribute's effective value; otherwise, if there is a declaration for 
039     * this attribute, and that declaration includes a default value, then that 
040     * default value is the attribute's effective value; otherwise, the 
041     * attribute does not exist on this element in the structure model until it 
042     * has been explicitly added. Note that the <code>Node.nodeValue</code> 
043     * attribute on the <code>Attr</code> instance can also be used to retrieve 
044     * the string version of the attribute's value(s).
045     * <p> If the attribute was not explicitly given a value in the instance 
046     * document but has a default value provided by the schema associated with 
047     * the document, an attribute node will be created with 
048     * <code>specified</code> set to <code>false</code>. Removing attribute 
049     * nodes for which a default value is defined in the schema generates a new 
050     * attribute node with the default value and <code>specified</code> set to 
051     * <code>false</code>. If validation occurred while invoking 
052     * <code>Document.normalizeDocument()</code>, attribute nodes with 
053     * <code>specified</code> equals to <code>false</code> are recomputed 
054     * according to the default attribute values provided by the schema. If no 
055     * default value is associate with this attribute in the schema, the 
056     * attribute node is discarded. 
057     * <p>In XML, where the value of an attribute can contain entity references, 
058     * the child nodes of the <code>Attr</code> node may be either 
059     * <code>Text</code> or <code>EntityReference</code> nodes (when these are 
060     * in use; see the description of <code>EntityReference</code> for 
061     * discussion). 
062     * <p>The DOM Core represents all attribute values as simple strings, even if 
063     * the DTD or schema associated with the document declares them of some 
064     * specific type such as tokenized. 
065     * <p>The way attribute value normalization is performed by the DOM 
066     * implementation depends on how much the implementation knows about the 
067     * schema in use. Typically, the <code>value</code> and 
068     * <code>nodeValue</code> attributes of an <code>Attr</code> node initially 
069     * returns the normalized value given by the parser. It is also the case 
070     * after <code>Document.normalizeDocument()</code> is called (assuming the 
071     * right options have been set). But this may not be the case after 
072     * mutation, independently of whether the mutation is performed by setting 
073     * the string value directly or by changing the <code>Attr</code> child 
074     * nodes. In particular, this is true when <a href='http://www.w3.org/TR/2004/REC-xml-20040204#dt-charref'>character 
075     * references</a> are involved, given that they are not represented in the DOM and they 
076     * impact attribute value normalization. On the other hand, if the 
077     * implementation knows about the schema in use when the attribute value is 
078     * changed, and it is of a different type than CDATA, it may normalize it 
079     * again at that time. This is especially true of specialized DOM 
080     * implementations, such as SVG DOM implementations, which store attribute 
081     * values in an internal form different from a string.
082     * <p>The following table gives some examples of the relations between the 
083     * attribute value in the original document (parsed attribute), the value as 
084     * exposed in the DOM, and the serialization of the value: 
085     * <table border='1' cellpadding='3'>
086     * <tr>
087     * <th>Examples</th>
088     * <th>Parsed 
089     * attribute value</th>
090     * <th>Initial <code>Attr.value</code></th>
091     * <th>Serialized attribute value</th>
092     * </tr>
093     * <tr>
094     * <td valign='top' rowspan='1' colspan='1'>
095     * Character reference</td>
096     * <td valign='top' rowspan='1' colspan='1'>
097     * <pre>"x&amp;#178;=5"</pre>
098     * </td>
099     * <td valign='top' rowspan='1' colspan='1'>
100     * <pre>"x\u00b2=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 {
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 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 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 value)
208                                throws DOMException;
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 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 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    }