< prev index next >

src/java.xml/share/classes/org/xml/sax/AttributeList.java

Print this page




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


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