Welcome!

Java IoT Authors: Pat Romanski, Elizabeth White, Liz McMillan, Peter Silva, Patrick Hubbard

Related Topics: Java IoT

Java IoT: Article

StAX: Java's XML Pull Parser Specification

An overview

Until recently Java programmers have had three options when wishing to access the XML infoset: they could use DOM, JDOM, or SAX. With the release of the JSR 173 StAX specification, Java programmers now have a fourth option, which gives them the efficiency of SAX with a convenient and extendable programming model. This article explores the rationale behind StAX's pull parsing model and describes how you can use the API to more cleanly create Java code to extract the information you need from your XML document. The article describes StAX's two API flavors, "cursor" and "event," and provides some of the reasons why the specification ended up containing two sets of reading and writing APIs. Example usage of each of the reading APIs and each of the writing APIs will be provided.

Document Streaming vs Document Object Model
When creating code that processes XML documents there are two approaches to dealing with the XML infoset data: object model and streaming. With object model, you first create an in-memory object model tree that holds the complete infoset state for an XML document; once in memory you can freely navigate around the tree and even evaluate arbitrary XPath expressions against the tree. This flexibility comes at a price - the complete details of the XML document must be held in memory as objects for the entire duration of the document processing. The creation of the document object graph requires considerable processor resources and takes up a large memory footprint. This may not be a problem for small XML documents, but for large XML ones memory may become a bottleneck to application performance.

With the streaming approach the XML infoset is processed in a serial manner (as a depth first traversal of the XML infoset tree); once an element has been seen its state is discarded and may be garbage collected. Only the infoset state at the current point of the document is available at any one time, which clearly limits the types of processing that can be done and implies that you need to know what processing you are going to perform before reading in the XML document. If you don't think you will ever need to use XML streaming, try loading a 100 megabyte XML file into your latest application and watch what happens.

Streaming Pull Parsing vs Streaming Push Parsing
If you are creating an application that's memory limited, either because you are running on a constrained device (as in a phone) or your application is simultaneously processing several requests (as in an application server), you need to read your XML documents using a streaming model. In the past you were restricted to using the Simple API for XML (SAX). SAX was the first widely available API for reading XML in Java and provides a very low-level, efficient API that deals directly with the character data in the XML document. SAX uses a push processing model in which the SAX library reads the XML document and calls methods on your application objects as it encounters elements and text within the XML document. Although the SAX API is simple, the code application developers need to create to use SAX is not.

A "pull" parsing alternative to SAX's "push" parsing has lurked in the background for some time, but no longer: the recently ratified StAX specification now standardizes a pull parser for Java. StAX provides an alternative processing model where you call methods on the parser at your leisure and move the processing along at your command. The key difference here is that with SAX you don't have control of the application thread and can only accept invocations from the parser. In contrast, with pull parsing you own the application thread and you control when and where you call the XML parser.

This control over "when and where" leads to increased freedoms in application design, allowing you to either collect all your parsing code together or alternatively place your parsing code within the objects that understand that particular type of information.

Pull parsing has the following advantages over push parsing:

  • Parsing simple documents can now be done with simple code.
  • It's much simpler to write recursive descent parsing code for more complex documents.
  • More than one document can be read by an application at one time with just a single thread. This can be useful when part way through reading one document you need to read a second document.
  • The parser can be told to skip parts of the XML document that are not relevant to the application, which simplifies your code and may reduce processing time and memory churn.
  • You can create streaming pipelines in an object-oriented way that are efficient and simple to use.
XML Information Model
The StAX specification models an XML document as a set of events, and these events are pulled by the application and supplied in the order in which they are encountered in the XML document. The StAX specification defines the following types of events: Attribute, Characters, Comment, StartDocument, EndDocument, StartElement, EndElement, Namespace, DTD, EntityDeclaration, EntityReference, NotationDeclaration, and ProcessingInstruction.

The last five event types are only seen if your document contains a DTD. Each event has different properties associated with it depending on the type of event.

