Source for org.xml.sax.Attributes

   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