|
||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
AttributeList | Deprecated. This interface has been replaced by the SAX2
Attributes
interface, which includes Namespace support. |
Attributes | Interface for a list of XML attributes. |
ContentHandler | Receive notification of the logical content of a document. |
DocumentHandler | Deprecated. This interface has been replaced by the SAX2
ContentHandler
interface, which includes Namespace support. |
DTDHandler | Receive notification of basic DTD-related events. |
EntityResolver | Basic interface for resolving entities. |
ErrorHandler | Basic interface for SAX error handlers. |
Locator | Interface for associating a SAX event with a document location. |
Parser | Deprecated. This interface has been replaced by the SAX2
XMLReader
interface, which includes Namespace support. |
XMLFilter | Interface for an XML filter. |
XMLReader | SAX2 Interface for reading an XML document using callbacks. |
Class Summary | |
HandlerBase | Deprecated. This class works with the deprecated
DocumentHandler
interface. |
InputSource | A single input source for an XML entity. |
Exception Summary | |
SAXException | Encapsulate a general SAX error or warning. |
SAXNotRecognizedException | Exception class for an unrecognized identifier. |
SAXNotSupportedException | Exception class for an unsupported operation. |
SAXParseException | Encapsulate an XML parse error or warning. |
This package provides the core SAX1 and SAX2 APIs. SAX1 APIs are deprecated to encourage integration of namespace-awareness into designs of new applications and maintainance of existing infrastructure. For more information on SAX, see the SAX page.
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:
Feature ID | Default | Description |
---|---|---|
external-general-entities | unspecified | Reports whether this parser processes external general entities; always true if validating |
external-parameter-entities | unspecified | Reports whether this parser processes external parameter entities; always true if validating |
lexical-handler/parameter-entities | unspecified | true indicates that the LexicalHandler will report the beginning and end of parameter entities |
namespaces | true | true indicates namespace URIs and unprefixed local names for element and attribute names will be available |
namespace-prefixes | false | true indicates XML 1.0 names (with prefixes) and attributes (including xmlns* attributes) will be available |
string-interning | unspecified | true if all XML names (for elements, prefixes, attributes, and local names), as well as Namespace URIs, will have been interned using java.lang.String.intern, supporting fast testing of equality/inequality with string constants |
validation | unspecified | controls whether the parser is reporting all validity errors; if true, all external entities will be read. |
Support for the default values of the namespaces and namespace-prefixes properties is required.
For default values not specified by SAX2, each XMLReader implementation specifies its default (or may choose not to expose the feature flag). Implementations may support changing current standard feature values, but not while parsing.
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:
Property ID | Description |
---|---|
declaration-handler | Used to see most DTD declarations except those treated as lexical ("root element name is ...") or which are mandatory for all SAX parsers (DTDHandler). The Object must implement DeclHandler. |
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. |
lexical-handler | Used to see some syntax events that are essential in some applications: comments, CDATA delimeters, selected general entity inclusions, and the start and end of the DTD. The Object must implement 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 need not support them.
Namespace support is the root of the incompatibilities between SAX1 and SAX2. Namespaces are not part of XML itself, but are felt to be sufficiently strategic that this layer has been integrated into the SAX2 API. Existing applications needs to change two method signatures, and add two new handler methods, to handle SAX2 namespace features.
Names in the ContentHandler startElement and endElement callback must now, by default, conform to the XML + Namespaces specification. You will get two callbacks describing the beginning and end of a scope for a given name prefix, and may also see the attributes which tell you that same thing. (As a rule, ignore those callbacks.)
If you explicitly enable the namespace-prefixes feature on a parser, you can see the xmlns* attributes, and the element and attribute names as found in the document (with prefixes). If your SAX1 application is currently namespace aware, or needs to work with data that may use prefixed (or perhaps hierarchical) names, you must enable that feature in order to continue working correctly with a SAX2 parser, in addition to making the various call syntax changes. (You can phase in use of the SAX2 namespace features incrementally, as you verify that it's safe for use with each existing application's data set or messaging partner.)
|
Source code is GPL'd in the JAXP subproject at http://savannah.gnu.org/projects/classpathx |
|||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |