001: /*
002: * Copyright (c) 2000 World Wide Web Consortium,
003: * (Massachusetts Institute of Technology, Institut National de
004: * Recherche en Informatique et en Automatique, Keio University). All
005: * Rights Reserved. This program is distributed under the W3C's Software
006: * Intellectual Property License. This program is distributed in the
007: * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009: * PURPOSE.
010: * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
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 document type definition.
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>nodeValue</code> attribute
043: * on the <code>Attr</code> instance can also be used to retrieve the string
044: * version of the attribute's value(s).
045: * <p>In XML, where the value of an attribute can contain entity references,
046: * the child nodes of the <code>Attr</code> node may be either
047: * <code>Text</code> or <code>EntityReference</code> nodes (when these are
048: * in use; see the description of <code>EntityReference</code> for
049: * discussion). Because the DOM Core is not aware of attribute types, it
050: * treats all attribute values as simple strings, even if the DTD or schema
051: * declares them as having tokenized types.
052: * <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>.
053: */
054: public interface Attr extends Node {
055: /**
056: * Returns the name of this attribute.
057: */
058: public String getName();
059:
060: /**
061: * If this attribute was explicitly given a value in the original
062: * document, this is <code>true</code>; otherwise, it is
063: * <code>false</code>. Note that the implementation is in charge of this
064: * attribute, not the user. If the user changes the value of the
065: * attribute (even if it ends up having the same value as the default
066: * value) then the <code>specified</code> flag is automatically flipped
067: * to <code>true</code>. To re-specify the attribute as the default
068: * value from the DTD, the user must delete the attribute. The
069: * implementation will then make a new attribute available with
070: * <code>specified</code> set to <code>false</code> and the default
071: * value (if one exists).
072: * <br>In summary: If the attribute has an assigned value in the document
073: * then <code>specified</code> is <code>true</code>, and the value is
074: * the assigned value.If the attribute has no assigned value in the
075: * document and has a default value in the DTD, then
076: * <code>specified</code> is <code>false</code>, and the value is the
077: * default value in the DTD.If the attribute has no assigned value in
078: * the document and has a value of #IMPLIED in the DTD, then the
079: * attribute does not appear in the structure model of the document.If
080: * the <code>ownerElement</code> attribute is <code>null</code> (i.e.
081: * because it was just created or was set to <code>null</code> by the
082: * various removal and cloning operations) <code>specified</code> is
083: * <code>true</code>.
084: */
085: public boolean getSpecified();
086:
087: /**
088: * On retrieval, the value of the attribute is returned as a string.
089: * Character and general entity references are replaced with their
090: * values. See also the method <code>getAttribute</code> on the
091: * <code>Element</code> interface.
092: * <br>On setting, this creates a <code>Text</code> node with the unparsed
093: * contents of the string. I.e. any characters that an XML processor
094: * would recognize as markup are instead treated as literal text. See
095: * also the method <code>setAttribute</code> on the <code>Element</code>
096: * interface.
097: * @exception DOMException
098: * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
099: */
100: public String getValue();
101:
102: /**
103: * On retrieval, the value of the attribute is returned as a string.
104: * Character and general entity references are replaced with their
105: * values. See also the method <code>getAttribute</code> on the
106: * <code>Element</code> interface.
107: * <br>On setting, this creates a <code>Text</code> node with the unparsed
108: * contents of the string. I.e. any characters that an XML processor
109: * would recognize as markup are instead treated as literal text. See
110: * also the method <code>setAttribute</code> on the <code>Element</code>
111: * interface.
112: * @exception DOMException
113: * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
114: */
115: public void setValue(String value) throws DOMException;
116:
117: /**
118: * The <code>Element</code> node this attribute is attached to or
119: * <code>null</code> if this attribute is not in use.
120: * @since DOM Level 2
121: */
122: public Element getOwnerElement();
123:
124: }
|