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     ////////////////////////////////////////////////////////////////////
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      */
getLength()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      */
getURI(int index)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      */
getLocalName(int index)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      */
getQName(int index)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      */
getType(int index)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      */
getValue(int index)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      */
getIndex(String uri, String localName)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      */
getIndex(String qName)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      */
getType(String uri, String localName)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      */
getType(String qName)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      */
getValue(String uri, String localName)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      */
getValue(String qName)253     public abstract String getValue (String qName);
254 
255 }
256 
257 // end of Attributes.java
258