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