1. // Attributes.java - attribute list with Namespace support

  2. // Written by David Megginson, sax@megginson.com

  3. // NO WARRANTY!  This class is in the public domain.

  4. 

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

  6. 

  7. 

  8. package org.xml.sax;

  9. 

  10. 

  11. /**

  12.  * Interface for a list of XML attributes.

  13.  *

  14.  * <blockquote>

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

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

  17.  * </blockquote>

  18.  *

  19.  * <p>This interface allows access to a list of attributes in

  20.  * three different ways:</p>

  21.  *

  22.  * <ol>

  23.  * <li>by attribute index;</li>

  24.  * <li>by Namespace-qualified name; or</li>

  25.  * <li>by qualified (prefixed) name.</li>

  26.  * </ol>

  27.  *

  28.  * <p>The list will not contain attributes that were declared

  29.  * #IMPLIED but not specified in the start tag.  It will also not

  30.  * contain attributes used as Namespace declarations (xmlns*) unless

  31.  * the <code>http://xml.org/sax/features/namespace-prefixes</code> 

  32.  * feature is set to <var>true</var> (it is <var>false</var> by 

  33.  * default).</p>

  34.  *

  35.  * <p>If the namespace-prefixes feature (see above) is <var>false</var>, 

  36.  * access by qualified name may not be available; if the 

  37.  * <code>http://xml.org/sax/features/namespaces</code>

  38.  * feature is <var>false</var>, access by Namespace-qualified names 

  39.  * may not be available.</p>

  40.  *

  41.  * <p>This interface replaces the now-deprecated SAX1 {@link

  42.  * org.xml.sax.AttributeList AttributeList} interface, which does not 

  43.  * contain Namespace support.  In addition to Namespace support, it 

  44.  * adds the <var>getIndex</var> methods (below).</p>

  45.  *

  46.  * <p>The order of attributes in the list is unspecified, and will

  47.  * vary from implementation to implementation.</p>

  48.  *

  49.  * @since SAX 2.0

  50.  * @author David Megginson, 

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

  52.  * @version 2.0r2pre

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

  54.  */

  55. public interface Attributes

  56. {

  57. 

  58. 

  59.     ////////////////////////////////////////////////////////////////////

  60.     // Indexed access.

  61.     ////////////////////////////////////////////////////////////////////

  62. 

  63. 

  64.     /**

  65.      * Return the number of attributes in the list.

  66.      *

  67.      * <p>Once you know the number of attributes, you can iterate

  68.      * through the list.</p>

  69.      *

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

  71.      * @see #getURI(int)

  72.      * @see #getLocalName(int)

  73.      * @see #getQName(int)

  74.      * @see #getType(int)

  75.      * @see #getValue(int)

  76.      */

  77.     public abstract int getLength ();

  78. 

  79. 

  80.     /**

  81.      * Look up an attribute's Namespace URI by index.

  82.      *

  83.      * @param index The attribute index (zero-based).

  84.      * @return The Namespace URI, or the empty string if none

  85.      *         is available, or null if the index is out of

  86.      *         range.

  87.      * @see #getLength

  88.      */

  89.     public abstract String getURI (int index);

  90. 

  91. 

  92.     /**

  93.      * Look up an attribute's local name by index.

  94.      *

  95.      * @param index The attribute index (zero-based).

  96.      * @return The local name, or the empty string if Namespace

  97.      *         processing is not being performed, or null

  98.      *         if the index is out of range.

  99.      * @see #getLength

  100.      */

  101.     public abstract String getLocalName (int index);

  102. 

  103. 

  104.     /**

  105.      * Look up an attribute's XML 1.0 qualified name by index.

  106.      *

  107.      * @param index The attribute index (zero-based).

  108.      * @return The XML 1.0 qualified name, or the empty string

  109.      *         if none is available, or null if the index

  110.      *         is out of range.

  111.      * @see #getLength

  112.      */

  113.     public abstract String getQName (int index);

  114. 

  115. 

  116.     /**

  117.      * Look up an attribute's type by index.

  118.      *

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

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

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

  122.      *

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

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

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

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

  127.      *

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

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

  130.      *

  131.      * @param index The attribute index (zero-based).

  132.      * @return The attribute's type as a string, or null if the

  133.      *         index is out of range.

  134.      * @see #getLength

  135.      */

  136.     public abstract String getType (int index);

  137. 

  138. 

  139.     /**

  140.      * Look up an attribute's value by index.

  141.      *

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

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

  144.      * into a single string with each token separated by a

  145.      * single space.</p>

  146.      *

  147.      * @param index The attribute index (zero-based).

  148.      * @return The attribute's value as a string, or null if the

  149.      *         index is out of range.

  150.      * @see #getLength

  151.      */

  152.     public abstract String getValue (int index);

  153. 

  154. 

  155. 

  156.     ////////////////////////////////////////////////////////////////////

  157.     // Name-based query.

  158.     ////////////////////////////////////////////////////////////////////

  159. 

  160. 

  161.     /**

  162.      * Look up the index of an attribute by Namespace name.

  163.      *

  164.      * @param uri The Namespace URI, or the empty string if

  165.      *        the name has no Namespace URI.

  166.      * @param localName The attribute's local name.

  167.      * @return The index of the attribute, or -1 if it does not

  168.      *         appear in the list.

  169.      */

  170.     public int getIndex (String uri, String localName);

  171. 

  172. 

  173.     /**

  174.      * Look up the index of an attribute by XML 1.0 qualified name.

  175.      *

  176.      * @param qName The qualified (prefixed) name.

  177.      * @return The index of the attribute, or -1 if it does not

  178.      *         appear in the list.

  179.      */

  180.     public int getIndex (String qName);

  181. 

  182. 

  183.     /**

  184.      * Look up an attribute's type by Namespace name.

  185.      *

  186.      * <p>See {@link #getType(int) getType(int)} for a description

  187.      * of the possible types.</p>

  188.      *

  189.      * @param uri The Namespace URI, or the empty String if the

  190.      *        name has no Namespace URI.

  191.      * @param localName The local name of the attribute.

  192.      * @return The attribute type as a string, or null if the

  193.      *         attribute is not in the list or if Namespace

  194.      *         processing is not being performed.

  195.      */

  196.     public abstract String getType (String uri, String localName);

  197. 

  198. 

  199.     /**

  200.      * Look up an attribute's type by XML 1.0 qualified name.

  201.      *

  202.      * <p>See {@link #getType(int) getType(int)} for a description

  203.      * of the possible types.</p>

  204.      *

  205.      * @param qName The XML 1.0 qualified name.

  206.      * @return The attribute type as a string, or null if the

  207.      *         attribute is not in the list or if qualified names

  208.      *         are not available.

  209.      */

  210.     public abstract String getType (String qName);

  211. 

  212. 

  213.     /**

  214.      * Look up an attribute's value by Namespace name.

  215.      *

  216.      * <p>See {@link #getValue(int) getValue(int)} for a description

  217.      * of the possible values.</p>

  218.      *

  219.      * @param uri The Namespace URI, or the empty String if the

  220.      *        name has no Namespace URI.

  221.      * @param localName The local name of the attribute.

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

  223.      *         attribute is not in the list.

  224.      */

  225.     public abstract String getValue (String uri, String localName);

  226. 

  227. 

  228.     /**

  229.      * Look up an attribute's value by XML 1.0 qualified name.

  230.      *

  231.      * <p>See {@link #getValue(int) getValue(int)} for a description

  232.      * of the possible values.</p>

  233.      *

  234.      * @param qName The XML 1.0 qualified name.

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

  236.      *         attribute is not in the list or if qualified names

  237.      *         are not available.

  238.      */

  239.     public abstract String getValue (String qName);

  240. 

  241. }

  242. 

  243. // end of Attributes.java