A StAX parser is an engine that reads a Unicode character stream and converts the textual data into events. Below is an example XML document:


<?xml version="1.0" encoding="UTF-8"?>
<pre1:foo xmlns:pre1="http://www.example.com/foons">
	<pre1:sometext>
			the text <![CDATA[<notallowed> as normal text]]> other text
	</pre1:sometext>
	<pre2:bar ratio="5.5" xmlns:pre2="http://www.example.com/barns"/>
</pre1:foo>

The above document would be parsed into the events shown in Figure 1.

As you can see, this small document would be converted (by default) into a stream of 14 primary events. Each colored circle in the figure is an event object. The large circles are the primary events that are seen by the application, while the small circles are secondary events that are generally accessed from some primary event.

Salient points about the event stream to note are:

  • Every StartElement event has a matching EndElement event, even for empty events like <eg/>.
  • Attributes, although events, are not (normally) seen in the event stream but are instead accessible from their StartElement event.
  • Namespaces events are not (normally) seen in the event stream but instead appear twice, first accessible from a StartElement and, second, accessible from the corresponding EndElement.
  • XML Character data may be split over more than one event and crop up where you might not expect.
While parsing an XML document the StAX parsing engine maintains a namespace stack. The namespace stack holds details of all the XML namespaces defined for the current element and its ancestors. This namespace stack is accessible though the interface javax.xml. namespace.NamespaceContext, which includes methods for looking up a namespace URI given a prefix and looking up a prefix given a namespace URI.

Cursor vs Iterator
The Story of Two APIs

When programming in Java, object creation has traditionally been seen as the enemy of performance. One of the SAX API's main advantages is that very few superfluous objects are created during the parsing of an XML document. SAX even gives the application direct access into the parser's internal character buffer in order to read text content! This lean and mean approach leads to very efficient parsing of XML. One of the design goals for StAX was for it to be at least as fast as SAX.

Very early on during the process of creating the StAX specification two alternative API styles were proposed by the expert group. One, which I'll call "cursor," followed SAX's lean and mean approach; the other, which I'll call "iterator," was a modern object-oriented API utilizing immutable objects. The expert group looked long and hard at which API style we should go with, including doing a performance analysis of the two styles. What we discovered was that we were trying to support three different end-user developers:

  1. Library and infrastructure developers: The group who creates app servers, JAXM, JAXB, JAXRpc, implementations, etc., and needs a very low-level and close-to-the-metal API with little overhead and few requirements for extensibility.
  2. J2ME developers: This group wants an XML pull parsing library that's small and simple and has a tiny footprint. They have little need for being able to extend the parser or modify the event stream.
  3. J2EE and J2SE developers: This large group generally wants a simple, efficient pull parser that naturally produces elegant bug-free code while allowing for more complex features such as stream modification and introducing new application event types.
We looked at many inventive ideas on how to create a single API that would allow us to "have our cake and eat it," but each of these ideas was rejected as they left us with a bad taste in our mouth and invariably produced a less-predictable API. In the end our desire to support these three developer types and our requirement that we be just as fast as SAX led the expert group to support both API styles.

Cursor API
The cursor API contains a central parser interface called XMLStreamReader that includes accessor methods for all the possible information you could retrieve from the XML Information model. The parser interface contains methods for accessing the document encoding, element names, attributes, namespaces, text content, processing instructions, etc. Methods are provided to allow access into the internal character buffer just as in SAX. The cursor approach is like a mirror image of SAX and provides direct access to string and character information while exposing methods with integer indexes for accessing attribute and namespace information just as in SAX. Thus it's possible to access all of the Information Model via a set of methods that return strings so object allocation is kept to a bare minimum.

Listing 1 provides some example code that uses an XMLStreamReader instance called "sr", which reads the example document listed in Figure 1. The code uses "sr" to walk over the document and retrieve the text content of the element <pre1:sometext> and the value of the ratio attribute of the element <pre2:bar>.

