org.xml.sax.package.html Maven / Gradle / Ivy
This package provides the core of the Java ME SAX API subset defined by JSR
280. The JSR 280 subset is backward compatible with the subset
defined by JSR 172, and excludes deprecated SAX1 APIs as well as some
SAX2 APIs not essential for Java ME.
Note also that this code is based on the open source SAX APIs:
This package, both source code and documentation, is in the
Public Domain, and comes with NO WARRANTY.
See http://www.saxproject.org
for further information.
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 supported by the
JSR 280 subset are:
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.
namespaces
read/write
true
A value of "true" indicates namespace URIs and unprefixed local names
for element and attribute names will be available.
Note: The pair of properties namespaces and
namespace-prefixes have different default combinations
for SAX (true, false) and JAXP (false, true). JSR 280 compliant
implementations must support both the SAX and JAXP default combinations.
namespace-prefixes
read/write
false
A value of "true" indicates that XML qualified names (with prefixes) and
attributes (including xmlns* attributes) will be available.
Note: The pair of properties namespaces and
namespace-prefixes have different default combinations
for SAX (true, false) and JAXP (false, true). JSR 280 compliant
implementations must support both the SAX and JAXP default combinations.
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(), and
- DTDHandler.unparsedEntityDecl().
It does not apply to EntityResolver.resolveEntity(),
which is not used to report declarations.
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.
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
dom-node. Manage those properties using
setProperty(). Those identifiers are:
Property ID
Description
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.
xml-string
Readable only during a parser callback, this exposes a
chunk of characters responsible for the current event.
All of these standard properties are optional;
XMLReader implementations need not support them.