Source for org.xml.sax.AttributeList

   1: // SAX Attribute List Interface.
   2: // http://www.saxproject.org
   3: // No warranty; no copyright -- use this as you will.
   4: // $Id: AttributeList.java,v 1.1 2004/12/23 22:38:42 mark Exp $
   5: 
   6: package org.xml.sax;
   7: 
   8: /**
   9:  * Interface for an element's attribute specifications.
  10:  *
  11:  * <blockquote>
  12:  * <em>This module, both source code and documentation, is in the
  13:  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  14:  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  15:  * for further information.
  16:  * </blockquote>
  17:  *
  18:  * <p>This is the original SAX1 interface for reporting an element's
  19:  * attributes.  Unlike the new {@link org.xml.sax.Attributes Attributes}
  20:  * interface, it does not support Namespace-related information.</p>
  21:  *
  22:  * <p>When an attribute list is supplied as part of a
  23:  * {@link org.xml.sax.DocumentHandler#startElement startElement}
  24:  * event, the list will return valid results only during the
  25:  * scope of the event; once the event handler returns control
  26:  * to the parser, the attribute list is invalid.  To save a
  27:  * persistent copy of the attribute list, use the SAX1
  28:  * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
  29:  * helper class.</p>
  30:  *
  31:  * <p>An attribute list includes only attributes that have been
  32:  * specified or defaulted: #IMPLIED attributes will not be included.</p>
  33:  *
  34:  * <p>There are two ways for the SAX application to obtain information
  35:  * from the AttributeList.  First, it can iterate through the entire
  36:  * list:</p>
  37:  *
  38:  * <pre>
  39:  * public void startElement (String name, AttributeList atts) {
  40:  *   for (int i = 0; i < atts.getLength(); i++) {
  41:  *     String name = atts.getName(i);
  42:  *     String type = atts.getType(i);
  43:  *     String value = atts.getValue(i);
  44:  *     [...]
  45:  *   }
  46:  * }
  47:  * </pre>
  48:  *
  49:  * <p>(Note that the result of getLength() will be zero if there
  50:  * are no attributes.)
  51:  *
  52:  * <p>As an alternative, the application can request the value or
  53:  * type of specific attributes:</p>
  54:  *
  55:  * <pre>
  56:  * public void startElement (String name, AttributeList atts) {
  57:  *   String identifier = atts.getValue("id");
  58:  *   String label = atts.getValue("label");
  59:  *   [...]
  60:  * }
  61:  * </pre>
  62:  *
  63:  * @deprecated This interface has been replaced by the SAX2
  64:  *             {@link org.xml.sax.Attributes Attributes}
  65:  *             interface, which includes Namespace support.
  66:  * @since SAX 1.0
  67:  * @author David Megginson
  68:  * @version 2.0.1 (sax2r2)
  69:  * @see org.xml.sax.DocumentHandler#startElement startElement
  70:  * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl
  71:  */
  72: public interface AttributeList {
  73: 
  74: 
  75:     ////////////////////////////////////////////////////////////////////
  76:     // Iteration methods.
  77:     ////////////////////////////////////////////////////////////////////
  78:     
  79: 
  80:     /**
  81:      * Return the number of attributes in this list.
  82:      *
  83:      * <p>The SAX parser may provide attributes in any
  84:      * arbitrary order, regardless of the order in which they were
  85:      * declared or specified.  The number of attributes may be
  86:      * zero.</p>
  87:      *
  88:      * @return The number of attributes in the list.  
  89:      */
  90:     public abstract int getLength ();
  91:     
  92:     
  93:     /**
  94:      * Return the name of an attribute in this list (by position).
  95:      *
  96:      * <p>The names must be unique: the SAX parser shall not include the
  97:      * same attribute twice.  Attributes without values (those declared
  98:      * #IMPLIED without a value specified in the start tag) will be
  99:      * omitted from the list.</p>
 100:      *
 101:      * <p>If the attribute name has a namespace prefix, the prefix
 102:      * will still be attached.</p>
 103:      *
 104:      * @param i The index of the attribute in the list (starting at 0).
 105:      * @return The name of the indexed attribute, or null
 106:      *         if the index is out of range.
 107:      * @see #getLength 
 108:      */
 109:     public abstract String getName (int i);
 110:     
 111:     
 112:     /**
 113:      * Return the type of an attribute in the list (by position).
 114:      *
 115:      * <p>The attribute type is one of the strings "CDATA", "ID",
 116:      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
 117:      * or "NOTATION" (always in upper case).</p>
 118:      *
 119:      * <p>If the parser has not read a declaration for the attribute,
 120:      * or if the parser does not report attribute types, then it must
 121:      * return the value "CDATA" as stated in the XML 1.0 Recommentation
 122:      * (clause 3.3.3, "Attribute-Value Normalization").</p>
 123:      *
 124:      * <p>For an enumerated attribute that is not a notation, the
 125:      * parser will report the type as "NMTOKEN".</p>
 126:      *
 127:      * @param i The index of the attribute in the list (starting at 0).
 128:      * @return The attribute type as a string, or
 129:      *         null if the index is out of range.
 130:      * @see #getLength 
 131:      * @see #getType(java.lang.String)
 132:      */
 133:     public abstract String getType (int i);
 134:     
 135:     
 136:     /**
 137:      * Return the value of an attribute in the list (by position).
 138:      *
 139:      * <p>If the attribute value is a list of tokens (IDREFS,
 140:      * ENTITIES, or NMTOKENS), the tokens will be concatenated
 141:      * into a single string separated by whitespace.</p>
 142:      *
 143:      * @param i The index of the attribute in the list (starting at 0).
 144:      * @return The attribute value as a string, or
 145:      *         null if the index is out of range.
 146:      * @see #getLength
 147:      * @see #getValue(java.lang.String)
 148:      */
 149:     public abstract String getValue (int i);
 150: 
 151: 
 152: 
 153:     ////////////////////////////////////////////////////////////////////
 154:     // Lookup methods.
 155:     ////////////////////////////////////////////////////////////////////
 156:     
 157:     
 158:     /**
 159:      * Return the type of an attribute in the list (by name).
 160:      *
 161:      * <p>The return value is the same as the return value for
 162:      * getType(int).</p>
 163:      *
 164:      * <p>If the attribute name has a namespace prefix in the document,
 165:      * the application must include the prefix here.</p>
 166:      *
 167:      * @param name The name of the attribute.
 168:      * @return The attribute type as a string, or null if no
 169:      *         such attribute exists.
 170:      * @see #getType(int)
 171:      */
 172:     public abstract String getType (String name);
 173:     
 174:     
 175:     /**
 176:      * Return the value of an attribute in the list (by name).
 177:      *
 178:      * <p>The return value is the same as the return value for
 179:      * getValue(int).</p>
 180:      *
 181:      * <p>If the attribute name has a namespace prefix in the document,
 182:      * the application must include the prefix here.</p>
 183:      *
 184:      * @param name the name of the attribute to return
 185:      * @return The attribute value as a string, or null if
 186:      *         no such attribute exists.
 187:      * @see #getValue(int)
 188:      */
 189:     public abstract String getValue (String name);
 190:     
 191: }
 192: 
 193: // end of AttributeList.java