Listing 1 assumes the XMLStreamReader sr has just been created, i.e., StartDocument will be the first event.

Iterator API
The iterator API presents the event stream as an ordered list of immutable event objects. The StAX API defines a common base interface called XMLEvent and a subinterface for each of the event types listed in the XML information model. The Iterator API contains a central parser interface called XMLEventReader with just five methods in it, the most important being nextEvent(), which returns the next event in the stream. The interface XMLEventReader implements java.util.Iterator so it can be passed into routines that can handle the standard Java Iterator.

The common super interface XMLEvent contains methods for finding the actual event type and downcasting to the event subtypes. Listing 2 shows the equivalent code for reading our example XML document but using the XMLEventReader "er".

Clearly in a real application the three QName objects would be held in static final fields but are left inline here to aid in comparing the code examples.

What can I do with the iterator API that I can't do with the cursor API?

As the XMLEvent subclasses are immutable objects, you can place them in arrays, lists, and maps and pass them through your application as you desire, even after the parser has moved on to later events.

You can create your own subtypes of XMLEvent that are either completely new information items or extensions of existing events but with extra methods.

You can modify an event stream by adding or removing events in a way that's much simpler to code than with the cursor API.

Which API Should I Use?
This decision can only be made by the individual developer depending on the specific situation; if one API fitted all needs we would not have ended up with two.

My personal rules of thumb:

  1. If you're programming on J2ME, use the cursor API.
  2. If you're creating low-level infrastructure or libraries and you need to achieve the best possible performance, use the cursor API.
  3. If you want to create pipelines of XML processing, use the iterator API.
  4. If you want to modify the event stream, use the iterator API.
  5. If you want to future proof your app by enabling pluggable processing of the event stream, use the iterator API.
  6. If in doubt, use the iterator API.
Performance: What's the Beef?
During the expert group design discussions for StAX, the author created a prototype pull parser that provided both types of API styles, and a series of performance tests were performed using a wide range of XML test data. Due to the fact that the internal parser implementation was common for all the tests, the results showed the performance impact of using the iterator API style versus the cursor API style when accessing the parser.

The performance differences between the API styles arise mostly because of the extra objects that are created and later need to be garbage collected. The cursor and event API need to create the objects shown in Figure 2.

The cursor API does not need to create string objects for XML character data as it provides direct access to the internal character buffer. In addition, the iterator API needs to create the immutable event objects. The items colored yellow are string objects that may be cached to improve performance at the expense of some cache management complexity.

Figure 3 shows the number of bytes of XML processed per millisecond averaged over different sets of XML test files. The test was run on JDK 122 and JDK 142 for both API styles and with and without string caching enabled. The test files are loaded into memory so there is no I/O during the test runs.

Clearly there has been a massive (3-6 times) performance improvement across the board from JDK 122 to JDK 142. The iterator API without any string caching is 6.5 times faster on JDK 142.

String caching makes a big difference on JDK 122, running up to 50% faster, but only a small difference on JDK 142, showing less than a 5% improvement with perfect caching. Clearly we can now take Joshua Bloch at his word when he says that object pooling of lightweight objects is unnecessary with modern JVMs.

The overhead from using the iterator API style instead of the cursor API is around 25-30%. This sounds like a lot but remember this test program is doing 90% XML parsing and 10% application logic, whereas your typical application would probably be the other way round - 90% app logic and 10% parsing - which would drive the overhead down to about 3%, which is in the noise for most applications.

Of course your mileage may vary depending on your particular usage scenario. With the first generation StAX parser coming out soon, we'll see if this level of performance difference is also reflected in the real StAX parsers.

StAX Input Factories
How do I create an instance of XMLStreamReader or XMLEventReader?

StAX parsers that implement either of these two APIs are created by the javax.xml.stream.XMLInputFactory, which follows the standard factory pattern. When we get JAXP support you'll be able to create instances via the JAXP APIs. Create a new instance of XMLInputFactory by calling newInstance(); this method will search for a StAX implementation using the standard techniques.

