org.w3c.dom.Attr Maven / Gradle / Ivy
/*
* Copyright (c) 2003 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;
/**
* DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.
*
* The Attr interface represents an attribute in an
* Element object. Typically the allowable values for the
* attribute are defined in a document type definition.
* Attr objects inherit the Node 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
* Node attributes parentNode,
* previousSibling, and nextSibling have a
* null value for Attr 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,
* Attr nodes may not be immediate children of a
* DocumentFragment. However, they can be associated with
* Element nodes contained within a
* DocumentFragment. In short, users and implementors of the
* DOM need to be aware that Attr nodes have some things in
* common with other objects inheriting the Node interface, but
* they also are quite distinct.
*
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 nodeValue attribute
* on the Attr instance can also be used to retrieve the string
* version of the attribute's value(s).
*
In XML, where the value of an attribute can contain entity references,
* the child nodes of the Attr node may be either
* Text or EntityReference nodes (when these are
* in use; see the description of EntityReference for
* discussion). Because the DOM Core is not aware of attribute types, it
* treats all attribute values as simple strings, even if the DTD or schema
* declares them as having tokenized types.
*
The DOM implementation does not perform any kind of normalization.
* While it is expected that the value and
* nodeValue attributes of an Attr node would
* initially return a normalized value depending on the schema in used, this
* may not be the case after mutation. This is true, independently of
* whether the mutation is performed by setting the string value directly or
* by changing the Attr child nodes. In particular, this is
* true when character entity references are involved, given that they are
* not represented in the DOM and they impact attribute value normalization.
*
Note: The property [references] defined in [XML Information set]
* is not accessible from DOM Level 3 Core.
*
See also the Document Object Model (DOM) Level 3 Core Specification.
*/
public interface Attr extends Node {
/**
* Returns the name of this attribute.
*/
public String getName();
/**
* True if this attribute was explicitly given a value in the
* instance document, false otherwise. If the user changes
* the value of this attribute node (even if it ends up having the same
* value as the default value) then this is set to true.
* Removing attributes for which a default value is defined in the DTD
* generates a new attribute with the default value and this set to
* false. The implementation may handle attributes with
* default values from other schemas similarly but applications should
* use normalizeDocument() to guarantee this information is
* up-to-date.
*
This attribute is based on the property [specified] defined [XML Information set]
* .
*/
public boolean getSpecified();
/**
* On retrieval, the value of the attribute is returned as a string.
* Character and general entity references are replaced with their
* values. See also the method getAttribute on the
* Element interface.
*
On setting, this creates a Text node with the unparsed
* contents of the string. I.e. any characters that an XML processor
* would recognize as markup are instead treated as literal text. See
* also the method setAttribute on the Element
* interface.
*
Note: Some specialized implementations, such as some [SVG 1.0]
* implementations, may do normalization automatically, even after
* mutation; in such case, the value on retrieval may differ from the
* value on setting.
*
The value may contain the normalized attribute value
* and represents in that case the property [normalized value] defined
* in [XML Information set]
* .
*/
public String getValue();
/**
* On retrieval, the value of the attribute is returned as a string.
* Character and general entity references are replaced with their
* values. See also the method getAttribute on the
* Element interface.
*
On setting, this creates a Text node with the unparsed
* contents of the string. I.e. any characters that an XML processor
* would recognize as markup are instead treated as literal text. See
* also the method setAttribute on the Element
* interface.
*
Note: Some specialized implementations, such as some [SVG 1.0]
* implementations, may do normalization automatically, even after
* mutation; in such case, the value on retrieval may differ from the
* value on setting.
*
The value may contain the normalized attribute value
* and represents in that case the property [normalized value] defined
* in [XML Information set]
* .
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
*/
public void setValue(String value)
throws DOMException;
/**
* The Element node this attribute is attached to or
* null if this attribute is not in use.
*
This attribute represents the property [owner element] defined in [XML Information set]
* .
* @since DOM Level 2
*/
public Element getOwnerElement();
/**
* The type information associated with this attribute.
* @since DOM Level 3
*/
public TypeInfo getSchemaTypeInfo();
/**
* Returns whether this attribute is known to be of type ID or not. When
* it is and its value is unique, the ownerElement of this
* attribute can be retrieved using Document.getElementById.
* This translates to getIsId() in Java. Is that ok? changed to be a
* method. How does this relate to schemaTypeInfo? no
* relation.
* @return true if this attribute is of type ID,
* false otherwise.
* @since DOM Level 3
*/
public boolean isId();
}