java/14 : java.xml/org/xml/sax/package-info.java

org.xml.sax

https://openjdk.java.net/

GPLv2 + Classpath Exception

/*
 * Copyright (c) 2015, 2019, 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 interfaces for the Simple API for XML (SAX). Supports both
the SAX1 and SAX2 APIs.

 SAX2 Standard Feature Flags 

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
http://xml.org/sax/features/ before an identifier such as
validation.  Turn features on or off using
setFeature.  Those standard identifiers are:

    Standard Features
    
    
     Feature ID
     Access
     Default
     Description
     
    
    
    
     external-general-entities
     read/write
     unspecified
      Reports whether this parser processes external
         general entities; always true if validating.
             
     
    
     external-parameter-entities
     read/write
     unspecified
      Reports whether this parser processes external
         parameter entities; always true if validating.
             
     
    
     is-standalone
     (parsing) read-only, (not parsing) none
     not applicable
      May be examined only during a parse, after the
         startDocument() callback has been completed; read-only.
         The value is true if the document specified standalone="yes" in
         its XML declaration, and otherwise is false.
             
     
    
     lexical-handler/parameter-entities
     read/write
     unspecified
      A value of "true" indicates that the LexicalHandler will report
         the beginning and end of parameter entities.
             
     
    
     namespaces
     read/write
     true
      A value of "true" indicates namespace URIs and unprefixed local names
         for element and attribute names will be available.
             
     
    
     namespace-prefixes
     read/write
     false
      A value of "true" indicates that XML qualified names (with prefixes) and
         attributes (including xmlns* attributes) will be available.
             
     
    
     resolve-dtd-uris
     read/write
     true
      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
         Locator.getSystemId().
         This applies to system IDs passed in 
             DTDHandler.notationDecl(),
             
DTDHandler.unparsedEntityDecl(), and
             
DeclHandler.externalEntityDecl().
         
         It does not apply to EntityResolver.resolveEntity(),
         which is not used to report declarations, or to
         LexicalHandler.startDTD(), which already provides
         the non-absolutized URI.
         
     
    
     string-interning
     read/write
     unspecified
      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 java.lang.String.intern. This supports fast
         testing of equality/inequality against string constants,
         rather than forcing slower calls to String.equals().
         
     
    
    unicode-normalization-checking
    read/write
    false
     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).
             
    
    
     use-attributes2
     read-only
     not applicable
      Returns "true" if the Attributes objects passed by
         this parser in ContentHandler.startElement()
         implement the org.xml.sax.ext.Attributes2 interface.
         That interface exposes additional DTD-related information,
         such as whether the attribute was specified in the
         source text rather than defaulted.
     
    
    
     use-locator2
     read-only
     not applicable
      Returns "true" if the Locator objects passed by
         this parser in ContentHandler.setDocumentLocator()
         implement the org.xml.sax.ext.Locator2 interface.
         That interface exposes additional entity information,
         such as the character encoding and XML version used.
        
    
    
     use-entity-resolver2
     read/write
     true
      Returns "true" if, when setEntityResolver is given
         an object implementing the org.xml.sax.ext.EntityResolver2 interface,
         those new methods will be used.
         Returns "false" to indicate that those methods will not be used.
     
    
    
     validation
     read/write
     unspecified
      Controls whether the parser is reporting all validity
         errors; if true, all external entities will be read.
     
    
    
     xmlns-uris
     read/write
     false
      Controls whether, when the namespace-prefixes feature
         is set, the parser treats namespace declaration attributes as
         being in the http://www.w3.org/2000/xmlns/ 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.
     
    
    
        xml-1.1
        read-only
        not applicable
         Returns "true" if the parser supports both XML 1.1 and XML 1.0.
            Returns "false" if the parser supports only XML 1.0.
        
    
    


Support for the default values of the
namespaces and namespace-prefixes
properties is required.
Support for any other feature flags is entirely optional.

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.
 SAX2 Standard Handler and Property IDs 

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
http://xml.org/sax/properties/ before an identifier such as
lexical-handler or
dom-node.  Manage those properties using
setProperty().  Those identifiers are:

    Standard Property IDs
    
    
     Property ID
     Description
     
     
    
    
     declaration-handler
      Used to see most DTD declarations except those treated
         as lexical ("document element name is ...") or which are
         mandatory for all SAX parsers (DTDHandler).
         The Object must implement org.xml.sax.ext.DeclHandler.
        
    
    
        document-xml-version
         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".
        
    
    
     dom-node
      For "DOM Walker" style parsers, which ignore their
         parser.parse() parameters, this is used to
         specify the DOM (sub)tree being walked by the parser.
         The Object must implement the
         org.w3c.dom.Node interface.
        
    
    
     lexical-handler
      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 org.xml.sax.ext.LexicalHandler.
        
    
    
     xml-string
      Readable only during a parser callback, this exposes a TBS
         chunk of characters responsible for the current event.
        
    
    


All of these standard properties are optional.
XMLReader implementations are not required to support them.
API Note: The SAX API, originally developed at
the SAX Project,
has been defined by Java SE since 1.4.
Since: 1.4/**
 * Provides the interfaces for the Simple API for XML (SAX). Supports both
 * the SAX1 and SAX2 APIs.
 *
 * <p>
 * <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 class="striped">
 *     <caption>Standard Features</caption>
 *     <thead>
 *     <tr>
 *      <th scope="col">Feature ID</th>
 *      <th scope="col">Access</th>
 *      <th scope="col">Default</th>
 *      <th scope="col">Description</th>
 *      </tr>
 *     </thead>
 *
 *     <tbody>
 *     <tr>
 *      <th scope="row">external-general-entities</th>
 *      <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>
 *      <th scope="row">external-parameter-entities</th>
 *      <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>
 *      <th scope="row">is-standalone</th>
 *      <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>
 *      <th scope="row">lexical-handler/parameter-entities</th>
 *      <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>
 *      <th scope="row">namespaces</th>
 *      <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>
 *      <th scope="row">namespace-prefixes</th>
 *      <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>
 *      <th scope="row">resolve-dtd-uris</th>
 *      <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>
 *      <th scope="row">string-interning</th>
 *      <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>
 *     <th scope="row">unicode-normalization-checking</th>
 *     <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>
 *      <th scope="row">use-attributes2</th>
 *      <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>
 *      <th scope="row">use-locator2</th>
 *      <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>
 *      <th scope="row">use-entity-resolver2</th>
 *      <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>
 *      <th scope="row">validation</th>
 *      <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>
 *      <th scope="row">xmlns-uris</th>
 *      <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>
 *         <th scope="row">xml-1.1</th>
 *         <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>
 *     </tbody>
 * </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 class="striped">
 *     <caption>Standard Property IDs</caption>
 *     <thead>
 *     <tr>
 *      <th scope="col">Property ID</th>
 *      <th scope="col">Description</th>
 *      </tr>
 *      </thead>
 *
 *     <tbody>
 *     <tr>
 *      <th scope="row">declaration-handler</th>
 *      <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>
 *         <th scope="row">document-xml-version</th>
 *         <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>
 *      <th scope="row">dom-node</th>
 *      <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>
 *      <th scope="row">lexical-handler</th>
 *      <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>
 *      <th scope="row">xml-string</th>
 *      <td> Readable only during a parser callback, this exposes a <b>TBS</b>
 *          chunk of characters responsible for the current event.
 *         </td>
 *     </tr>
 *     </tbody>
 * </table>
 *
 * <p>
 * All of these standard properties are optional.
 * XMLReader implementations are not required to support them.
 *
 * @apiNote The SAX API, originally developed at
 * <a href="http://www.saxproject.org">the SAX Project</a>,
 * has been defined by Java SE since 1.4.
 *
 * @since 1.4
 */