The input factory has a set of configuration parameters that control the features of the parser that will be created by the factory. Once you have an instance of the factory you can override the default configuration parameter values.

Some of the more interesting configuration parameters are:

  • javax.xml.stream.isCoalescing: Defaults to false but when set to true will request a parser that coalesces all contagious text into a single character event.
  • javax.xml.stream.supportDTD: Defaults to true, but when set to false will request a parser that does not support DTDs in XML documents.
  • javax.xml.stream.resolver: Can be used to set an implementation of XMLResolver, which is used during parsing to resolve external entities.
Below is the code to create an instance of the XMLStreamReader on a File f.


        XMLInputFactory factory = XMLInputFactory.newInstance();
        XMLStreamReader sr = factory.createXMLStreamReader(new FileInputStream(f));
And to create an XMLEventReader
        XMLInputFactory factory = XMLInputFactory.newInstance();
        XMLEventReader sr = factory.createXMLEventReader(new FileInputStream(f));

If we wanted a differently featured parser, we would set some configuration parameters before creating the parser as follows:


        XMLInputFactory factory = XMLInputFactory.newInstance();
        factory.setProperty("javax.xml.stream.isCoalescing",Boolean.TRUE);
      factory.setProperty("javax.xml.stream.supportDTD",Boolean.FALSE);
        XMLEventReader sr = factory.createXMLEventReader(new FileInputStream(f));

Some of the standard configuration parameters are optional, meaning that some implementations may choose not to support the feature. You can check to see if a standard (or nonstandard) configuration parameter is supported by calling isPropertySupported() on the factory instance. Here's an example of using an optional feature:


        XMLInputFactory factory = XMLInputFactory.newInstance();
        if(factory.isPropertySupported("javax.xml.stream.isValidating")){
            factory.setProperty("javax.xml.stream.isValidating",Boolean.TRUE);
            factory.setProperty("javax.xml.stream.reporter",this);
        }
        XMLStreamReader sr = factory.createXMLStreamReader(new FileInputStream(f));

The above code instantiates a DTD validating parser if the implementation supports DTD validation.

Once you have created either an XMLStreamReader or an XMLEventReader parser you can find out what its configuration is by calling getProperty() on the parser.

One important design feature of StAX is that you must specify the properties of the parser before you create the parser and you cannot change the property value for an existing parser nor set a new data source into the parser. The rationale behind these restrictions is that we wanted to enable optimized and modular implementations.

A StAX implementation could use a special parsing engine with its own optimized byte to Unicode decoding when reading from a java.io.InputStream; alternatively it could use a different parsing engine when a java.io.Reader is the data source. Another example is the javax.xml.stream.supportDTD property that when "false" could trigger an implementation to use a simpler, faster parsing engine. If we allowed any of the configuration parameters to be modifiable after the parser was created, these types of optimization would be considerably harder to implement.

