libjava/org/w3c/dom/Attr.java

   1 /*
   2  * Copyright (c) 2000 World Wide Web Consortium,
   3  * (Massachusetts Institute of Technology, Institut National de
   4  * Recherche en Informatique et en Automatique, Keio University). All
   5  * Rights Reserved. This program is distributed under the W3C's Software
   6  * Intellectual Property License. This program is distributed in the
   7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
   8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
   9  * PURPOSE.
  10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
  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 document type definition.
  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>nodeValue</code> attribute
  43  * on the <code>Attr</code> instance can also be used to retrieve the string
  44  * version of the attribute's value(s).
  45  * <p>In XML, where the value of an attribute can contain entity references,
  46  * the child nodes of the <code>Attr</code> node may be either
  47  * <code>Text</code> or <code>EntityReference</code> nodes (when these are
  48  * in use; see the description of <code>EntityReference</code> for
  49  * discussion). Because the DOM Core is not aware of attribute types, it
  50  * treats all attribute values as simple strings, even if the DTD or schema
  51  * declares them as having tokenized types.
  52  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
  53  */
  54 public interface Attr extends Node {
  55     /**
  56      * Returns the name of this attribute.
  57      */
  58     public String getName();
  59
  60     /**
  61      * If this attribute was explicitly given a value in the original
  62      * document, this is <code>true</code>; otherwise, it is
  63      * <code>false</code>. Note that the implementation is in charge of this
  64      * attribute, not the user. If the user changes the value of the
  65      * attribute (even if it ends up having the same value as the default
  66      * value) then the <code>specified</code> flag is automatically flipped
  67      * to <code>true</code>. To re-specify the attribute as the default
  68      * value from the DTD, the user must delete the attribute. The
  69      * implementation will then make a new attribute available with
  70      * <code>specified</code> set to <code>false</code> and the default
  71      * value (if one exists).
  72      * <br>In summary:  If the attribute has an assigned value in the document
  73      * then <code>specified</code> is <code>true</code>, and the value is
  74      * the assigned value.  If the attribute has no assigned value in the
  75      * document and has a default value in the DTD, then
  76      * <code>specified</code> is <code>false</code>, and the value is the
  77      * default value in the DTD. If the attribute has no assigned value in
  78      * the document and has a value of #IMPLIED in the DTD, then the
  79      * attribute does not appear in the structure model of the document. If
  80      * the <code>ownerElement</code> attribute is <code>null</code> (i.e.
  81      * because it was just created or was set to <code>null</code> by the
  82      * various removal and cloning operations) <code>specified</code> is
  83      * <code>true</code>.
  84      */
  85     public boolean getSpecified();
  86
  87     /**
  88      * On retrieval, the value of the attribute is returned as a string.
  89      * Character and general entity references are replaced with their
  90      * values. See also the method <code>getAttribute</code> on the
  91      * <code>Element</code> interface.
  92      * <br>On setting, this creates a <code>Text</code> node with the unparsed
  93      * contents of the string. I.e. any characters that an XML processor
  94      * would recognize as markup are instead treated as literal text. See
  95      * also the method <code>setAttribute</code> on the <code>Element</code>
  96      * interface.
  97      * @exception DOMException
  98      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
  99      */
 100     public String getValue();
 101     public void setValue(String value)
 102                             throws DOMException;
 103
 104     /**
 105      * The <code>Element</code> node this attribute is attached to or
 106      * <code>null</code> if this attribute is not in use.
 107      * @since DOM Level 2
 108      */
 109     public Element getOwnerElement();
 110
 111 }