libjava/classpath/external/sax/org/xml/sax/AttributeList.java

   1 // SAX Attribute List Interface.
   2 // http://www.saxproject.org
   3 // No warranty; no copyright -- use this as you will.
   4 // $Id: AttributeList.java,v 1.10 2004/12/11 15:41:09 dog Exp $
   5
   6 package org.xml.sax;
   7
   8 /**
   9  * Interface for an element's attribute specifications.
  10  *
  11  * <blockquote>
  12  * <em>This module, both source code and documentation, is in the
  13  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  14  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  15  * for further information.
  16  * </blockquote>
  17  *
  18  * <p>This is the original SAX1 interface for reporting an element's
  19  * attributes.  Unlike the new {@link org.xml.sax.Attributes Attributes}
  20  * interface, it does not support Namespace-related information.</p>
  21  *
  22  * <p>When an attribute list is supplied as part of a
  23  * {@link org.xml.sax.DocumentHandler#startElement startElement}
  24  * event, the list will return valid results only during the
  25  * scope of the event; once the event handler returns control
  26  * to the parser, the attribute list is invalid.  To save a
  27  * persistent copy of the attribute list, use the SAX1
  28  * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
  29  * helper class.</p>
  30  *
  31  * <p>An attribute list includes only attributes that have been
  32  * specified or defaulted: #IMPLIED attributes will not be included.</p>
  33  *
  34  * <p>There are two ways for the SAX application to obtain information
  35  * from the AttributeList.  First, it can iterate through the entire
  36  * list:</p>
  37  *
  38  * <pre>
  39  * public void startElement (String name, AttributeList atts) {
  40  *   for (int i = 0; i < atts.getLength(); i++) {
  41  *     String name = atts.getName(i);
  42  *     String type = atts.getType(i);
  43  *     String value = atts.getValue(i);
  44  *     [...]
  45  *   }
  46  * }
  47  * </pre>
  48  *
  49  * <p>(Note that the result of getLength() will be zero if there
  50  * are no attributes.)
  51  *
  52  * <p>As an alternative, the application can request the value or
  53  * type of specific attributes:</p>
  54  *
  55  * <pre>
  56  * public void startElement (String name, AttributeList atts) {
  57  *   String identifier = atts.getValue("id");
  58  *   String label = atts.getValue("label");
  59  *   [...]
  60  * }
  61  * </pre>
  62  *
  63  * @deprecated This interface has been replaced by the SAX2
  64  *             {@link org.xml.sax.Attributes Attributes}
  65  *             interface, which includes Namespace support.
  66  * @since SAX 1.0
  67  * @author David Megginson
  68  * @version 2.0.1 (sax2r2)
  69  * @see org.xml.sax.DocumentHandler#startElement startElement
  70  * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl
  71  */
  72 public interface AttributeList {
  73
  74 \f
  75     ////////////////////////////////////////////////////////////////////
  76     // Iteration methods.
  77     ////////////////////////////////////////////////////////////////////
  78
  79
  80     /**
  81      * Return the number of attributes in this list.
  82      *
  83      * <p>The SAX parser may provide attributes in any
  84      * arbitrary order, regardless of the order in which they were
  85      * declared or specified.  The number of attributes may be
  86      * zero.</p>
  87      *
  88      * @return The number of attributes in the list.
  89      */
  90     public abstract int getLength ();
  91
  92
  93     /**
  94      * Return the name of an attribute in this list (by position).
  95      *
  96      * <p>The names must be unique: the SAX parser shall not include the
  97      * same attribute twice.  Attributes without values (those declared
  98      * #IMPLIED without a value specified in the start tag) will be
  99      * omitted from the list.</p>
 100      *
 101      * <p>If the attribute name has a namespace prefix, the prefix
 102      * will still be attached.</p>
 103      *
 104      * @param i The index of the attribute in the list (starting at 0).
 105      * @return The name of the indexed attribute, or null
 106      *         if the index is out of range.
 107      * @see #getLength
 108      */
 109     public abstract String getName (int i);
 110
 111
 112     /**
 113      * Return the type of an attribute in the list (by position).
 114      *
 115      * <p>The attribute type is one of the strings "CDATA", "ID",
 116      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
 117      * or "NOTATION" (always in upper case).</p>
 118      *
 119      * <p>If the parser has not read a declaration for the attribute,
 120      * or if the parser does not report attribute types, then it must
 121      * return the value "CDATA" as stated in the XML 1.0 Recommentation
 122      * (clause 3.3.3, "Attribute-Value Normalization").</p>
 123      *
 124      * <p>For an enumerated attribute that is not a notation, the
 125      * parser will report the type as "NMTOKEN".</p>
 126      *
 127      * @param i The index of the attribute in the list (starting at 0).
 128      * @return The attribute type as a string, or
 129      *         null if the index is out of range.
 130      * @see #getLength
 131      * @see #getType(java.lang.String)
 132      */
 133     public abstract String getType (int i);
 134
 135
 136     /**
 137      * Return the value of an attribute in the list (by position).
 138      *
 139      * <p>If the attribute value is a list of tokens (IDREFS,
 140      * ENTITIES, or NMTOKENS), the tokens will be concatenated
 141      * into a single string separated by whitespace.</p>
 142      *
 143      * @param i The index of the attribute in the list (starting at 0).
 144      * @return The attribute value as a string, or
 145      *         null if the index is out of range.
 146      * @see #getLength
 147      * @see #getValue(java.lang.String)
 148      */
 149     public abstract String getValue (int i);
 150
 151
 152 \f
 153     ////////////////////////////////////////////////////////////////////
 154     // Lookup methods.
 155     ////////////////////////////////////////////////////////////////////
 156
 157
 158     /**
 159      * Return the type of an attribute in the list (by name).
 160      *
 161      * <p>The return value is the same as the return value for
 162      * getType(int).</p>
 163      *
 164      * <p>If the attribute name has a namespace prefix in the document,
 165      * the application must include the prefix here.</p>
 166      *
 167      * @param name The name of the attribute.
 168      * @return The attribute type as a string, or null if no
 169      *         such attribute exists.
 170      * @see #getType(int)
 171      */
 172     public abstract String getType (String name);
 173
 174
 175     /**
 176      * Return the value of an attribute in the list (by name).
 177      *
 178      * <p>The return value is the same as the return value for
 179      * getValue(int).</p>
 180      *
 181      * <p>If the attribute name has a namespace prefix in the document,
 182      * the application must include the prefix here.</p>
 183      *
 184      * @param name the name of the attribute to return
 185      * @return The attribute value as a string, or null if
 186      *         no such attribute exists.
 187      * @see #getValue(int)
 188      */
 189     public abstract String getValue (String name);
 190
 191 }
 192
 193 // end of AttributeList.java