What About Writing XML?
StAX is a truly bidirectional API and can be effectively used to generate XML, either from scratch or as the result of a StAX Event pipeline. The StAX writers are intelligent in that they maintain namespace stacks and can automatically generate namespace prefixes (if you don't care what they look like). The writers can also close elements using the correct prefix and localname.

Listings 3 and 4 show some code to generate our example XML file using someText and ratio variables. If you want to use the cursor API, the code appears as in Listing 3. If you want to use the iterator API, the code should look like Listing 4.

The writers automatically escape any illegal Unicode characters such as < or & that are found in character content or attribute values.

Summary
After a lot of hard work the StAX API specification has finally seen the light of day and Java application programmers now have a standard pull parser interface for XML. The StAX API has many advantages over the SAX API for developers, including a simpler programming model and the ability to modify the event stream data and extend the information model to allow the introduction of application-specific additions. J2ME programmers now have an XML API that matches their resource-constrained environments, while library developers now have a standard API to use that fits in with their client applications' threading models and performance expectations.

Acknowledgment
I would like to thank the members of the JSR 173 expert group for an interesting and stimulating set of discussions over the past two years.

More Stories By David Stephenson

David has worked in the computing industry for over ten years working in areas of distributed systems, middleware and IT solutions. David has a wide range of experience in computing having worked for Hewlett Packard laboratories and for the HPs middleware divisions creating e-services technology. Lately David has worked in the area of web services and on both the Java and .net platforms and has been HPís contributing expert in the JCP for both JSR31 and JSR173.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


@ThingsExpo Stories
WebRTC services have already permeated corporate communications in the form of videoconferencing solutions. However, WebRTC has the potential of going beyond and catalyzing a new class of services providing more than calls with capabilities such as mass-scale real-time media broadcasting, enriched and augmented video, person-to-machine and machine-to-machine communications. In his session at @ThingsExpo, Luis Lopez, CEO of Kurento, introduced the technologies required for implementing these idea...
Buzzword alert: Microservices and IoT at a DevOps conference? What could possibly go wrong? In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, the leading expert on architecting agility for the enterprise and president of Intellyx, panelists peeled away the buzz and discuss the important architectural principles behind implementing IoT solutions for the enterprise. As remote IoT devices and sensors become increasingly intelligent, they become part of our distributed cloud enviro...
"A lot of times people will come to us and have a very diverse set of requirements or very customized need and we'll help them to implement it in a fashion that you can't just buy off of the shelf," explained Nick Rose, CTO of Enzu, in this SYS-CON.tv interview at 18th Cloud Expo, held June 7-9, 2016, at the Javits Center in New York City, NY.
The WebRTC Summit New York, to be held June 6-8, 2017, at the Javits Center in New York City, NY, announces that its Call for Papers is now open. Topics include all aspects of improving IT delivery by eliminating waste through automated business models leveraging cloud technologies. WebRTC Summit is co-located with 20th International Cloud Expo and @ThingsExpo. WebRTC is the future of browser-to-browser communications, and continues to make inroads into the traditional, difficult, plug-in web co...
In his keynote at @ThingsExpo, Chris Matthieu, Director of IoT Engineering at Citrix and co-founder and CTO of Octoblu, focused on building an IoT platform and company. He provided a behind-the-scenes look at Octoblu’s platform, business, and pivots along the way (including the Citrix acquisition of Octoblu).
For basic one-to-one voice or video calling solutions, WebRTC has proven to be a very powerful technology. Although WebRTC’s core functionality is to provide secure, real-time p2p media streaming, leveraging native platform features and server-side components brings up new communication capabilities for web and native mobile applications, allowing for advanced multi-user use cases such as video broadcasting, conferencing, and media recording.
Web Real-Time Communication APIs have quickly revolutionized what browsers are capable of. In addition to video and audio streams, we can now bi-directionally send arbitrary data over WebRTC's PeerConnection Data Channels. With the advent of Progressive Web Apps and new hardware APIs such as WebBluetooh and WebUSB, we can finally enable users to stitch together the Internet of Things directly from their browsers while communicating privately and securely in a decentralized way.
WebRTC is about the data channel as much as about video and audio conferencing. However, basically all commercial WebRTC applications have been built with a focus on audio and video. The handling of “data” has been limited to text chat and file download – all other data sharing seems to end with screensharing. What is holding back a more intensive use of peer-to-peer data? In her session at @ThingsExpo, Dr Silvia Pfeiffer, WebRTC Applications Team Lead at National ICT Australia, looked at differ...
The security needs of IoT environments require a strong, proven approach to maintain security, trust and privacy in their ecosystem. Assurance and protection of device identity, secure data encryption and authentication are the key security challenges organizations are trying to address when integrating IoT devices. This holds true for IoT applications in a wide range of industries, for example, healthcare, consumer devices, and manufacturing. In his session at @ThingsExpo, Lancen LaChance, vic...
With all the incredible momentum behind the Internet of Things (IoT) industry, it is easy to forget that not a single CEO wakes up and wonders if “my IoT is broken.” What they wonder is if they are making the right decisions to do all they can to increase revenue, decrease costs, and improve customer experience – effectively the same challenges they have always had in growing their business. The exciting thing about the IoT industry is now these decisions can be better, faster, and smarter. Now ...
Fact is, enterprises have significant legacy voice infrastructure that’s costly to replace with pure IP solutions. How can we bring this analog infrastructure into our shiny new cloud applications? There are proven methods to bind both legacy voice applications and traditional PSTN audio into cloud-based applications and services at a carrier scale. Some of the most successful implementations leverage WebRTC, WebSockets, SIP and other open source technologies. In his session at @ThingsExpo, Da...
Who are you? How do you introduce yourself? Do you use a name, or do you greet a friend by the last four digits of his social security number? Assuming you don’t, why are we content to associate our identity with 10 random digits assigned by our phone company? Identity is an issue that affects everyone, but as individuals we don’t spend a lot of time thinking about it. In his session at @ThingsExpo, Ben Klang, Founder & President of Mojo Lingo, discussed the impact of technology on identity. Sho...
A critical component of any IoT project is what to do with all the data being generated. This data needs to be captured, processed, structured, and stored in a way to facilitate different kinds of queries. Traditional data warehouse and analytical systems are mature technologies that can be used to handle certain kinds of queries, but they are not always well suited to many problems, particularly when there is a need for real-time insights.
You think you know what’s in your data. But do you? Most organizations are now aware of the business intelligence represented by their data. Data science stands to take this to a level you never thought of – literally. The techniques of data science, when used with the capabilities of Big Data technologies, can make connections you had not yet imagined, helping you discover new insights and ask new questions of your data. In his session at @ThingsExpo, Sarbjit Sarkaria, data science team lead ...
WebRTC has had a real tough three or four years, and so have those working with it. Only a few short years ago, the development world were excited about WebRTC and proclaiming how awesome it was. You might have played with the technology a couple of years ago, only to find the extra infrastructure requirements were painful to implement and poorly documented. This probably left a bitter taste in your mouth, especially when things went wrong.
WebRTC is bringing significant change to the communications landscape that will bridge the worlds of web and telephony, making the Internet the new standard for communications. Cloud9 took the road less traveled and used WebRTC to create a downloadable enterprise-grade communications platform that is changing the communication dynamic in the financial sector. In his session at @ThingsExpo, Leo Papadopoulos, CTO of Cloud9, discussed the importance of WebRTC and how it enables companies to focus o...
Providing secure, mobile access to sensitive data sets is a critical element in realizing the full potential of cloud computing. However, large data caches remain inaccessible to edge devices for reasons of security, size, format or limited viewing capabilities. Medical imaging, computer aided design and seismic interpretation are just a few examples of industries facing this challenge. Rather than fighting for incremental gains by pulling these datasets to edge devices, we need to embrace the i...
Web Real-Time Communication APIs have quickly revolutionized what browsers are capable of. In addition to video and audio streams, we can now bi-directionally send arbitrary data over WebRTC's PeerConnection Data Channels. With the advent of Progressive Web Apps and new hardware APIs such as WebBluetooh and WebUSB, we can finally enable users to stitch together the Internet of Things directly from their browsers while communicating privately and securely in a decentralized way.
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo 2016 in New York. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place June 6-8, 2017, at the Javits Center in New York City, New York, is co-located with 20th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry p...
In his General Session at 17th Cloud Expo, Bruce Swann, Senior Product Marketing Manager for Adobe Campaign, explored the key ingredients of cross-channel marketing in a digital world. Learn how the Adobe Marketing Cloud can help marketers embrace opportunities for personalized, relevant and real-time customer engagement across offline (direct mail, point of sale, call center) and digital (email, website, SMS, mobile apps, social networks, connected objects).