001// Attributes.java - attribute list with Namespace support 002// Written by David Megginson, sax@megginson.com 003// NO WARRANTY! This class is in the public domain. 004 005// $Id: Attributes.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $ 006 007 008package org.xml.sax; 009 010 011/** 012 * Interface for a list of XML attributes. 013 * 014 * <blockquote> 015 * <em>This module, both source code and documentation, is in the 016 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 017 * </blockquote> 018 * 019 * <p>This interface allows access to a list of attributes in 020 * three different ways:</p> 021 * 022 * <ol> 023 * <li>by attribute index;</li> 024 * <li>by Namespace-qualified name; or</li> 025 * <li>by qualified (prefixed) name.</li> 026 * </ol> 027 * 028 * <p>The list will not contain attributes that were declared 029 * #IMPLIED but not specified in the start tag. It will also not 030 * contain attributes used as Namespace declarations (xmlns*) unless 031 * the <code>http://xml.org/sax/features/namespace-prefixes</code> 032 * feature is set to <var>true</var> (it is <var>false</var> by 033 * default).</p> 034 * 035 * <p>If the namespace-prefixes feature (see above) is <var>false</var>, 036 * access by qualified name may not be available; if the 037 * <code>http://xml.org/sax/features/namespaces</code> 038 * feature is <var>false</var>, access by Namespace-qualified names 039 * may not be available.</p> 040 * 041 * <p>This interface replaces the now-deprecated SAX1 {@link 042 * org.xml.sax.AttributeList AttributeList} interface, which does not 043 * contain Namespace support. In addition to Namespace support, it 044 * adds the <var>getIndex</var> methods (below).</p> 045 * 046 * <p>The order of attributes in the list is unspecified, and will 047 * vary from implementation to implementation.</p> 048 * 049 * @since SAX 2.0 050 * @author David Megginson, 051 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 052 * @version 2.0 053 * @see org.xml.sax.helpers.AttributeListImpl 054 */ 055public interface Attributes 056{ 057 058 059 //////////////////////////////////////////////////////////////////// 060 // Indexed access. 061 //////////////////////////////////////////////////////////////////// 062 063 064 /** 065 * Return the number of attributes in the list. 066 * 067 * <p>Once you know the number of attributes, you can iterate 068 * through the list.</p> 069 * 070 * @return The number of attributes in the list. 071 * @see #getURI(int) 072 * @see #getLocalName(int) 073 * @see #getQName(int) 074 * @see #getType(int) 075 * @see #getValue(int) 076 */ 077 public abstract int getLength (); 078 079 080 /** 081 * Look up an attribute's Namespace URI by index. 082 * 083 * @param index The attribute index (zero-based). 084 * @return The Namespace URI, or the empty string if none 085 * is available, or null if the index is out of 086 * range. 087 * @see #getLength 088 */ 089 public abstract String getURI (int index); 090 091 092 /** 093 * Look up an attribute's local name by index. 094 * 095 * @param index The attribute index (zero-based). 096 * @return The local name, or the empty string if Namespace 097 * processing is not being performed, or null 098 * if the index is out of range. 099 * @see #getLength 100 */ 101 public abstract String getLocalName (int index); 102 103 104 /** 105 * Look up an attribute's XML 1.0 qualified name by index. 106 * 107 * @param index The attribute index (zero-based). 108 * @return The XML 1.0 qualified name, or the empty string 109 * if none is available, or null if the index 110 * is out of range. 111 * @see #getLength 112 */ 113 public abstract String getQName (int index); 114 115 116 /** 117 * Look up an attribute's type by index. 118 * 119 * <p>The attribute type is one of the strings "CDATA", "ID", 120 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", 121 * or "NOTATION" (always in upper case).</p> 122 * 123 * <p>If the parser has not read a declaration for the attribute, 124 * or if the parser does not report attribute types, then it must 125 * return the value "CDATA" as stated in the XML 1.0 Recommentation 126 * (clause 3.3.3, "Attribute-Value Normalization").</p> 127 * 128 * <p>For an enumerated attribute that is not a notation, the 129 * parser will report the type as "NMTOKEN".</p> 130 * 131 * @param index The attribute index (zero-based). 132 * @return The attribute's type as a string, or null if the 133 * index is out of range. 134 * @see #getLength 135 */ 136 public abstract String getType (int index); 137 138 139 /** 140 * Look up an attribute's value by index. 141 * 142 * <p>If the attribute value is a list of tokens (IDREFS, 143 * ENTITIES, or NMTOKENS), the tokens will be concatenated 144 * into a single string with each token separated by a 145 * single space.</p> 146 * 147 * @param index The attribute index (zero-based). 148 * @return The attribute's value as a string, or null if the 149 * index is out of range. 150 * @see #getLength 151 */ 152 public abstract String getValue (int index); 153 154 155 156 //////////////////////////////////////////////////////////////////// 157 // Name-based query. 158 //////////////////////////////////////////////////////////////////// 159 160 161 /** 162 * Look up the index of an attribute by Namespace name. 163 * 164 * @param uri The Namespace URI, or the empty string if 165 * the name has no Namespace URI. 166 * @param localName The attribute's local name. 167 * @return The index of the attribute, or -1 if it does not 168 * appear in the list. 169 */ 170 public int getIndex (String uri, String localPart); 171 172 173 /** 174 * Look up the index of an attribute by XML 1.0 qualified name. 175 * 176 * @param qName The qualified (prefixed) name. 177 * @return The index of the attribute, or -1 if it does not 178 * appear in the list. 179 */ 180 public int getIndex (String qName); 181 182 183 /** 184 * Look up an attribute's type by Namespace name. 185 * 186 * <p>See {@link #getType(int) getType(int)} for a description 187 * of the possible types.</p> 188 * 189 * @param uri The Namespace URI, or the empty String if the 190 * name has no Namespace URI. 191 * @param localName The local name of the attribute. 192 * @return The attribute type as a string, or null if the 193 * attribute is not in the list or if Namespace 194 * processing is not being performed. 195 */ 196 public abstract String getType (String uri, String localName); 197 198 199 /** 200 * Look up an attribute's type by XML 1.0 qualified name. 201 * 202 * <p>See {@link #getType(int) getType(int)} for a description 203 * of the possible types.</p> 204 * 205 * @param qName The XML 1.0 qualified name. 206 * @return The attribute type as a string, or null if the 207 * attribute is not in the list or if qualified names 208 * are not available. 209 */ 210 public abstract String getType (String qName); 211 212 213 /** 214 * Look up an attribute's value by Namespace name. 215 * 216 * <p>See {@link #getValue(int) getValue(int)} for a description 217 * of the possible values.</p> 218 * 219 * @param uri The Namespace URI, or the empty String if the 220 * name has no Namespace URI. 221 * @param localName The local name of the attribute. 222 * @return The attribute value as a string, or null if the 223 * attribute is not in the list. 224 */ 225 public abstract String getValue (String uri, String localName); 226 227 228 /** 229 * Look up an attribute's value by XML 1.0 qualified name. 230 * 231 * <p>See {@link #getValue(int) getValue(int)} for a description 232 * of the possible values.</p> 233 * 234 * @param qName The XML 1.0 qualified name. 235 * @return The attribute value as a string, or null if the 236 * attribute is not in the list or if qualified names 237 * are not available. 238 */ 239 public abstract String getValue (String qName); 240 241} 242 243// end of Attributes.java