/*
 * Copyright (c) 2004 World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C(r) Software License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
 */

package org.w3c.dom;

/**
 * The <code>Attr</code> interface represents an attribute in an 
 * <code>Element</code> object. Typically the allowable values for the 
 * attribute are defined in a schema associated with the document.
 * <p><code>Attr</code> objects inherit the <code>Node</code> interface, but 
 * since they are not actually child nodes of the element they describe, the 
 * DOM does not consider them part of the document tree. Thus, the 
 * <code>Node</code> attributes <code>parentNode</code>, 
 * <code>previousSibling</code>, and <code>nextSibling</code> have a 
 * <code>null</code> value for <code>Attr</code> objects. The DOM takes the 
 * view that attributes are properties of elements rather than having a 
 * separate identity from the elements they are associated with; this should 
 * make it more efficient to implement such features as default attributes 
 * associated with all elements of a given type. Furthermore, 
 * <code>Attr</code> nodes may not be immediate children of a 
 * <code>DocumentFragment</code>. However, they can be associated with 
 * <code>Element</code> nodes contained within a 
 * <code>DocumentFragment</code>. In short, users and implementors of the 
 * DOM need to be aware that <code>Attr</code> nodes have some things in 
 * common with other objects inheriting the <code>Node</code> interface, but 
 * they also are quite distinct.
 * <p>The attribute's effective value is determined as follows: if this 
 * attribute has been explicitly assigned any value, that value is the 
 * attribute's effective value; otherwise, if there is a declaration for 
 * this attribute, and that declaration includes a default value, then that 
 * default value is the attribute's effective value; otherwise, the 
 * attribute does not exist on this element in the structure model until it 
 * has been explicitly added. Note that the <code>Node.nodeValue</code> 
 * attribute on the <code>Attr</code> instance can also be used to retrieve 
 * the string version of the attribute's value(s).
 * <p> If the attribute was not explicitly given a value in the instance 
 * document but has a default value provided by the schema associated with 
 * the document, an attribute node will be created with 
 * <code>specified</code> set to <code>false</code>. Removing attribute 
 * nodes for which a default value is defined in the schema generates a new 
 * attribute node with the default value and <code>specified</code> set to 
 * <code>false</code>. If validation occurred while invoking 
 * <code>Document.normalizeDocument()</code>, attribute nodes with 
 * <code>specified</code> equals to <code>false</code> are recomputed 
 * according to the default attribute values provided by the schema. If no 
 * default value is associate with this attribute in the schema, the 
 * attribute node is discarded. 
 * <p>In XML, where the value of an attribute can contain entity references, 
 * the child nodes of the <code>Attr</code> node may be either 
 * <code>Text</code> or <code>EntityReference</code> nodes (when these are 
 * in use; see the description of <code>EntityReference</code> for 
 * discussion). 
 * <p>The DOM Core represents all attribute values as simple strings, even if 
 * the DTD or schema associated with the document declares them of some 
 * specific type such as tokenized. 
 * <p>The way attribute value normalization is performed by the DOM 
 * implementation depends on how much the implementation knows about the 
 * schema in use. Typically, the <code>value</code> and 
 * <code>nodeValue</code> attributes of an <code>Attr</code> node initially 
 * returns the normalized value given by the parser. It is also the case 
 * after <code>Document.normalizeDocument()</code> is called (assuming the 
 * right options have been set). But this may not be the case after 
 * mutation, independently of whether the mutation is performed by setting 
 * the string value directly or by changing the <code>Attr</code> child 
 * nodes. In particular, this is true when <a href='http://www.w3.org/TR/2004/REC-xml-20040204#dt-charref'>character 

 * references</a> are involved, given that they are not represented in the DOM and they 
 * impact attribute value normalization. On the other hand, if the 
 * implementation knows about the schema in use when the attribute value is 
 * changed, and it is of a different type than CDATA, it may normalize it 
 * again at that time. This is especially true of specialized DOM 
 * implementations, such as SVG DOM implementations, which store attribute 
 * values in an internal form different from a string.
 * <p>The following table gives some examples of the relations between the 
 * attribute value in the original document (parsed attribute), the value as 
 * exposed in the DOM, and the serialization of the value: 
 * <table border='1' cellpadding='3'>
 * <tr>
 * <th>Examples</th>
 * <th>Parsed 
 * attribute value</th>
 * <th>Initial <code>Attr.value</code></th>
 * <th>Serialized attribute value</th>
 * </tr>
 * <tr>
 * <td valign='top' rowspan='1' colspan='1'>
 * Character reference</td>
 * <td valign='top' rowspan='1' colspan='1'>
 * <pre>"x&#178;=5"</pre>
 * </td>
 * <td valign='top' rowspan='1' colspan='1'>
 * <pre>"x\u00b2=5"</pre>