1. // SAX Attribute List Interface.

  2. // No warranty; no copyright -- use this as you will.

  3. // $Id: AttributeList.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $

  4. 

  5. package org.xml.sax;

  6. 

  7. /**

  8.  * Interface for an element's attribute specifications.

  9.  *

  10.  * <blockquote>

  11.  * <em>This module, both source code and documentation, is in the

  12.  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

  13.  * </blockquote>

  14.  *

  15.  * <p>This is the original SAX1 interface for reporting an element's

  16.  * attributes.  Unlike the new {@link org.xml.sax.Attributes Attributes}

  17.  * interface, it does not support Namespace-related information.</p>

  18.  *

  19.  * <p>When an attribute list is supplied as part of a

  20.  * {@link org.xml.sax.DocumentHandler#startElement startElement}

  21.  * event, the list will return valid results only during the

  22.  * scope of the event; once the event handler returns control

  23.  * to the parser, the attribute list is invalid.  To save a

  24.  * persistent copy of the attribute list, use the SAX1

  25.  * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}

  26.  * helper class.</p>

  27.  *

  28.  * <p>An attribute list includes only attributes that have been

  29.  * specified or defaulted: #IMPLIED attributes will not be included.</p>

  30.  *

  31.  * <p>There are two ways for the SAX application to obtain information

  32.  * from the AttributeList.  First, it can iterate through the entire

  33.  * list:</p>

  34.  *

  35.  * <pre>

  36.  * public void startElement (String name, AttributeList atts) {

  37.  *   for (int i = 0; i < atts.getLength(); i++) {

  38.  *     String name = atts.getName(i);

  39.  *     String type = atts.getType(i);

  40.  *     String value = atts.getValue(i);

  41.  *     [...]

  42.  *   }

  43.  * }

  44.  * </pre>

  45.  *

  46.  * <p>(Note that the result of getLength() will be zero if there

  47.  * are no attributes.)

  48.  *

  49.  * <p>As an alternative, the application can request the value or

  50.  * type of specific attributes:</p>

  51.  *

  52.  * <pre>

  53.  * public void startElement (String name, AttributeList atts) {

  54.  *   String identifier = atts.getValue("id");

  55.  *   String label = atts.getValue("label");

  56.  *   [...]

  57.  * }

  58.  * </pre>

  59.  *

  60.  * @deprecated This interface has been replaced by the SAX2

  61.  *             {@link org.xml.sax.Attributes Attributes}

  62.  *             interface, which includes Namespace support.

  63.  * @since SAX 1.0

  64.  * @author David Megginson, 

  65.  *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>

  66.  * @version 2.0r2pre

  67.  * @see org.xml.sax.DocumentHandler#startElement startElement

  68.  * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl

  69.  */

  70. public interface AttributeList {

  71. 

  72. 

  73.     ////////////////////////////////////////////////////////////////////

  74.     // Iteration methods.

  75.     ////////////////////////////////////////////////////////////////////

  76.     

  77. 

  78.     /**

  79.      * Return the number of attributes in this list.

  80.      *

  81.      * <p>The SAX parser may provide attributes in any

  82.      * arbitrary order, regardless of the order in which they were

  83.      * declared or specified.  The number of attributes may be

  84.      * zero.</p>

  85.      *

  86.      * @return The number of attributes in the list.  

  87.      */

  88.     public abstract int getLength ();

  89.     

  90.     

  91.     /**

  92.      * Return the name of an attribute in this list (by position).

  93.      *

  94.      * <p>The names must be unique: the SAX parser shall not include the

  95.      * same attribute twice.  Attributes without values (those declared

  96.      * #IMPLIED without a value specified in the start tag) will be

  97.      * omitted from the list.</p>

  98.      *

  99.      * <p>If the attribute name has a namespace prefix, the prefix

  100.      * will still be attached.</p>

  101.      *

  102.      * @param i The index of the attribute in the list (starting at 0).

  103.      * @return The name of the indexed attribute, or null

  104.      *         if the index is out of range.

  105.      * @see #getLength 

  106.      */

  107.     public abstract String getName (int i);

  108.     

  109.     

  110.     /**

  111.      * Return the type of an attribute in the list (by position).

  112.      *

  113.      * <p>The attribute type is one of the strings "CDATA", "ID",

  114.      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",

  115.      * or "NOTATION" (always in upper case).</p>

  116.      *

  117.      * <p>If the parser has not read a declaration for the attribute,

  118.      * or if the parser does not report attribute types, then it must

  119.      * return the value "CDATA" as stated in the XML 1.0 Recommentation

  120.      * (clause 3.3.3, "Attribute-Value Normalization").</p>

  121.      *

  122.      * <p>For an enumerated attribute that is not a notation, the

  123.      * parser will report the type as "NMTOKEN".</p>

  124.      *

  125.      * @param i The index of the attribute in the list (starting at 0).

  126.      * @return The attribute type as a string, or

  127.      *         null if the index is out of range.

  128.      * @see #getLength 

  129.      * @see #getType(java.lang.String)

  130.      */

  131.     public abstract String getType (int i);

  132.     

  133.     

  134.     /**

  135.      * Return the value of an attribute in the list (by position).

  136.      *

  137.      * <p>If the attribute value is a list of tokens (IDREFS,

  138.      * ENTITIES, or NMTOKENS), the tokens will be concatenated

  139.      * into a single string separated by whitespace.</p>

  140.      *

  141.      * @param i The index of the attribute in the list (starting at 0).

  142.      * @return The attribute value as a string, or

  143.      *         null if the index is out of range.

  144.      * @see #getLength

  145.      * @see #getValue(java.lang.String)

  146.      */

  147.     public abstract String getValue (int i);

  148. 

  149. 

  150. 

  151.     ////////////////////////////////////////////////////////////////////

  152.     // Lookup methods.

  153.     ////////////////////////////////////////////////////////////////////

  154.     

  155.     

  156.     /**

  157.      * Return the type of an attribute in the list (by name).

  158.      *

  159.      * <p>The return value is the same as the return value for

  160.      * getType(int).</p>

  161.      *

  162.      * <p>If the attribute name has a namespace prefix in the document,

  163.      * the application must include the prefix here.</p>

  164.      *

  165.      * @param name The name of the attribute.

  166.      * @return The attribute type as a string, or null if no

  167.      *         such attribute exists.

  168.      * @see #getType(int)

  169.      */

  170.     public abstract String getType (String name);

  171.     

  172.     

  173.     /**

  174.      * Return the value of an attribute in the list (by name).

  175.      *

  176.      * <p>The return value is the same as the return value for

  177.      * getValue(int).</p>

  178.      *

  179.      * <p>If the attribute name has a namespace prefix in the document,

  180.      * the application must include the prefix here.</p>

  181.      *

  182.      * @param i The index of the attribute in the list.

  183.      * @return The attribute value as a string, or null if

  184.      *         no such attribute exists.

  185.      * @see #getValue(int)

  186.      */

  187.     public abstract String getValue (String name);

  188.     

  189. }

  190. 

  191. // end of AttributeList.java