View Javadoc
1   /*
2    * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  // Attributes.java - attribute list with Namespace support
27  // http://www.saxproject.org
28  // Written by David Megginson
29  // NO WARRANTY!  This class is in the public domain.
30  // $Id: Attributes.java,v 1.2 2004/11/03 22:44:51 jsuttor Exp $
31  
32  package org.xml.sax;
33  
34  
35  /**
36   * Interface for a list of XML attributes.
37   *
38   * <blockquote>
39   * <em>This module, both source code and documentation, is in the
40   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
41   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>;
42   * for further information.
43   * </blockquote>
44   *
45   * <p>This interface allows access to a list of attributes in
46   * three different ways:</p>
47   *
48   * <ol>
49   * <li>by attribute index;</li>
50   * <li>by Namespace-qualified name; or</li>
51   * <li>by qualified (prefixed) name.</li>
52   * </ol>
53   *
54   * <p>The list will not contain attributes that were declared
55   * #IMPLIED but not specified in the start tag.  It will also not
56   * contain attributes used as Namespace declarations (xmlns*) unless
57   * the <code>http://xml.org/sax/features/namespace-prefixes</code>;
58   * feature is set to <var>true</var> (it is <var>false</var> by
59   * default).
60   * Because SAX2 conforms to the original "Namespaces in XML"
61   * recommendation, it normally does not
62   * give namespace declaration attributes a namespace URI.
63   * </p>
64   *
65   * <p>Some SAX2 parsers may support using an optional feature flag
66   * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request
67   * that those attributes be given URIs, conforming to a later
68   * backwards-incompatible revision of that recommendation.  (The
69   * attribute's "local name" will be the prefix, or "xmlns" when
70   * defining a default element namespace.)  For portability, handler
71   * code should always resolve that conflict, rather than requiring
72   * parsers that can change the setting of that feature flag.  </p>
73   *
74   * <p>If the namespace-prefixes feature (see above) is
75   * <var>false</var>, access by qualified name may not be available; if
76   * the <code>http://xml.org/sax/features/namespaces</code> feature is
77   * <var>false</var>, access by Namespace-qualified names may not be
78   * available.</p>
79   *
80   * <p>This interface replaces the now-deprecated SAX1 {@link
81   * org.xml.sax.AttributeList AttributeList} interface, which does not
82   * contain Namespace support.  In addition to Namespace support, it
83   * adds the <var>getIndex</var> methods (below).</p>
84   *
85   * <p>The order of attributes in the list is unspecified, and will
86   * vary from implementation to implementation.</p>
87   *
88   * @since SAX 2.0
89   * @author David Megginson
90   * @see org.xml.sax.helpers.AttributesImpl
91   * @see org.xml.sax.ext.DeclHandler#attributeDecl
92   */
93  public interface Attributes
94  {
95  
96  
97      ////////////////////////////////////////////////////////////////////
98      // Indexed access.
99      ////////////////////////////////////////////////////////////////////
100 
101 
102     /**
103      * Return the number of attributes in the list.
104      *
105      * <p>Once you know the number of attributes, you can iterate
106      * through the list.</p>
107      *
108      * @return The number of attributes in the list.
109      * @see #getURI(int)
110      * @see #getLocalName(int)
111      * @see #getQName(int)
112      * @see #getType(int)
113      * @see #getValue(int)
114      */
115     public abstract int getLength ();
116 
117 
118     /**
119      * Look up an attribute's Namespace URI by index.
120      *
121      * @param index The attribute index (zero-based).
122      * @return The Namespace URI, or the empty string if none
123      *         is available, or null if the index is out of
124      *         range.
125      * @see #getLength
126      */
127     public abstract String getURI (int index);
128 
129 
130     /**
131      * Look up an attribute's local name by index.
132      *
133      * @param index The attribute index (zero-based).
134      * @return The local name, or the empty string if Namespace
135      *         processing is not being performed, or null
136      *         if the index is out of range.
137      * @see #getLength
138      */
139     public abstract String getLocalName (int index);
140 
141 
142     /**
143      * Look up an attribute's XML qualified (prefixed) name by index.
144      *
145      * @param index The attribute index (zero-based).
146      * @return The XML qualified name, or the empty string
147      *         if none is available, or null if the index
148      *         is out of range.
149      * @see #getLength
150      */
151     public abstract String getQName (int index);
152 
153 
154     /**
155      * Look up an attribute's type by index.
156      *
157      * <p>The attribute type is one of the strings "CDATA", "ID",
158      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
159      * or "NOTATION" (always in upper case).</p>
160      *
161      * <p>If the parser has not read a declaration for the attribute,
162      * or if the parser does not report attribute types, then it must
163      * return the value "CDATA" as stated in the XML 1.0 Recommendation
164      * (clause 3.3.3, "Attribute-Value Normalization").</p>
165      *
166      * <p>For an enumerated attribute that is not a notation, the
167      * parser will report the type as "NMTOKEN".</p>
168      *
169      * @param index The attribute index (zero-based).
170      * @return The attribute's type as a string, or null if the
171      *         index is out of range.
172      * @see #getLength
173      */
174     public abstract String getType (int index);
175 
176 
177     /**
178      * Look up an attribute's value by index.
179      *
180      * <p>If the attribute value is a list of tokens (IDREFS,
181      * ENTITIES, or NMTOKENS), the tokens will be concatenated
182      * into a single string with each token separated by a
183      * single space.</p>
184      *
185      * @param index The attribute index (zero-based).
186      * @return The attribute's value as a string, or null if the
187      *         index is out of range.
188      * @see #getLength
189      */
190     public abstract String getValue (int index);
191 
192 
193 
194     ////////////////////////////////////////////////////////////////////
195     // Name-based query.
196     ////////////////////////////////////////////////////////////////////
197 
198 
199     /**
200      * Look up the index of an attribute by Namespace name.
201      *
202      * @param uri The Namespace URI, or the empty string if
203      *        the name has no Namespace URI.
204      * @param localName The attribute's local name.
205      * @return The index of the attribute, or -1 if it does not
206      *         appear in the list.
207      */
208     public int getIndex (String uri, String localName);
209 
210 
211     /**
212      * Look up the index of an attribute by XML qualified (prefixed) name.
213      *
214      * @param qName The qualified (prefixed) name.
215      * @return The index of the attribute, or -1 if it does not
216      *         appear in the list.
217      */
218     public int getIndex (String qName);
219 
220 
221     /**
222      * Look up an attribute's type by Namespace name.
223      *
224      * <p>See {@link #getType(int) getType(int)} for a description
225      * of the possible types.</p>
226      *
227      * @param uri The Namespace URI, or the empty String if the
228      *        name has no Namespace URI.
229      * @param localName The local name of the attribute.
230      * @return The attribute type as a string, or null if the
231      *         attribute is not in the list or if Namespace
232      *         processing is not being performed.
233      */
234     public abstract String getType (String uri, String localName);
235 
236 
237     /**
238      * Look up an attribute's type by XML qualified (prefixed) name.
239      *
240      * <p>See {@link #getType(int) getType(int)} for a description
241      * of the possible types.</p>
242      *
243      * @param qName The XML qualified name.
244      * @return The attribute type as a string, or null if the
245      *         attribute is not in the list or if qualified names
246      *         are not available.
247      */
248     public abstract String getType (String qName);
249 
250 
251     /**
252      * Look up an attribute's value by Namespace name.
253      *
254      * <p>See {@link #getValue(int) getValue(int)} for a description
255      * of the possible values.</p>
256      *
257      * @param uri The Namespace URI, or the empty String if the
258      *        name has no Namespace URI.
259      * @param localName The local name of the attribute.
260      * @return The attribute value as a string, or null if the
261      *         attribute is not in the list.
262      */
263     public abstract String getValue (String uri, String localName);
264 
265 
266     /**
267      * Look up an attribute's value by XML qualified (prefixed) name.
268      *
269      * <p>See {@link #getValue(int) getValue(int)} for a description
270      * of the possible values.</p>
271      *
272      * @param qName The XML qualified name.
273      * @return The attribute value as a string, or null if the
274      *         attribute is not in the list or if qualified names
275      *         are not available.
276      */
277     public abstract String getValue (String qName);
278 
279 }
280 
281 // end of Attributes.java