package org.xml.sax;

Feature ID	Access	Default	Description
external-general-entities	read/write	unspecified	Reports whether this parser processes external general entities; always true if validating.
external-parameter-entities	read/write	unspecified	Reports whether this parser processes external parameter entities; always true if validating.
is-standalone	(parsing) read-only, (not parsing) none	not applicable	May be examined only during a parse, after the startDocument() callback has been completed; read-only. The value is true if the document specified standalone="yes" in its XML declaration, and otherwise is false.
lexical-handler/parameter-entities	read/write	unspecified	A value of "true" indicates that the LexicalHandler will report the beginning and end of parameter entities.
namespaces	read/write	true	A value of "true" indicates namespace URIs and unprefixed local names for element and attribute names will be available.
namespace-prefixes	read/write	false	A value of "true" indicates that XML qualified names (with prefixes) and attributes (including xmlns* attributes) will be available.
resolve-dtd-uris	read/write	true	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 Locator.getSystemId(). This applies to system IDs passed in DTDHandler.notationDecl(), DTDHandler.unparsedEntityDecl(), and DeclHandler.externalEntityDecl(). It does not apply to EntityResolver.resolveEntity(), which is not used to report declarations, or to LexicalHandler.startDTD(), which already provides the non-absolutized URI.
string-interning	read/write	unspecified	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 java.lang.String.intern. This supports fast testing of equality/inequality against string constants, rather than forcing slower calls to String.equals().
unicode-normalization-checking	read/write	false	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).
use-attributes2	read-only	not applicable	Returns "true" if the Attributes objects passed by this parser in ContentHandler.startElement() implement the org.xml.sax.ext.Attributes2 interface. That interface exposes additional DTD-related information, such as whether the attribute was specified in the source text rather than defaulted.
use-locator2	read-only	not applicable	Returns "true" if the Locator objects passed by this parser in ContentHandler.setDocumentLocator() implement the org.xml.sax.ext.Locator2 interface. That interface exposes additional entity information, such as the character encoding and XML version used.
use-entity-resolver2	read/write	true	Returns "true" if, when setEntityResolver is given an object implementing the org.xml.sax.ext.EntityResolver2 interface, those new methods will be used. Returns "false" to indicate that those methods will not be used.
validation	read/write	unspecified	Controls whether the parser is reporting all validity errors; if true, all external entities will be read.
xmlns-uris	read/write	false	Controls whether, when the namespace-prefixes feature is set, the parser treats namespace declaration attributes as being in the http://www.w3.org/2000/xmlns/ 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.
xml-1.1	read-only	not applicable	Returns "true" if the parser supports both XML 1.1 and XML 1.0. Returns "false" if the parser supports only XML 1.0.

Property ID	Description
declaration-handler	Used to see most DTD declarations except those treated as lexical ("document element name is ...") or which are mandatory for all SAX parsers (DTDHandler). The Object must implement org.xml.sax.ext.DeclHandler.
document-xml-version	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".
dom-node	For "DOM Walker" style parsers, which ignore their parser.parse() parameters, this is used to specify the DOM (sub)tree being walked by the parser. The Object must implement the org.w3c.dom.Node interface.
lexical-handler	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 org.xml.sax.ext.LexicalHandler.
xml-string	Readable only during a parser callback, this exposes a TBS chunk of characters responsible for the current event.

API Note:	The SAX API, originally developed at the SAX Project, has been defined by Java SE since 1.4.
Since:	1.4

/

java/ 14/ java.xml/org/xml/sax/package-info.java

SAX2 Standard Feature Flags

SAX2 Standard Handler and Property IDs