View Javadoc

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.4 2004/03/19 20:17:54 maartenc 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 the empty string
45   * when defining a default element namespace.)  For portability,
46   * handler code should always resolve that conflict, rather than
47   * requiring parsers that can change the setting of that feature flag.
48   * </p>
49   *
50   * <p>If the namespace-prefixes feature (see above) is <var>false</var>, 
51   * access by qualified name may not be available; if the 
52   * <code>http://xml.org/sax/features/namespaces</code>
53   * feature is <var>false</var>, access by Namespace-qualified names 
54   * may not be available.</p>
55   *
56   * <p>This interface replaces the now-deprecated SAX1 {@link
57   * org.xml.sax.AttributeList AttributeList} interface, which does not 
58   * contain Namespace support.  In addition to Namespace support, it 
59   * adds the <var>getIndex</var> methods (below).</p>
60   *
61   * <p>The order of attributes in the list is unspecified, and will
62   * vary from implementation to implementation.</p>
63   *
64   * @since SAX 2.0
65   * @author David Megginson
66   * @version 2.0.1 (sax2r2)
67   * @see org.xml.sax.helpers.AttributesImpl
68   * @see org.xml.sax.ext.DeclHandler#attributeDecl
69   */
70  public interface Attributes
71  {
72  
73  
74      ////////////////////////////////////////////////////////////////////
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     ////////////////////////////////////////////////////////////////////
172     // Name-based query.
173     ////////////////////////////////////////////////////////////////////
174 
175 
176     /***
177      * Look up the index of an attribute by Namespace name.
178      *
179      * @param uri The Namespace URI, or the empty string if
180      *        the name has no Namespace URI.
181      * @param localName The attribute's local name.
182      * @return The index of the attribute, or -1 if it does not
183      *         appear in the list.
184      */
185     public int getIndex (String uri, String localName);
186 
187 
188     /***
189      * Look up the index of an attribute by XML qualified (prefixed) name.
190      *
191      * @param qName The qualified (prefixed) name.
192      * @return The index of the attribute, or -1 if it does not
193      *         appear in the list.
194      */
195     public int getIndex (String qName);
196 
197 
198     /***
199      * Look up an attribute's type by Namespace name.
200      *
201      * <p>See {@link #getType(int) getType(int)} for a description
202      * of the possible types.</p>
203      *
204      * @param uri The Namespace URI, or the empty String if the
205      *        name has no Namespace URI.
206      * @param localName The local name of the attribute.
207      * @return The attribute type as a string, or null if the
208      *         attribute is not in the list or if Namespace
209      *         processing is not being performed.
210      */
211     public abstract String getType (String uri, String localName);
212 
213 
214     /***
215      * Look up an attribute's type by XML qualified (prefixed) name.
216      *
217      * <p>See {@link #getType(int) getType(int)} for a description
218      * of the possible types.</p>
219      *
220      * @param qName The XML qualified name.
221      * @return The attribute type as a string, or null if the
222      *         attribute is not in the list or if qualified names
223      *         are not available.
224      */
225     public abstract String getType (String qName);
226 
227 
228     /***
229      * Look up an attribute's value by Namespace name.
230      *
231      * <p>See {@link #getValue(int) getValue(int)} for a description
232      * of the possible values.</p>
233      *
234      * @param uri The Namespace URI, or the empty String if the
235      *        name has no Namespace URI.
236      * @param localName The local name of the attribute.
237      * @return The attribute value as a string, or null if the
238      *         attribute is not in the list.
239      */
240     public abstract String getValue (String uri, String localName);
241 
242 
243     /***
244      * Look up an attribute's value by XML qualified (prefixed) name.
245      *
246      * <p>See {@link #getValue(int) getValue(int)} for a description
247      * of the possible values.</p>
248      *
249      * @param qName The XML qualified name.
250      * @return The attribute value as a string, or null if the
251      *         attribute is not in the list or if qualified names
252      *         are not available.
253      */
254     public abstract String getValue (String qName);
255 
256 }
257 
258 // end of Attributes.java