1 /*
2 * Copyright (c) 2015, 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 /**
27 * Provides the interfaces for the Simple API for XML (SAX). Supports both
28 * the SAX1 and SAX2 APIs.
29 *
30 * <p>
31 * <h2> SAX2 Standard Feature Flags </h2>
32 *
33 * <p>
34 * One of the essential characteristics of SAX2 is that it added
35 * feature flags which can be used to examine and perhaps modify
36 * parser modes, in particular modes such as validation.
37 * Since features are identified by (absolute) URIs, anyone
38 * can define such features.
39 * Currently defined standard feature URIs have the prefix
40 * <code>http://xml.org/sax/features/</code> before an identifier such as
41 * <code>validation</code>. Turn features on or off using
42 * <em>setFeature</em>. Those standard identifiers are:
43 *
44 *
45 * <table class="striped">
46 * <caption>Standard Features</caption>
47 * <thead>
48 * <tr>
49 * <th scope="col">Feature ID</th>
50 * <th scope="col">Access</th>
51 * <th scope="col">Default</th>
52 * <th scope="col">Description</th>
53 * </tr>
54 * </thead>
55 *
56 * <tbody>
57 * <tr>
58 * <th scope="row">external-general-entities</th>
59 * <td><em>read/write</em></td>
60 * <td><em>unspecified</em></td>
61 * <td> Reports whether this parser processes external
62 * general entities; always true if validating.
63 * </td>
64 * </tr>
65 *
66 * <tr>
67 * <th scope="row">external-parameter-entities</th>
68 * <td><em>read/write</em></td>
69 * <td><em>unspecified</em></td>
70 * <td> Reports whether this parser processes external
71 * parameter entities; always true if validating.
72 * </td>
73 * </tr>
74 *
75 * <tr>
76 * <th scope="row">is-standalone</th>
77 * <td>(parsing) <em>read-only</em>, (not parsing) <em>none</em></td>
78 * <td>not applicable</td>
79 * <td> May be examined only during a parse, after the
80 * <em>startDocument()</em> callback has been completed; read-only.
81 * The value is true if the document specified standalone="yes" in
82 * its XML declaration, and otherwise is false.
83 * </td>
84 * </tr>
85 *
86 * <tr>
87 * <th scope="row">lexical-handler/parameter-entities</th>
88 * <td><em>read/write</em></td>
89 * <td><em>unspecified</em></td>
90 * <td> A value of "true" indicates that the LexicalHandler will report
91 * the beginning and end of parameter entities.
92 * </td>
93 * </tr>
94 *
95 * <tr>
96 * <th scope="row">namespaces</th>
97 * <td><em>read/write</em></td>
98 * <td>true</td>
99 * <td> A value of "true" indicates namespace URIs and unprefixed local names
100 * for element and attribute names will be available.
101 * </td>
102 * </tr>
103 *
104 * <tr>
105 * <th scope="row">namespace-prefixes</th>
106 * <td><em>read/write</em></td>
107 * <td>false</td>
108 * <td> A value of "true" indicates that XML qualified names (with prefixes) and
109 * attributes (including <em>xmlns*</em> attributes) will be available.
110 * </td>
111 * </tr>
112 *
113 * <tr>
114 * <th scope="row">resolve-dtd-uris</th>
115 * <td><em>read/write</em></td>
116 * <td><em>true</em></td>
117 * <td> A value of "true" indicates that system IDs in declarations will
118 * be absolutized (relative to their base URIs) before reporting.
119 * (That is the default behavior for all SAX2 XML parsers.)
120 * A value of "false" indicates those IDs will not be absolutized;
121 * parsers will provide the base URI from
122 * <em>Locator.getSystemId()</em>.
123 * This applies to system IDs passed in <ul>
124 * <li><em>DTDHandler.notationDecl()</em>,
125 * <li><em>DTDHandler.unparsedEntityDecl()</em>, and
126 * <li><em>DeclHandler.externalEntityDecl()</em>.
127 * </ul>
128 * It does not apply to <em>EntityResolver.resolveEntity()</em>,
129 * which is not used to report declarations, or to
130 * <em>LexicalHandler.startDTD()</em>, which already provides
131 * the non-absolutized URI.
132 * </td>
133 * </tr>
134 *
135 * <tr>
136 * <th scope="row">string-interning</th>
137 * <td><em>read/write</em></td>
138 * <td><em>unspecified</em></td>
139 * <td> Has a value of "true" if all XML names (for elements, prefixes,
140 * attributes, entities, notations, and local names),
141 * as well as Namespace URIs, will have been interned
142 * using <em>java.lang.String.intern</em>. This supports fast
143 * testing of equality/inequality against string constants,
144 * rather than forcing slower calls to <em>String.equals()</em>.
145 * </td>
146 * </tr>
147 *
148 * <tr>
149 * <th scope="row">unicode-normalization-checking</th>
150 * <td><em>read/write</em></td>
151 * <td><em>false</em></td>
152 * <td> Controls whether the parser reports Unicode normalization
153 * errors as described in section 2.13 and Appendix B of the
154 * XML 1.1 Recommendation. If true, Unicode normalization
155 * errors are reported using the ErrorHandler.error() callback.
156 * Such errors are not fatal in themselves (though, obviously,
157 * other Unicode-related encoding errors may be).
158 * </td>
159 * </tr>
160 *
161 * <tr>
162 * <th scope="row">use-attributes2</th>
163 * <td><em>read-only</em></td>
164 * <td>not applicable</td>
165 * <td> Returns "true" if the <em>Attributes</em> objects passed by
166 * this parser in <em>ContentHandler.startElement()</em>
167 * implement the <a href="ext/Attributes2.html"
168 * ><em>org.xml.sax.ext.Attributes2</em></a> interface.
169 * That interface exposes additional DTD-related information,
170 * such as whether the attribute was specified in the
171 * source text rather than defaulted.
172 * </td>
173 * </tr>
174 *
175 * <tr>
176 * <th scope="row">use-locator2</th>
177 * <td><em>read-only</em></td>
178 * <td>not applicable</td>
179 * <td> Returns "true" if the <em>Locator</em> objects passed by
180 * this parser in <em>ContentHandler.setDocumentLocator()</em>
181 * implement the <a href="ext/Locator2.html"
182 * ><em>org.xml.sax.ext.Locator2</em></a> interface.
183 * That interface exposes additional entity information,
184 * such as the character encoding and XML version used.
185 * </td>
186 * </tr>
187 *
188 * <tr>
189 * <th scope="row">use-entity-resolver2</th>
190 * <td><em>read/write</em></td>
191 * <td><em>true</em></td>
192 * <td> Returns "true" if, when <em>setEntityResolver</em> is given
193 * an object implementing the <a href="ext/EntityResolver2.html"
194 * ><em>org.xml.sax.ext.EntityResolver2</em></a> interface,
195 * those new methods will be used.
196 * Returns "false" to indicate that those methods will not be used.
197 * </td>
198 * </tr>
199 *
200 * <tr>
201 * <th scope="row">validation</th>
202 * <td><em>read/write</em></td>
203 * <td><em>unspecified</em></td>
204 * <td> Controls whether the parser is reporting all validity
205 * errors; if true, all external entities will be read.
206 * </td>
207 * </tr>
208 *
209 * <tr>
210 * <th scope="row">xmlns-uris</th>
211 * <td><em>read/write</em></td>
212 * <td><em>false</em></td>
213 * <td> Controls whether, when the <em>namespace-prefixes</em> feature
214 * is set, the parser treats namespace declaration attributes as
215 * being in the <em>http://www.w3.org/2000/xmlns/</em> namespace.
216 * By default, SAX2 conforms to the original "Namespaces in XML"
217 * Recommendation, which explicitly states that such attributes are
218 * not in any namespace.
219 * Setting this optional flag to "true" makes the SAX2 events conform to
220 * a later backwards-incompatible revision of that recommendation,
221 * placing those attributes in a namespace.
222 * </td>
223 * </tr>
224 *
225 * <tr>
226 * <th scope="row">xml-1.1</th>
227 * <td><em>read-only</em></td>
228 * <td>not applicable</td>
229 * <td> Returns "true" if the parser supports both XML 1.1 and XML 1.0.
230 * Returns "false" if the parser supports only XML 1.0.
231 * </td>
232 * </tr>
233 * </tbody>
234 * </table>
235 *
236 * <p>
237 * Support for the default values of the
238 * <em>namespaces</em> and <em>namespace-prefixes</em>
239 * properties is required.
240 * Support for any other feature flags is entirely optional.
241 *
242 *
243 * <p>
244 * For default values not specified by SAX2,
245 * each XMLReader implementation specifies its default,
246 * or may choose not to expose the feature flag.
247 * Unless otherwise specified here,
248 * implementations may support changing current values
249 * of these standard feature flags, but not while parsing.
250 *
251 *
252 * <h2> SAX2 Standard Handler and Property IDs </h2>
253 *
254 * <p>
255 * For parser interface characteristics that are described
256 * as objects, a separate namespace is defined. The
257 * objects in this namespace are again identified by URI, and
258 * the standard property URIs have the prefix
259 * <code>http://xml.org/sax/properties/</code> before an identifier such as
260 * <code>lexical-handler</code> or
261 * <code>dom-node</code>. Manage those properties using
262 * <em>setProperty()</em>. Those identifiers are:
263 *
264 * <table class="striped">
265 * <caption>Standard Property IDs</caption>
266 * <thead>
267 * <tr>
268 * <th scope="col">Property ID</th>
269 * <th scope="col">Description</th>
270 * </tr>
271 * </thead>
272 *
273 * <tbody>
274 * <tr>
275 * <th scope="row">declaration-handler</th>
276 * <td> Used to see most DTD declarations except those treated
277 * as lexical ("document element name is ...") or which are
278 * mandatory for all SAX parsers (<em>DTDHandler</em>).
279 * The Object must implement <a href="ext/DeclHandler.html"
280 * ><em>org.xml.sax.ext.DeclHandler</em></a>.
281 * </td>
282 * </tr>
283 *
284 * <tr>
285 * <th scope="row">document-xml-version</th>
286 * <td> May be examined only during a parse, after the startDocument()
287 * callback has been completed; read-only. This property is a
288 * literal string describing the actual XML version of the document,
289 * such as "1.0" or "1.1".
290 * </td>
291 * </tr>
292 *
293 * <tr>
294 * <th scope="row">dom-node</th>
295 * <td> For "DOM Walker" style parsers, which ignore their
296 * <em>parser.parse()</em> parameters, this is used to
297 * specify the DOM (sub)tree being walked by the parser.
298 * The Object must implement the
299 * <em>org.w3c.dom.Node</em> interface.
300 * </td>
301 * </tr>
302 *
303 * <tr>
304 * <th scope="row">lexical-handler</th>
305 * <td> Used to see some syntax events that are essential in some
306 * applications: comments, CDATA delimiters, selected general
307 * entity inclusions, and the start and end of the DTD
308 * (and declaration of document element name).
309 * The Object must implement <a href="ext/LexicalHandler.html"
310 * ><em>org.xml.sax.ext.LexicalHandler</em></a>.
311 * </td>
312 * </tr>
313 *
314 * <tr>
315 * <th scope="row">xml-string</th>
316 * <td> Readable only during a parser callback, this exposes a <b>TBS</b>
317 * chunk of characters responsible for the current event.
318 * </td>
319 * </tr>
320 * </tbody>
321 * </table>
322 *
323 * <p>
324 * All of these standard properties are optional.
325 * XMLReader implementations are not required to support them.
326 *
327 * @apiNote The SAX API, originally developed at
328 * <a href="http://www.saxproject.org">the SAX Project</a>, was introduced
329 * in Java SE 1.4 and continues to be maintained as part of Java SE.
330 *
331 * @since 1.4
332 */
333
334 package org.xml.sax;