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 013package 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 */ 054public 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 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}