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.13 2004/03/18 12:28:05 dmegginson 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 //////////////////////////////////////////////////////////////////// 75 // Indexed access. 76 //////////////////////////////////////////////////////////////////// 77 78 79 /** 80 * Return the number of attributes in the list. 81 * 82 * <p>Once you know the number of attributes, you can iterate 83 * through the list.</p> 84 * 85 * @return The number of attributes in the list. 86 * @see #getURI(int) 87 * @see #getLocalName(int) 88 * @see #getQName(int) 89 * @see #getType(int) 90 * @see #getValue(int) 91 */ 92 public abstract int getLength (); 93 94 95 /** 96 * Look up an attribute's Namespace URI by index. 97 * 98 * @param index The attribute index (zero-based). 99 * @return The Namespace URI, or the empty string if none 100 * is available, or null if the index is out of 101 * range. 102 * @see #getLength 103 */ 104 public abstract String getURI (int index); 105 106 107 /** 108 * Look up an attribute's local name by index. 109 * 110 * @param index The attribute index (zero-based). 111 * @return The local name, or the empty string if Namespace 112 * processing is not being performed, or null 113 * if the index is out of range. 114 * @see #getLength 115 */ 116 public abstract String getLocalName (int index); 117 118 119 /** 120 * Look up an attribute's XML qualified (prefixed) name by index. 121 * 122 * @param index The attribute index (zero-based). 123 * @return The XML qualified name, or the empty string 124 * if none is available, or null if the index 125 * is out of range. 126 * @see #getLength 127 */ 128 public abstract String getQName (int index); 129 130 131 /** 132 * Look up an attribute's type by index. 133 * 134 * <p>The attribute type is one of the strings "CDATA", "ID", 135 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", 136 * or "NOTATION" (always in upper case).</p> 137 * 138 * <p>If the parser has not read a declaration for the attribute, 139 * or if the parser does not report attribute types, then it must 140 * return the value "CDATA" as stated in the XML 1.0 Recommendation 141 * (clause 3.3.3, "Attribute-Value Normalization").</p> 142 * 143 * <p>For an enumerated attribute that is not a notation, the 144 * parser will report the type as "NMTOKEN".</p> 145 * 146 * @param index The attribute index (zero-based). 147 * @return The attribute's type as a string, or null if the 148 * index is out of range. 149 * @see #getLength 150 */ 151 public abstract String getType (int index); 152 153 154 /** 155 * Look up an attribute's value by index. 156 * 157 * <p>If the attribute value is a list of tokens (IDREFS, 158 * ENTITIES, or NMTOKENS), the tokens will be concatenated 159 * into a single string with each token separated by a 160 * single space.</p> 161 * 162 * @param index The attribute index (zero-based). 163 * @return The attribute's value as a string, or null if the 164 * index is out of range. 165 * @see #getLength 166 */ 167 public abstract String getValue (int index); 168 169 170 171 //////////////////////////////////////////////////////////////////// 173 // Name-based query. 174 //////////////////////////////////////////////////////////////////// 175 176 177 /** 178 * Look up the index of an attribute by Namespace name. 179 * 180 * @param uri The Namespace URI, or the empty string if 181 * the name has no Namespace URI. 182 * @param localName The attribute's local name. 183 * @return The index of the attribute, or -1 if it does not 184 * appear in the list. 185 */ 186 public int getIndex (String uri, String localName); 187 188 189 /** 190 * Look up the index of an attribute by XML qualified (prefixed) name. 191 * 192 * @param qName The qualified (prefixed) name. 193 * @return The index of the attribute, or -1 if it does not 194 * appear in the list. 195 */ 196 public int getIndex (String qName); 197 198 199 /** 200 * Look up an attribute's type by Namespace name. 201 * 202 * <p>See {@link #getType(int) getType(int)} for a description 203 * of the possible types.</p> 204 * 205 * @param uri The Namespace URI, or the empty String if the 206 * name has no Namespace URI. 207 * @param localName The local name of the attribute. 208 * @return The attribute type as a string, or null if the 209 * attribute is not in the list or if Namespace 210 * processing is not being performed. 211 */ 212 public abstract String getType (String uri, String localName); 213 214 215 /** 216 * Look up an attribute's type by XML qualified (prefixed) name. 217 * 218 * <p>See {@link #getType(int) getType(int)} for a description 219 * of the possible types.</p> 220 * 221 * @param qName The XML qualified name. 222 * @return The attribute type as a string, or null if the 223 * attribute is not in the list or if qualified names 224 * are not available. 225 */ 226 public abstract String getType (String qName); 227 228 229 /** 230 * Look up an attribute's value by Namespace name. 231 * 232 * <p>See {@link #getValue(int) getValue(int)} for a description 233 * of the possible values.</p> 234 * 235 * @param uri The Namespace URI, or the empty String if the 236 * name has no Namespace URI. 237 * @param localName The local name of the attribute. 238 * @return The attribute value as a string, or null if the 239 * attribute is not in the list. 240 */ 241 public abstract String getValue (String uri, String localName); 242 243 244 /** 245 * Look up an attribute's value by XML qualified (prefixed) name. 246 * 247 * <p>See {@link #getValue(int) getValue(int)} for a description 248 * of the possible values.</p> 249 * 250 * @param qName The XML qualified name. 251 * @return The attribute value as a string, or null if the 252 * attribute is not in the list or if qualified names 253 * are not available. 254 */ 255 public abstract String getValue (String qName); 256 257 } 258 259 // end of Attributes.java 260
