An Introduction to StAX
by Elliotte Rusty Harold
|
Pages: 1, 2
This simple example perhaps doesn't demonstrate the full power of StAX. Since the client application controls the process, it's easy to write separate methods for different elements. These methods can have detailed knowledge of the internal structure of the type of element they handle. For example, you could write one method that handles headers, one that handles img elements, one that handles tables, one that handles meta tags, and so forth. For example, you might process an html element that contains head and body child elements like this:
public void processHtml(XmlPullParser parser) {
while (true) {
int event = parser.next();
if (event == XMLStreamConstants.START_ELEMENT) {
if (parser.getLocalName().equals("head")) processHead(parser);
else if (parser.getLocalName().equals("body")) processBody(parser)
}
else if (event == XMLStreamConstants.END_ELEMENT) {// </html>
return;
}
}
}Here I'm making a lot of assumptions about exactly which tags appear
where when. This isn't unusual in XML processing . Most programs are
written with particular vocabularies in mind. You wouldn't expect an XHTML
outliner to know what to do with a DocBook document, much less an SVG
picture, for example. However, it is best to test and verify your
expectations about data formats. Normally, this would be done through
validation. You can turn on validation by setting the factory's
javax.xml.stream.isValidating property to true before
instantiating the parser like this:
factory.setProperty("javax.xml.stream.isValidating", Boolean.TRUE);You would then register an XMLReporter with the
XMLInputFactory to receive notices of the validity
errors. For example, using an anonymous inner class,
factory.setXMLReporter(new XMLReporter() {
public void report(String message, String errorType,
Object relatedInformation, Location location) {
System.err.println("Problem in " + location.getLocationURI());
System.err.println("at line " + location.getLineNumber()
+ ", column " + location.getColumnNumber());
System.err.println(message);
}
});If you want validity errors to be fatal, throw an
XMLStreamException from the report method rather than just
printing the error message. However, StAX parsers are not required to be
able to validate and the reference implementation can't, so this doesn't
yet work.
StAX does offer an alternative for simple cases. If you expect a particular item to be present in the document, you can require it using a type and an optional name and namespace. For example, if I think that the cursor is positioned at an XHTML <head> start-tag, I'd require it thusly:
parser.require(XMLStreamConstants.START_ELEMENT,
"http://www.w3.org/1999/xhtml",
"head");If my expectation proves wrong, then the require method throws an XMLStreamException, a checked exception. You can pass null for either the namespace or the element name to indicate that all namespaces and names are acceptable. Putting this all together, the general pattern might be something like:
try {
parser.next();
parser.require(XMLStreamConstants.START_ELEMENT,
"http://www.w3.org/1999/xhtml",
"head");
processHead(parser);
}
catch (XMLStreamException ex) {
// Oops! The head was missing!
}Output
StAX is not limited to reading XML documents. It can also create
them. For output, instead of an XMLStreamReader you use,
naturally enough, an XMLStreamWriter. This interface provides
methods to write elements, attributes, comments, text, and all the other
parts of an XML document. An XMLStreamWriter is created by an
XMLOutputFactory like this:
OutputStream out = new FileOutputStream("data.xml");
XMLOutputFactory factory = XMLOutputFactory.newInstance();
XMLStreamWriter writer = factory.createXMLStreamWriter(out);You write data onto the stream by using various writeFOO
methods: writeStartDocument, writeStartElement, writeEndElement,
writeCharacters, writeComment, writeCDATA, etc. For example, these
lines of code write a simple hello world document:
writer.writeStartDocument("ISO-8859-1", "1.0");
writer.writeStartElement("greeting");
writer.writeAttribute("id", "g1");
writer.writeCharacters("Hello StAX");
writer.writeEndDocument();When you've finished creating the document, you want to flush and close the writer. This does not close the underlying output stream, so you'll need to close that too:
writer.flush();
writer.close();
out.close();XMLStreamWriter helps maintain some well-formedness
constraints. For instance, endDocument closes all unclosed
start-tags, and writeCharacters performs any necessary
escaping of reserved characters like & and <. However, the checking
is minimal. XMLStreamWriter allows documents with multiple
roots, documents with more than one XML declaration, element names that
contain whitespace, characters that don't exist in the output character
set, and a lot more. Implementations are allowed but not required to check
these things. The reference implementation does not check them. Separate
verification and testing of the output is necessary. Creating XML
documents with XMLStreamWriter is faster and more more
efficient than serializing a DOM or XOM tree, but it's not nearly as
robust.
Summing Up
This article has just skimmed along the surface of StAX; the API has more to offer than there is space here to describe. Like SAX, StAX enables pipelines that chain the output of one process to the input of the next. It can filter the documents it parses to modify or log the documents. It can support XML views of non-XML data. It can marshal data structures and objects into XML documents and it can unmarshal the documents back into objects.
When is StAX not appropriate? Basically whenever a streaming API doesn't work. Like SAX, StAX still requires you to build data structures as the document is parsed in order to hold onto information for any length of time. In the worst case, these data structures can become as large and complex as the original document. In these cases, a tree-based API such as DOM or XOM may be more appropriate. Such an API definitely provides more convenient random access to the tree than does StAX (or any other streaming API). StAX works well when you need to process a large document a small piece at a time moving from beginning to end, that is, when you can essentially slide a peephole over the complete document. It works less well when you need to access widely separated parts of the document at the same time in unpredictable orders. However, many of the toughest XML processing problems come from exactly the domain where StAX does work well.
StAX is a fast, potentially extremely fast, straight-forward, memory-thrifty way to loading data from an XML document the structure of which is well known in advance. State management is much simpler in StAX than in SAX, so if you find that the SAX logic is just getting way too complex to follow or debug, then StAX is well worth exploring. A few features such as validation, schema support, and entity resolution are either not available or are not functional in the current reference implementation, but these should soon be available in independent implementations. StAX will be a very useful addition to any Java developer's XML toolkit.
- Why "streaming" word is used in StAX?
2007-03-22 02:55:51 vikas_khengare - StAX, Streaming APIs and DOM
2006-06-06 09:49:58 MichaelTrachtman - I have a question about this acticle
2004-01-29 09:20:33 Jeff Wong - bidirectional SAX
2003-10-03 17:11:52 Taylor Cowan - FYI: Patent pending
2003-10-01 03:35:10 Marty Feldmann - xmliter: another alternative
2003-09-21 18:29:55 Mark Hayes - Actually, StAX provides Event-Object based access!
2003-09-18 06:23:57 Stefan Haustein
