org.xml.sax.AttributeList Maven / Gradle / Ivy
// SAX Attribute List Interface.
// No warranty; no copyright -- use this as you will.
// $Id: AttributeList.java 233605 2001-11-06 18:33:40Z hannes $
package org.xml.sax;
/**
* Interface for an element's attribute specifications.
*
* The SAX parser implements this interface and passes an instance
* to the SAX application as the second argument of each startElement
* event.
*
* The instance provided will return valid results only during the
* scope of the startElement invocation (to save it for future
* use, the application must make a copy: the AttributeListImpl
* helper class provides a convenient constructor for doing so).
*
* An AttributeList includes only attributes that have been
* specified or defaulted: #IMPLIED attributes will not be included.
*
* There are two ways for the SAX application to obtain information
* from the AttributeList. First, it can iterate through the entire
* list:
*
*
* public void startElement (String name, AttributeList atts) {
* for (int i = 0; i < atts.getLength(); i++) {
* String name = atts.getName(i);
* String type = atts.getType(i);
* String value = atts.getValue(i);
* [...]
* }
* }
*
*
* (Note that the result of getLength() will be zero if there
* are no attributes.)
*
*
As an alternative, the application can request the value or
* type of specific attributes:
*
*
* public void startElement (String name, AttributeList atts) {
* String identifier = atts.getValue("id");
* String label = atts.getValue("label");
* [...]
* }
*
*
* The AttributeListImpl helper class provides a convenience
* implementation for use by parser or application writers.
*
* @author David Megginson ([email protected])
* @version 1.0
* @see org.xml.sax.DocumentHandler#startElement
* @see org.xml.sax.helpers.AttributeListImpl
*/
public interface AttributeList {
/**
* Return the number of attributes in this list.
*
* The SAX parser may provide attributes in any
* arbitrary order, regardless of the order in which they were
* declared or specified. The number of attributes may be
* zero.
*
* @return The number of attributes in the list.
*/
public abstract int getLength ();
/**
* Return the name of an attribute in this list (by position).
*
* The names must be unique: the SAX parser shall not include the
* same attribute twice. Attributes without values (those declared
* #IMPLIED without a value specified in the start tag) will be
* omitted from the list.
*
* If the attribute name has a namespace prefix, the prefix
* will still be attached.
*
* @param i The index of the attribute in the list (starting at 0).
* @return The name of the indexed attribute, or null
* if the index is out of range.
* @see #getLength
*/
public abstract String getName (int i);
/**
* Return the type of an attribute in the list (by position).
*
* The attribute type is one of the strings "CDATA", "ID",
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
* or "NOTATION" (always in upper case).
*
* If the parser has not read a declaration for the attribute,
* or if the parser does not report attribute types, then it must
* return the value "CDATA" as stated in the XML 1.0 Recommentation
* (clause 3.3.3, "Attribute-Value Normalization").
*
* For an enumerated attribute that is not a notation, the
* parser will report the type as "NMTOKEN".
*
* @param i The index of the attribute in the list (starting at 0).
* @return The attribute type as a string, or
* null if the index is out of range.
* @see #getLength
* @see #getType(java.lang.String)
*/
public abstract String getType (int i);
/**
* Return the value of an attribute in the list (by position).
*
* If the attribute value is a list of tokens (IDREFS,
* ENTITIES, or NMTOKENS), the tokens will be concatenated
* into a single string separated by whitespace.
*
* @param i The index of the attribute in the list (starting at 0).
* @return The attribute value as a string, or
* null if the index is out of range.
* @see #getLength
* @see #getValue(java.lang.String)
*/
public abstract String getValue (int i);
/**
* Return the type of an attribute in the list (by name).
*
* The return value is the same as the return value for
* getType(int).
*
* If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.
*
* @param name The name of the attribute.
* @return The attribute type as a string, or null if no
* such attribute exists.
* @see #getType(int)
*/
public abstract String getType (String name);
/**
* Return the value of an attribute in the list (by name).
*
* The return value is the same as the return value for
* getValue(int).
*
* If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.
*
* @param i The index of the attribute in the list.
* @return The attribute value as a string, or null if
* no such attribute exists.
* @see #getValue(int)
*/
public abstract String getValue (String name);
}