Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]

    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 226184 2005-04-08 10:53:24Z neeraj $
    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

Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]