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