1 /*
2 * Copyright (c) 2000, 2019, 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 package org.xml.sax;
27
28
29 /**
30 * Interface for a list of XML attributes.
31 *
32 * <p>This interface allows access to a list of attributes in
33 * three different ways:</p>
34 *
35 * <ol>
36 * <li>by attribute index;</li>
37 * <li>by Namespace-qualified name; or</li>
38 * <li>by qualified (prefixed) name.</li>
39 * </ol>
40 *
41 * <p>The list will not contain attributes that were declared
42 * #IMPLIED but not specified in the start tag. It will also not
43 * contain attributes used as Namespace declarations (xmlns*) unless
44 * the <code>http://xml.org/sax/features/namespace-prefixes</code>
45 * feature is set to <var>true</var> (it is <var>false</var> by
46 * default).
47 * Because SAX2 conforms to the original "Namespaces in XML"
48 * recommendation, it normally does not
49 * give namespace declaration attributes a namespace URI.
50 * </p>
51 *
52 * <p>Some SAX2 parsers may support using an optional feature flag
53 * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request
54 * that those attributes be given URIs, conforming to a later
55 * backwards-incompatible revision of that recommendation. (The
56 * attribute's "local name" will be the prefix, or "xmlns" when
57 * defining a default element namespace.) For portability, handler
58 * code should always resolve that conflict, rather than requiring
59 * parsers that can change the setting of that feature flag. </p>
60 *
61 * <p>If the namespace-prefixes feature (see above) is
62 * <var>false</var>, access by qualified name may not be available; if
63 * the <code>http://xml.org/sax/features/namespaces</code> feature is
64 * <var>false</var>, access by Namespace-qualified names may not be
65 * available.</p>
66 *
67 * <p>This interface replaces the now-deprecated SAX1 {@link
68 * org.xml.sax.AttributeList AttributeList} interface, which does not
69 * contain Namespace support. In addition to Namespace support, it
70 * adds the <var>getIndex</var> methods (below).</p>
71 *
72 * <p>The order of attributes in the list is unspecified, and will
73 * vary from implementation to implementation.</p>
74 *
75 * @since 1.4, SAX 2.0
76 * @author David Megginson
77 * @see org.xml.sax.helpers.AttributesImpl
78 * @see org.xml.sax.ext.DeclHandler#attributeDecl
79 */
80 public interface Attributes
81 {
82
83
84 ////////////////////////////////////////////////////////////////////
85 // Indexed access.
86 ////////////////////////////////////////////////////////////////////
87
88
89 /**
90 * Return the number of attributes in the list.
91 *
92 * <p>Once you know the number of attributes, you can iterate
93 * through the list.</p>
94 *
95 * @return The number of attributes in the list.
96 * @see #getURI(int)
97 * @see #getLocalName(int)
98 * @see #getQName(int)
99 * @see #getType(int)
100 * @see #getValue(int)
101 */
102 public abstract int getLength ();
103
104
105 /**
106 * Look up an attribute's Namespace URI by index.
107 *
108 * @param index The attribute index (zero-based).
109 * @return The Namespace URI, or the empty string if none
110 * is available, or null if the index is out of
111 * range.
112 * @see #getLength
113 */
114 public abstract String getURI (int index);
115
116
117 /**
118 * Look up an attribute's local name by index.
119 *
120 * @param index The attribute index (zero-based).
121 * @return The local name, or the empty string if Namespace
122 * processing is not being performed, or null
123 * if the index is out of range.
124 * @see #getLength
125 */
126 public abstract String getLocalName (int index);
127
128
129 /**
130 * Look up an attribute's XML qualified (prefixed) name by index.
131 *
132 * @param index The attribute index (zero-based).
133 * @return The XML qualified name, or the empty string
134 * if none is available, or null if the index
135 * is out of range.
136 * @see #getLength
137 */
138 public abstract String getQName (int index);
139
140
141 /**
142 * Look up an attribute's type by index.
143 *
144 * <p>The attribute type is one of the strings "CDATA", "ID",
145 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
146 * or "NOTATION" (always in upper case).</p>
147 *
148 * <p>If the parser has not read a declaration for the attribute,
149 * or if the parser does not report attribute types, then it must
150 * return the value "CDATA" as stated in the XML 1.0 Recommendation
151 * (clause 3.3.3, "Attribute-Value Normalization").</p>
152 *
153 * <p>For an enumerated attribute that is not a notation, the
154 * parser will report the type as "NMTOKEN".</p>
155 *
156 * @param index The attribute index (zero-based).
157 * @return The attribute's type as a string, or null if the
158 * index is out of range.
159 * @see #getLength
160 */
161 public abstract String getType (int index);
162
163
164 /**
165 * Look up an attribute's value by index.
166 *
167 * <p>If the attribute value is a list of tokens (IDREFS,
168 * ENTITIES, or NMTOKENS), the tokens will be concatenated
169 * into a single string with each token separated by a
170 * single space.</p>
171 *
172 * @param index The attribute index (zero-based).
173 * @return The attribute's value as a string, or null if the
174 * index is out of range.
175 * @see #getLength
176 */
177 public abstract String getValue (int index);
178
179
180
181 ////////////////////////////////////////////////////////////////////
182 // Name-based query.
183 ////////////////////////////////////////////////////////////////////
184
185
186 /**
187 * Look up the index of an attribute by Namespace name.
188 *
189 * @param uri The Namespace URI, or the empty string if
190 * the name has no Namespace URI.
191 * @param localName The attribute's local 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 uri, String localName);
196
197
198 /**
199 * Look up the index of an attribute by XML qualified (prefixed) name.
200 *
201 * @param qName The qualified (prefixed) name.
202 * @return The index of the attribute, or -1 if it does not
203 * appear in the list.
204 */
205 public int getIndex (String qName);
206
207
208 /**
209 * Look up an attribute's type by Namespace name.
210 *
211 * <p>See {@link #getType(int) getType(int)} for a description
212 * of the possible types.</p>
213 *
214 * @param uri The Namespace URI, or the empty String if the
215 * name has no Namespace URI.
216 * @param localName The local name of the attribute.
217 * @return The attribute type as a string, or null if the
218 * attribute is not in the list or if Namespace
219 * processing is not being performed.
220 */
221 public abstract String getType (String uri, String localName);
222
223
224 /**
225 * Look up an attribute's type by XML qualified (prefixed) name.
226 *
227 * <p>See {@link #getType(int) getType(int)} for a description
228 * of the possible types.</p>
229 *
230 * @param qName The XML qualified name.
231 * @return The attribute type as a string, or null if the
232 * attribute is not in the list or if qualified names
233 * are not available.
234 */
235 public abstract String getType (String qName);
236
237
238 /**
239 * Look up an attribute's value by Namespace name.
240 *
241 * <p>See {@link #getValue(int) getValue(int)} for a description
242 * of the possible values.</p>
243 *
244 * @param uri The Namespace URI, or the empty String if the
245 * name has no Namespace URI.
246 * @param localName The local name of the attribute.
247 * @return The attribute value as a string, or null if the
248 * attribute is not in the list.
249 */
250 public abstract String getValue (String uri, String localName);
251
252
253 /**
254 * Look up an attribute's value by XML qualified (prefixed) name.
255 *
256 * <p>See {@link #getValue(int) getValue(int)} for a description
257 * of the possible values.</p>
258 *
259 * @param qName The XML qualified name.
260 * @return The attribute value as a string, or null if the
261 * attribute is not in the list or if qualified names
262 * are not available.
263 */
264 public abstract String getValue (String qName);
265
266 }
267
268 // end of Attributes.java