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;