/*

 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/**

 * Provides the core SAX APIs.

 * Some SAX1 APIs are deprecated to encourage integration of

 * namespace-awareness into designs of new applications

 * and into maintenance of existing infrastructure.

 *

 * <p>

 * See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a>

 * for more information about SAX.

 *

 *

 * <h2> SAX2 Standard Feature Flags </h2>

 *

 * <p>

 * One of the essential characteristics of SAX2 is that it added

 * feature flags which can be used to examine and perhaps modify

 * parser modes, in particular modes such as validation.

 * Since features are identified by (absolute) URIs, anyone

 * can define such features.

 * Currently defined standard feature URIs have the prefix

 * <code>http://xml.org/sax/features/</code> before an identifier such as

 * <code>validation</code>.  Turn features on or off using

 * <em>setFeature</em>.  Those standard identifiers are:

 *

 *

 * <table border="1" cellpadding="3" cellspacing="0" width="100%">

 *     <tr align="center" bgcolor="#ccccff">

 *      <th>Feature ID</th>

 *      <th>Access</th>

 *      <th>Default</th>

 *      <th>Description</th>

 *      </tr>

 *

 *     <tr>

 *      <td>external-general-entities</td>

 *      <td><em>read/write</em></td>

 *      <td><em>unspecified</em></td>

 *      <td> Reports whether this parser processes external

 *          general entities; always true if validating.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>external-parameter-entities</td>

 *      <td><em>read/write</em></td>

 *      <td><em>unspecified</em></td>

 *      <td> Reports whether this parser processes external

 *          parameter entities; always true if validating.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>is-standalone</td>

 *      <td>(parsing) <em>read-only</em>, (not parsing) <em>none</em></td>

 *      <td>not applicable</td>

 *      <td> May be examined only during a parse, after the

 *          <em>startDocument()</em> callback has been completed; read-only.

 *          The value is true if the document specified standalone="yes" in

 *          its XML declaration, and otherwise is false.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>lexical-handler/parameter-entities</td>

 *      <td><em>read/write</em></td>

 *      <td><em>unspecified</em></td>

 *      <td> A value of "true" indicates that the LexicalHandler will report

 *          the beginning and end of parameter entities.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>namespaces</td>

 *      <td><em>read/write</em></td>

 *      <td>true</td>

 *      <td> A value of "true" indicates namespace URIs and unprefixed local names

 *          for element and attribute names will be available.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>namespace-prefixes</td>

 *      <td><em>read/write</em></td>

 *      <td>false</td>

 *      <td> A value of "true" indicates that XML qualified names (with prefixes) and

 *          attributes (including <em>xmlns*</em> attributes) will be available.

 *              </td>

 *      </tr>

 *

 *     <tr>

 *      <td>resolve-dtd-uris</td>

 *      <td><em>read/write</em></td>

 *      <td><em>true</em></td>

 *      <td> A value of "true" indicates that system IDs in declarations will

 *          be absolutized (relative to their base URIs) before reporting.

 *          (That is the default behavior for all SAX2 XML parsers.)

 *          A value of "false" indicates those IDs will not be absolutized;

 *          parsers will provide the base URI from

 *          <em>Locator.getSystemId()</em>.

 *          This applies to system IDs passed in <ul>

 *              <li><em>DTDHandler.notationDecl()</em>,

 *              <li><em>DTDHandler.unparsedEntityDecl()</em>, and

 *              <li><em>DeclHandler.externalEntityDecl()</em>.

 *          </ul>

 *          It does not apply to <em>EntityResolver.resolveEntity()</em>,

 *          which is not used to report declarations, or to

 *          <em>LexicalHandler.startDTD()</em>, which already provides

 *          the non-absolutized URI.

 *          </td>

 *      </tr>

 *

 *     <tr>

 *      <td>string-interning</td>

 *      <td><em>read/write</em></td>

 *      <td><em>unspecified</em></td>

 *      <td> Has a value of "true" if all XML names (for elements, prefixes,

 *          attributes, entities, notations, and local names),

 *          as well as Namespace URIs, will have been interned

 *          using <em>java.lang.String.intern</em>. This supports fast

 *          testing of equality/inequality against string constants,

 *          rather than forcing slower calls to <em>String.equals()</em>.

 *          </td>

 *      </tr>

 *

 *     <tr>

 *     <td>unicode-normalization-checking</td>

 *     <td><em>read/write</em></td>

 *     <td><em>false</em></td>

 *     <td> Controls whether the parser reports Unicode normalization

 *         errors as described in section 2.13 and Appendix B of the

 *         XML 1.1 Recommendation. If true, Unicode normalization

 *         errors are reported using the ErrorHandler.error() callback.

 *         Such errors are not fatal in themselves (though, obviously,

 *         other Unicode-related encoding errors may be).

 *              </td>

 *     </tr>

 *

 *     <tr>

 *      <td>use-attributes2</td>

 *      <td><em>read-only</em></td>

 *      <td>not applicable</td>

 *      <td> Returns "true" if the <em>Attributes</em> objects passed by

 *          this parser in <em>ContentHandler.startElement()</em>

 *          implement the <a href="ext/Attributes2.html"

 *          ><em>org.xml.sax.ext.Attributes2</em></a> interface.

 *          That interface exposes additional DTD-related information,

 *          such as whether the attribute was specified in the

 *          source text rather than defaulted.

 *      </td>

 *     </tr>

 *

 *     <tr>

 *      <td>use-locator2</td>

 *      <td><em>read-only</em></td>

 *      <td>not applicable</td>

 *      <td> Returns "true" if the <em>Locator</em> objects passed by

 *          this parser in <em>ContentHandler.setDocumentLocator()</em>

 *          implement the <a href="ext/Locator2.html"

 *          ><em>org.xml.sax.ext.Locator2</em></a> interface.

 *          That interface exposes additional entity information,

 *          such as the character encoding and XML version used.

 *         </td>

 *     </tr>

 *

 *     <tr>

 *      <td>use-entity-resolver2</td>

 *      <td><em>read/write</em></td>

 *      <td><em>true</em></td>

 *      <td> Returns "true" if, when <em>setEntityResolver</em> is given

 *          an object implementing the <a href="ext/EntityResolver2.html"

 *          ><em>org.xml.sax.ext.EntityResolver2</em></a> interface,

 *          those new methods will be used.

 *          Returns "false" to indicate that those methods will not be used.

 *      </td>

 *     </tr>

 *

 *     <tr>

 *      <td>validation</td>

 *      <td><em>read/write</em></td>

 *      <td><em>unspecified</em></td>

 *      <td> Controls whether the parser is reporting all validity

 *          errors; if true, all external entities will be read.

 *      </td>

 *     </tr>

 *

 *     <tr>

 *      <td>xmlns-uris</td>

 *      <td><em>read/write</em></td>

 *      <td><em>false</em></td>

 *      <td> Controls whether, when the <em>namespace-prefixes</em> feature

 *          is set, the parser treats namespace declaration attributes as

 *          being in the <em>http://www.w3.org/2000/xmlns/</em> namespace.

 *          By default, SAX2 conforms to the original "Namespaces in XML"

 *          Recommendation, which explicitly states that such attributes are

 *          not in any namespace.

 *          Setting this optional flag to "true" makes the SAX2 events conform to

 *          a later backwards-incompatible revision of that recommendation,

 *          placing those attributes in a namespace.

 *      </td>

 *     </tr>

 *

 *     <tr>

 *         <td>xml-1.1</td>

 *         <td><em>read-only</em></td>

 *         <td>not applicable</td>

 *         <td> Returns "true" if the parser supports both XML 1.1 and XML 1.0.

 *             Returns "false" if the parser supports only XML 1.0.

 *         </td>

 *     </tr>

 * </table>

 *

 * <p>

 * Support for the default values of the

 * <em>namespaces</em> and <em>namespace-prefixes</em>

 * properties is required.

 * Support for any other feature flags is entirely optional.

 *

 *

 * <p>

 * For default values not specified by SAX2,

 * each XMLReader implementation specifies its default,

 * or may choose not to expose the feature flag.

 * Unless otherwise specified here,

 * implementations may support changing current values

 * of these standard feature flags, but not while parsing.

 *

 *

 * <h2> SAX2 Standard Handler and Property IDs </h2>

 *

 * <p>

 * For parser interface characteristics that are described

 * as objects, a separate namespace is defined.  The

 * objects in this namespace are again identified by URI, and

 * the standard property URIs have the prefix

 * <code>http://xml.org/sax/properties/</code> before an identifier such as

 * <code>lexical-handler</code> or

 * <code>dom-node</code>.  Manage those properties using

 * <em>setProperty()</em>.  Those identifiers are:

 *

 * <table border="1" cellpadding="3" cellspacing="0" width="100%">

 *     <tr align="center" bgcolor="#ccccff">

 *      <th>Property ID</th>

 *      <th>Description</th>

 *      </tr>

 *

 *     <tr>

 *      <td>declaration-handler</td>

 *      <td> Used to see most DTD declarations except those treated

 *          as lexical ("document element name is ...") or which are

 *          mandatory for all SAX parsers (<em>DTDHandler</em>).

 *          The Object must implement <a href="ext/DeclHandler.html"

 *          ><em>org.xml.sax.ext.DeclHandler</em></a>.

 *         </td>

 *     </tr>

 *

 *     <tr>

 *         <td>document-xml-version</td>

 *         <td> May be examined only during a parse, after the startDocument()

 *             callback has been completed; read-only. This property is a

 *             literal string describing the actual XML version of the document,

 *             such as "1.0" or "1.1".

 *         </td>

 *     </tr>

 *

 *     <tr>

 *      <td>dom-node</td>

 *      <td> For "DOM Walker" style parsers, which ignore their

 *          <em>parser.parse()</em> parameters, this is used to

 *          specify the DOM (sub)tree being walked by the parser.

 *          The Object must implement the

 *          <em>org.w3c.dom.Node</em> interface.

 *         </td>

 *     </tr>

 *

 *     <tr>

 *      <td>lexical-handler</td>

 *      <td> Used to see some syntax events that are essential in some

 *          applications:  comments, CDATA delimiters, selected general

 *          entity inclusions, and the start and end of the DTD

 *          (and declaration of document element name).

 *          The Object must implement <a href="ext/LexicalHandler.html"

 *          ><em>org.xml.sax.ext.LexicalHandler</em></a>.

 *         </td>

 *     </tr>

 *

 *     <tr>

 *      <td>xml-string</td>

 *      <td> Readable only during a parser callback, this exposes a <b>TBS</b>

 *          chunk of characters responsible for the current event.

 *         </td>

 *     </tr>

 * </table>

 *

 * <p>

 * All of these standard properties are optional.

 * XMLReader implementations are not required to support them.

 *

 *

 * @since 1.4

 */

package org.xml.sax;