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

   1 // Attributes.java - attribute list with Namespace support
   2 // http://www.saxproject.org
   3 // Written by David Megginson
   4 // NO WARRANTY!  This class is in the public domain.
   5 // $Id: Attributes.java,v 1.1 2004/12/23 22:38:42 mark Exp $
   6
   7 package org.xml.sax;
   8
   9
  10 /**
  11  * Interface for a list of XML attributes.
  12  *
  13  * <blockquote>
  14  * <em>This module, both source code and documentation, is in the
  15  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  16  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  17  * for further information.
  18  * </blockquote>
  19  *
  20  * <p>This interface allows access to a list of attributes in
  21  * three different ways:</p>
  22  *
  23  * <ol>
  24  * <li>by attribute index;</li>
  25  * <li>by Namespace-qualified name; or</li>
  26  * <li>by qualified (prefixed) name.</li>
  27  * </ol>
  28  *
  29  * <p>The list will not contain attributes that were declared
  30  * #IMPLIED but not specified in the start tag.  It will also not
  31  * contain attributes used as Namespace declarations (xmlns*) unless
  32  * the <code>http://xml.org/sax/features/namespace-prefixes</code>
  33  * feature is set to <var>true</var> (it is <var>false</var> by
  34  * default).
  35  * Because SAX2 conforms to the original "Namespaces in XML"
  36  * recommendation, it normally does not
  37  * give namespace declaration attributes a namespace URI.
  38  * </p>
  39  *
  40  * <p>Some SAX2 parsers may support using an optional feature flag
  41  * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request
  42  * that those attributes be given URIs, conforming to a later
  43  * backwards-incompatible revision of that recommendation.  (The
  44  * attribute's "local name" will be the prefix, or "xmlns" when
  45  * defining a default element namespace.)  For portability, handler
  46  * code should always resolve that conflict, rather than requiring
  47  * parsers that can change the setting of that feature flag.  </p>
  48  *
  49  * <p>If the namespace-prefixes feature (see above) is
  50  * <var>false</var>, access by qualified name may not be available; if
  51  * the <code>http://xml.org/sax/features/namespaces</code> feature is
  52  * <var>false</var>, access by Namespace-qualified names may not be
  53  * available.</p>
  54  *
  55  * <p>This interface replaces the now-deprecated SAX1 {@link
  56  * org.xml.sax.AttributeList AttributeList} interface, which does not
  57  * contain Namespace support.  In addition to Namespace support, it
  58  * adds the <var>getIndex</var> methods (below).</p>
  59  *
  60  * <p>The order of attributes in the list is unspecified, and will
  61  * vary from implementation to implementation.</p>
  62  *
  63  * @since SAX 2.0
  64  * @author David Megginson
  65  * @version 2.0.1 (sax2r2)
  66  * @see org.xml.sax.helpers.AttributesImpl
  67  * @see org.xml.sax.ext.DeclHandler#attributeDecl
  68  */
  69 public interface Attributes
  70 {
  71
  72
  73     ////////////////////////////////////////////////////////////////////
  74     // Indexed access.
  75     ////////////////////////////////////////////////////////////////////
  76
  77
  78     /**
  79      * Return the number of attributes in the list.
  80      *
  81      * <p>Once you know the number of attributes, you can iterate
  82      * through the list.</p>
  83      *
  84      * @return The number of attributes in the list.
  85      * @see #getURI(int)
  86      * @see #getLocalName(int)
  87      * @see #getQName(int)
  88      * @see #getType(int)
  89      * @see #getValue(int)
  90      */
  91     public abstract int getLength ();
  92
  93
  94     /**
  95      * Look up an attribute's Namespace URI by index.
  96      *
  97      * @param index The attribute index (zero-based).
  98      * @return The Namespace URI, or the empty string if none
  99      *         is available, or null if the index is out of
 100      *         range.
 101      * @see #getLength
 102      */
 103     public abstract String getURI (int index);
 104
 105
 106     /**
 107      * Look up an attribute's local name by index.
 108      *
 109      * @param index The attribute index (zero-based).
 110      * @return The local name, or the empty string if Namespace
 111      *         processing is not being performed, or null
 112      *         if the index is out of range.
 113      * @see #getLength
 114      */
 115     public abstract String getLocalName (int index);
 116
 117
 118     /**
 119      * Look up an attribute's XML qualified (prefixed) name by index.
 120      *
 121      * @param index The attribute index (zero-based).
 122      * @return The XML qualified name, or the empty string
 123      *         if none is available, or null if the index
 124      *         is out of range.
 125      * @see #getLength
 126      */
 127     public abstract String getQName (int index);
 128
 129
 130     /**
 131      * Look up an attribute's type by index.
 132      *
 133      * <p>The attribute type is one of the strings "CDATA", "ID",
 134      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
 135      * or "NOTATION" (always in upper case).</p>
 136      *
 137      * <p>If the parser has not read a declaration for the attribute,
 138      * or if the parser does not report attribute types, then it must
 139      * return the value "CDATA" as stated in the XML 1.0 Recommendation
 140      * (clause 3.3.3, "Attribute-Value Normalization").</p>
 141      *
 142      * <p>For an enumerated attribute that is not a notation, the
 143      * parser will report the type as "NMTOKEN".</p>
 144      *
 145      * @param index The attribute index (zero-based).
 146      * @return The attribute's type as a string, or null if the
 147      *         index is out of range.
 148      * @see #getLength
 149      */
 150     public abstract String getType (int index);
 151
 152
 153     /**
 154      * Look up an attribute's value by index.
 155      *
 156      * <p>If the attribute value is a list of tokens (IDREFS,
 157      * ENTITIES, or NMTOKENS), the tokens will be concatenated
 158      * into a single string with each token separated by a
 159      * single space.</p>
 160      *
 161      * @param index The attribute index (zero-based).
 162      * @return The attribute's value as a string, or null if the
 163      *         index is out of range.
 164      * @see #getLength
 165      */
 166     public abstract String getValue (int index);
 167
 168
 169
 170     ////////////////////////////////////////////////////////////////////
 171     // Name-based query.
 172     ////////////////////////////////////////////////////////////////////
 173
 174
 175     /**
 176      * Look up the index of an attribute by Namespace name.
 177      *
 178      * @param uri The Namespace URI, or the empty string if
 179      *        the name has no Namespace URI.
 180      * @param localName The attribute's local name.
 181      * @return The index of the attribute, or -1 if it does not
 182      *         appear in the list.
 183      */
 184     public int getIndex (String uri, String localName);
 185
 186
 187     /**
 188      * Look up the index of an attribute by XML qualified (prefixed) name.
 189      *
 190      * @param qName The qualified (prefixed) name.
 191      * @return The index of the attribute, or -1 if it does not
 192      *         appear in the list.
 193      */
 194     public int getIndex (String qName);
 195
 196
 197     /**
 198      * Look up an attribute's type by Namespace name.
 199      *
 200      * <p>See {@link #getType(int) getType(int)} for a description
 201      * of the possible types.</p>
 202      *
 203      * @param uri The Namespace URI, or the empty String if the
 204      *        name has no Namespace URI.
 205      * @param localName The local name of the attribute.
 206      * @return The attribute type as a string, or null if the
 207      *         attribute is not in the list or if Namespace
 208      *         processing is not being performed.
 209      */
 210     public abstract String getType (String uri, String localName);
 211
 212
 213     /**
 214      * Look up an attribute's type by XML qualified (prefixed) name.
 215      *
 216      * <p>See {@link #getType(int) getType(int)} for a description
 217      * of the possible types.</p>
 218      *
 219      * @param qName The XML qualified name.
 220      * @return The attribute type as a string, or null if the
 221      *         attribute is not in the list or if qualified names
 222      *         are not available.
 223      */
 224     public abstract String getType (String qName);
 225
 226
 227     /**
 228      * Look up an attribute's value by Namespace name.
 229      *
 230      * <p>See {@link #getValue(int) getValue(int)} for a description
 231      * of the possible values.</p>
 232      *
 233      * @param uri The Namespace URI, or the empty String if the
 234      *        name has no Namespace URI.
 235      * @param localName The local name of the attribute.
 236      * @return The attribute value as a string, or null if the
 237      *         attribute is not in the list.
 238      */
 239     public abstract String getValue (String uri, String localName);
 240
 241
 242     /**
 243      * Look up an attribute's value by XML qualified (prefixed) name.
 244      *
 245      * <p>See {@link #getValue(int) getValue(int)} for a description
 246      * of the possible values.</p>
 247      *
 248      * @param qName The XML qualified name.
 249      * @return The attribute value as a string, or null if the
 250      *         attribute is not in the list or if qualified names
 251      *         are not available.
 252      */
 253     public abstract String getValue (String qName);
 254
 255 }
 256
 257 // end of Attributes.java