-- - -This document is in the Public Domain.
-
(See the ChangeLog in the distribution for more details.)
- -(See the ChangeLog included in the distribution for
-more detailed information.)
org.xml.sax.driver property is not specified
-but the SAX org.xml.sax.parser property is specified, XMLReaderFactory.createXMLReader() will
-attempt to create an XML1 Parser and then wrap it in
-a ParserAdapter.org.xml.sax.ext package into a separate
-distribution, SAX2-ext. The DeclHandler and
-LexicalHandler classes are no longer part of the core SAX2
-distribution.The following interfaces and classes have been deprecated, and will -be removed from a future version of SAX; they should be used only for -interaction with SAX1 drivers or applications:
- -The following interfaces and classes have been added to SAX2:
- -SAX2 contains complete Namespace support, which is available by -default from any XMLReader. An XML -reader can also optionally supply raw XML 1.0 names. See SAX2: Namespaces for more details.
- -An XML reader is fully configurable: it is possible to attempt to -query or change the current value of any feature or property. -Features and properties are identified by fully-qualified URIs, and -parties are free to invent their own names for new extensions. See SAX2: Features and Properties for more -details.
- -The ContentHandler and Attributes interfaces -are similar to the deprecated DocumentHandler -and AttributeList -interfaces, but they add support for Namespace-related information. -ContentHandler also adds a callback for skipped entities, and -Attributes adds the ability to look up an attribute's index by -name.
- -The ParserAdapter -class makes a SAX1 Parser behave as a SAX2 XMLReader. The XMLReaderAdapter -class makes a SAX2 XML reader behave as a SAX1 parser. These two -classes should ease the transition from SAX1 to SAX2 by allowing SAX1 -drivers and clients to co-exist with SAX2 drivers and clients in the -same application.
- - --- -This document is in the Public Domain.
-
SAX2 adds standard methods to query and set features and properties -in an XMLReader. It -is now possible to request an XML reader to validate (or not to -validate) a document, or to internalize (or not to internalize) all -names, using the getFeature, setFeature, -getProperty, and setProperty methods:
- -
-try {
- if (xmlReader.getFeature("http://xml.org/sax/features/validation")) {
- System.out.println("Parser is validating.");
- } else {
- System.out.println("Parser is not validating.");
- }
-} catch (SAXException e) {
- System.out.println("Parser may or may not be validating.");
-}
-There is no fixed set of features or properties available for SAX2: -implementors are free to define new features and properties as needed. -All feature and property names are fully-qualified URIs (often URLs), -such as "http://www.acme.com/features/foo"; as with Namespace URIs, -people should always define feature and property names based on URIs -that they control.
- -If an application attempts to query or set a feature that the XML -reader does not recognize, the XML reader throws a SAXNotRecognizedException; if the application attempts to set a -feature state or property value that the XML reader cannot support at -that time, or attempts to modify a feature or property when it is -read-only, the XML reader throws a SAXNotSupportedException.
- -One important application for properties is getting and setting -extension event handlers, for event types not supported by the four -core SAX2 handlers, EntityResolver, DTDHandler, ContentHandler, and -ErrorHandler. -Outside parties are free to define handlers for any kinds of events, -and to create properties for setting and querying them.
- -All XML readers are required to recognize the -"http://xml.org/sax/features/namespaces" and the -"http://xml.org/sax/features/namespace-prefixes" features (see below), -and to support a true value for the namespaces property and -a false value for the namespace-prefixes property: these -requirements ensure that all SAX2 XML readers can provide the minimal -required Namespace support for higher-level specs such as RDF, XSL, -XML Schemas, and XLink. XML readers are not required to recognize or -support any other features or any properties, even the core ones -listed below.
- - -While anyone is free to define new SAX2 features, there is a core -reference set of features that are application to a wide range of -applications, and that many SAX2 XML readers may choose to support. -Note that features may be read-only or read/write, and that they may -be modifiable only when parsing, or only when not parsing.
- -http://xml.org/sax/features/namespaceshttp://xml.org/sax/features/namespace-prefixeshttp://xml.org/sax/features/string-interninghttp://xml.org/sax/features/validationhttp://xml.org/sax/features/external-general-entitieshttp://xml.org/sax/features/external-parameter-entitiesWhile anyone is free to define new SAX2 properties, there is a core -reference set of properties that are application to a wide range of -applications, and that many SAX2 XML readers may choose to support. -Note that properties may be read-only or read/write, and that they may -be modifiable only when parsing, or only when not parsing.
- -http://xml.org/sax/properties/dom-nodeorg.w3c.dom.Nodehttp://xml.org/sax/properties/xml-stringjava.lang.String-- -This document is in the Public Domain.
-
The SAX interface assumes two basic streams:
- -With SAX1, programmers quickly realized that it was possible to -extend this model to support a processing chain, where requests could -flow through several different components, or filters, before arriving -at the original SAX driver, and events could flow through the same -filters before arriving at the application. Each filter can make -changes to the stream of events as it passes through, but the whole -chain of filters still appears to be a single SAX driver to the -application.
- -SAX2 formalizes this design technique by adding a new interface, org.xml.sax.XMLFilter, -and a new helper class, org.xml.sax.XMLFilterImpl.
- -The XMLFilter interface itself is very simple, extending -the basic XMLReader interface with two additional -methods:
- -
-public interface XMLFilter extends XMLReader
-{
- public abstract void setParent (XMLReader parent);
- public abstract XMLReader getParent ();
-}
-In other words, a SAX2 filter is simply an XMLReader that has -another XMLReader as its parent.
- -In normal use, a filter will implement not only the -XMLFilter interface but also one or all of the various -resolver and handler interfaces (EntityResolver, -DTDHandler, ContentHandler, and -ErrorHandler). To the parent XML reader, the filter is the -client application receiving the events; to the client application, -the filter is the SAX driver producing the events.
- -The XMLFilterImpl helper class provides a convenient -base for deriving SAX2 filters. This class implements the -XMLFilter, EntityResolver, -DTDHandler, ContentHandler, and -ErrorHandler interfaces. By default, it passes all events -on unmodified, but the derived filter can override specific -methods.
- -Here's an example of a very simple filter that changes the
-Namespace URI http://www.foo.com/ns/ to
-http://www.bar.com/ wherever it appears in an element
-name (but not an attribute name):
-public class FooFilter extends XMLFilterImpl
-{
- public FooFilter ()
- {
- }
-
- public FooFilter (XMLReader parent)
- {
- super(parent);
- }
-
-
- /**
- * Filter the Namespace URI for start-element events.
- */
- public void startElement (String uri, String localName,
- String qName, Attributes atts)
- throws SAXException
- {
- if (uri.equals("http://www.foo.com/ns/")) {
- uri = "http://www.bar.com/ns/";
- }
- super.startElement(uri, localName, qName, atts);
- }
-
-
- /**
- * Filter the Namespace URI for end-element events.
- */
- public void endElement (String uri, String localName, String qName)
- throws SAXException
- {
- if (uri.equals("http://www.foo.com/ns/")) {
- uri = "http://www.bar.com/ns/";
- }
- super.endElement(uri, localName, qName);
- }
-
-}
-Note the use of super.startElement and -super.endElement to send the event on to the client. In a -real filter, it would be good to override the -ContentHandler.startPrefixMapping and -ContentHandler.endPrefixMapping methods as well.
- -Long filter chains are not always the best approach, but you will -find that it is sometimes easier to build complex XML applications if -you can break them down into a collection of simple SAX filters, each -one reading the events from its parent.
- --- -This document is in the Public Domain.
-
SAX2 adds XML Namespace support, which is -required for higher-level standards like XSL, XML Schemas, RDF, and XLink. Every implementation of the SAX2 XMLReader interface is -required to support Namespace processing as its default state; some -XML readers may also allow Namespace processing to be disabled or -modified (note to SAX driver writers: there is a helper class, NamespaceSupport, -that can do most of the work of Namespace processing for you).
- -Namespace processing affects only element and attribute names. -Without Namespace processing, each XML element and attribute has a -single, local name (called the qName), which may contain a -colon; with Namespace processing, each element and attribute has a -two-part name, consisting of an optional URI (equivalent to a Java or -Perl package name) followed by a local name which may not contain a -colon.
- -SAX is capable of supporting either of these views or both -simultaneously, though XML readers are required to support only the -Namespaces view, and most applications will not need anything -further.
- -Namespace support affects the ContentHandler and -Attributes -interfaces.
- - -In SAX2, the startElement and endElement callbacks in a content handler look like this:
- -- --public void startElement (String uri, String localName, - String qName, Attributes atts) - throws SAXException; - -public void endElement (String uri, String localName, String qName) - throws SAXException; -
By default, an XML reader will report a Namespace URI and a local -name for every element, in both the start and end handler. Consider -the following example:
- -- -- <html:hr xmlns:html="http://www.w3.org/1999/xhtml"/> -
With the default SAX2 Namespace processing, the XML reader would -report a start and end element event with the Namespace URI -"http://www.w3.org/1999/xhtml" and the local name "hr". The XML -reader might also report the original qName "html:hr", but that -parameter might simply be an empty string.
- - -For attributes, you can look up the value of a named attribute -using the getValue method, and you can look up the Namespace URI or local -name of an attribute by its index using the getURI and -getLocalName methods (usually when you're iterating -through the entire attribute list):
- -
-String rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
-String resource = atts.getValue(rdfns, "resource");
-
-for (int i = 0; i < atts.getLength(); i++) {
- String uri = atts.getURI(i);
- String localName = atts.getLocalName(i);
- String value = atts.getValue(i);
- /* ... */
-}
-In addition to those events, SAX2 reports the scope of Namespace -declarations using the startPrefixMapping and endPrefixMapping methods, so that applications can resolve -prefixes in attribute values or character data if necessary. The -callbacks look like this:
- -- --public void startPrefixMapping (String prefix, String uri) - throws SAXException; -public void endPrefixMapping (String prefix) - throws SAXException; -
For the above example, the XML reader would make the following -callback before the start-element event:
- -
-startPrefixMapping("html", "http://www.w3.org/1999/xhtml")
-The XML reader would make the following callback after the -end-element event:
- -
-endPrefixMapping("html")
-The rest of this document applies only to SAX2 applications with -special requirements, such as text editors.
- -The "http://xml.org/features/namespaces" feature controls general -Namespace processing: when this feature is true (the default), -Namespace URIs and local names must be available through the -startElement and endElement callbacks in the ContentHandler -interface, and through the various methods in the Attributes interface, -and start/endPrefixMapping events must be reported.
- -The "http://xml.org/features/namespace-prefixes" feature controls -the reporting of qNames and Namespace declarations (xmlns* -attributes): when this feature is false (the default), qNames may -optionally be reported, and xmlns* attributes must not be -reported.
- -The following table summarizes the interaction of these two -features (for general information on using features, see SAX2: Features and Properties):
- -| namespaces | -namespace-prefixes | -Namespace names | -start/endPrefixMapping | -qNames | -xmlns* attributes | -
|---|---|---|---|---|---|
| true | -false | -YES | -YES | -unknown | -NO | -
| true | -true | -YES | -YES | -YES | -YES | -
| false | -false | -(ILLEGAL COMBINATION) | -|||
| false | -true | -unknown | -unknown | -YES | -YES | -
Note xmlns* attributes will not be -reported unless the namespace-prefixes feature is true (it -is false by default).
- - -Consider the following simple sample document:
- -- --<?xml version="1.0"?> - -<h:hello xmlns:h="http://www.greeting.com/ns/" id="a1" h:person="David"/> -
If namespaces is true and namespace-prefixes -is false (the default), then a SAX2 XML reader will report the -following:
- -If namespaces is true and namespace-prefixes -is true, then a SAX2 XML reader will report the following:
- -If namespaces is false and namespace-prefixes -is true, then a SAX2 XML reader will report the following:
- --- -This document is in the Public Domain.
-
This document provides a quick-start tutorial for Java programmers -who wish to use SAX2 in their programs.
- - -SAX is not an XML parser.
- -SAX is a common interface implemented for many different XML -parsers (and things that pose as XML parsers), just as the JDBC is a -common interface implemented for many different relational databases -(and things that pose as relational databases). If you want to use -SAX, you'll need all of the following:
- -Java 1.1 or higher.
The SAX2 distribution installed on your Java -classpath.
A SAX2-compatible XML parser installed on your Java -classpath.
The name of the SAX2 driver class in your XML parser (read the -documentation that came with the parser, and write down the class -name).
Start by creating a class that extends DefaultHandler:
- -
-import org.xml.sax.helpers.DefaultHandler;
-
-public class MySAXApp extends DefaultHandler
-{
-
- public MySAXApp ()
- {
- super();
- }
-
-}
-Now, let's assume that the SAX driver for your XML parser is named -"com.acme.xml.SAXDriver" (this does not really exist: you -must find out the name of the real driver for your parser). -Since this is a Java application, we'll create a static -main method that creates a new instance of this driver -(note the "throws Exception" wimp-out):
- -
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = new com.acme.xml.SAXDriver();
- }
-Alternatively, if you don't want to tie your application to a -specific SAX driver, you can use the createXMLReader -method from the XMLReaderFactory class to choose a SAX driver dynamically:
- -
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = XMLReaderFactory.createXMLReader();
- }
-In this case, it will be necessary at runtime to set the -org.xml.sax.driver Java system property to the full classname of the -SAX driver, as in
- -- --java -Dorg.xml.sax.driver=com.acme.xml.SAXDriver MySAXApp sample.xml -
We can use this object to parse XML documents, but first, we have -to register event handlers that the parser can use for reporting -information, using the setContentHandler and setErrorHandler methods from the XMLReader interface. In -a real-world application, the handlers will usually be separate -objects, but for this simple demo, we've bundled the handlers into the -top-level class, so we just have to instantiate the class and register -it with the XML reader:
- -
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = XMLReaderFactory.createXMLReader();
- MySAXApp handler = new MySAXApp();
- xr.setContentHandler(handler);
- xr.setErrorHandler(handler);
- }
-This code creates an instance of MySAXApp to receive XML parsing -events, and registers it with the XML reader for regular content -events and error events (there are other kinds, but they're rarely -used). Now, let's assume that all of the command-line args are file -names, and we'll try to parse them one-by-one using the parse method from the XMLReader interface:
- -
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = XMLReaderFactory.createXMLReader();
- MySAXApp handler = new MySAXApp();
- xr.setContentHandler(handler);
- xr.setErrorHandler(handler);
-
- // Parse each file provided on the
- // command line.
- for (int i = 0; i < args.length; i++) {
- FileReader r = new FileReader(args[i]);
- xr.parse(new InputSource(r));
- }
- }
-Note that each reader must be wrapped in an InputSource object to be parsed. Here's the whole demo class -together (so far):
- -
-import java.io.FileReader;
-
-import org.xml.sax.XMLReader;
-import org.xml.sax.InputSource;
-import org.xml.sax.helpers.XMLReaderFactory;
-import org.xml.sax.helpers.DefaultHandler;
-
-
-public class MySAXApp extends DefaultHandler
-{
-
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = XMLReaderFactory.createXMLReader();
- MySAXApp handler = new MySAXApp();
- xr.setContentHandler(handler);
- xr.setErrorHandler(handler);
-
- // Parse each file provided on the
- // command line.
- for (int i = 0; i < args.length; i++) {
- FileReader r = new FileReader(args[i]);
- xr.parse(new InputSource(r));
- }
- }
-
-
- public MySAXApp ()
- {
- super();
- }
-}
-You can compile this code and run it (make sure you specify the SAX -driver class in the org.xml.sax.driver property), but nothing much -will happen unless the document contains malformed XML, because you -have not yet set up your application to handle SAX events.
- - -Things get interesting when you start implementing methods to -respond to XML parsing events (remember that we registered our class -to receive XML parsing events in the previous section). The most -important events are the start and end of the document, the start and -end of elements, and character data.
- -To find out about the start and end of the document, the client -application implements the startDocument and endDocument methods:
- -
- public void startDocument ()
- {
- System.out.println("Start document");
- }
-
- public void endDocument ()
- {
- System.out.println("End document");
- }
-The start/endDocument event handlers take no arguments. When the -SAX driver finds the beginning of the document, it will invoke the -startDocument method once; when it finds the end, it will -invoke the endDocument method once (if there have been -errors, endDocument may not be invoked).
- -These examples simply print a message to standard output, but your -application can contain any arbitrary code in these handlers: most -commonly, the code will build some kind of an in-memory tree, produce -output, populate a database, or extract information from the XML -stream.
- -The SAX driver will signal the start and end of elements in much -the same way, except that it will also pass some parameters to the startElement and endElement methods:
- -
- public void startElement (String uri, String name,
- String qName, Attributes atts)
- {
- System.out.println("Start element: {" + uri + "}" + name);
- }
-
- public void endElement (String uri, String name, String qName)
- {
- System.out.println("End element: {" + uri + "}" + name);
- }
-These methods print a message every time an element starts or ends, -with the Namespace URI in braces before the element's local name. The -qName contains the raw XML 1.0 name, and since not all -SAX drivers will report it, it is best to ignore that parameter for -now.
- -Finally, SAX2 reports regular character data through the characters method; the following implementation will print all -character data to the screen; it is a little longer because it -pretty-prints the output by escaping special characters:
- -
- public void characters (char ch[], int start, int length)
- {
- System.out.print("Characters: \"");
- for (int i = start; i < start + length; i++) {
- switch (ch[i]) {
- case '\\':
- System.out.print("\\\\");
- break;
- case '"':
- System.out.print("\\\"");
- break;
- case '\n':
- System.out.print("\\n");
- break;
- case '\r':
- System.out.print("\\r");
- break;
- case '\t':
- System.out.print("\\t");
- break;
- default:
- System.out.print(ch[i]);
- break;
- }
- }
- System.out.print("\"\n");
- }
-Note that a SAX driver is free to chunk the character data any way -it wants, so you cannot count on all of the character data content of -an element arriving in a single characters event.
- - -Here is the complete sample application (again, in a serious app -the event handlers would probably be implemented in a separate -class):
- -
-import java.io.FileReader;
-
-import org.xml.sax.XMLReader;
-import org.xml.sax.Attributes;
-import org.xml.sax.InputSource;
-import org.xml.sax.helpers.XMLReaderFactory;
-import org.xml.sax.helpers.DefaultHandler;
-
-
-public class MySAXApp extends DefaultHandler
-{
-
- public static void main (String args[])
- throws Exception
- {
- XMLReader xr = XMLReaderFactory.createXMLReader();
- MySAXApp handler = new MySAXApp();
- xr.setContentHandler(handler);
- xr.setErrorHandler(handler);
-
- // Parse each file provided on the
- // command line.
- for (int i = 0; i < args.length; i++) {
- FileReader r = new FileReader(args[i]);
- xr.parse(new InputSource(r));
- }
- }
-
-
- public MySAXApp ()
- {
- super();
- }
-
-
- ////////////////////////////////////////////////////////////////////
- // Event handlers.
- ////////////////////////////////////////////////////////////////////
-
-
- public void startDocument ()
- {
- System.out.println("Start document");
- }
-
-
- public void endDocument ()
- {
- System.out.println("End document");
- }
-
-
- public void startElement (String uri, String name,
- String qName, Attributes atts)
- {
- System.out.println("Start element: {" + uri + "}" + name);
- }
-
-
- public void endElement (String uri, String name, String qName)
- {
- System.out.println("End element: {" + uri + "}" + name);
- }
-
-
- public void characters (char ch[], int start, int length)
- {
- System.out.print("Characters: \"");
- for (int i = start; i < start + length; i++) {
- switch (ch[i]) {
- case '\\':
- System.out.print("\\\\");
- break;
- case '"':
- System.out.print("\\\"");
- break;
- case '\n':
- System.out.print("\\n");
- break;
- case '\r':
- System.out.print("\\r");
- break;
- case '\t':
- System.out.print("\\t");
- break;
- default:
- System.out.print(ch[i]);
- break;
- }
- }
- System.out.print("\"\n");
- }
-
-}
-Consider the following XML document:
- -- --<?xml version="1.0"?> - -<poem xmlns="http://www.megginson.com/ns/exp/poetry"> -<title>Roses are Red</title> -<l>Roses are red,</l> -<l>Violets are blue;</l> -<l>Sugar is sweet,</l> -<l>And I love you.</l> -</poem> -
If this document is named roses.xml and there is a
-SAX2 driver on your classpath named
-com.acme.xml.SAXDriver (this driver does not actually
-exist), you can invoke the sample application like this:
- --java -Dcom.acme.xml.SAXDriver MySAXApp roses.xml -
When you run this, you'll get output something like this:
- -
-Start document
-Start element: {http://www.megginson.com/ns/exp/poetry}poem
-Characters: "\n"
-Start element: {http://www.megginson.com/ns/exp/poetry}title
-Characters: "Roses are Red"
-End element: {http://www.megginson.com/ns/exp/poetry}title
-Characters: "\n"
-Start element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "Roses are red,"
-End element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "\n"
-Start element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "Violets are blue;"
-End element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "\n"
-Start element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "Sugar is sweet,"
-End element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "\n"
-Start element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "And I love you."
-End element: {http://www.megginson.com/ns/exp/poetry}l
-Characters: "\n"
-End element: {http://www.megginson.com/ns/exp/poetry}poem
-End document
-Note that even a short document generates (at least) 25 events: one -for the start and end of each of the six elements used (or, if you -prefer, one for each start tag and one for each end tag), one of each -of the eleven chunks of character data (including whitespace between -elements), one for the start of the document, and one for the end.
- - --- -This document is in the Public Domain.
-
SAX2 is a new Java-based release of SAX, the Simple API for -XML. A C++ version (at least) is planned as well. SAX2 -introduces configurable features and properties and adds support for -XML Namespaces; it includes adapters so that SAX1 parsers and -applications can interoperate with SAX2.
- -