Mercurial > hg > openjdk > jdk9 > jaxp
view src/java.xml/share/classes/org/xml/sax/package-info.java @ 1133:a208fa9beeee
8180349: Review JAXP Java SE 9 API javadocs
Reviewed-by: rriggs, lancea
author | joehw |
---|---|
date | Wed, 24 May 2017 14:10:04 -0700 |
parents | |
children |
line wrap: on
line source
/* * 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;