Welcome!

Java IoT Authors: Elizabeth White, Pat Romanski, Harry Trott, Philippe Abdoulaye, Scott Sobhani

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
In his keynote at 18th Cloud Expo, Andrew Keys, Co-Founder of ConsenSys Enterprise, provided an overview of the evolution of the Internet and the Database and the future of their combination – the Blockchain. Andrew Keys is Co-Founder of ConsenSys Enterprise. He comes to ConsenSys Enterprise with capital markets, technology and entrepreneurial experience. Previously, he worked for UBS investment bank in equities analysis. Later, he was responsible for the creation and distribution of life sett...
There are several IoTs: the Industrial Internet, Consumer Wearables, Wearables and Healthcare, Supply Chains, and the movement toward Smart Grids, Cities, Regions, and Nations. There are competing communications standards every step of the way, a bewildering array of sensors and devices, and an entire world of competing data analytics platforms. To some this appears to be chaos. In this power panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, Bradley Holt, Developer Advocate a...
Cognitive Computing is becoming the foundation for a new generation of solutions that have the potential to transform business. Unlike traditional approaches to building solutions, a cognitive computing approach allows the data to help determine the way applications are designed. This contrasts with conventional software development that begins with defining logic based on the current way a business operates. In her session at 18th Cloud Expo, Judith S. Hurwitz, President and CEO of Hurwitz & ...
In his general session at 18th Cloud Expo, Lee Atchison, Principal Cloud Architect and Advocate at New Relic, discussed cloud as a ‘better data center’ and how it adds new capacity (faster) and improves application availability (redundancy). The cloud is a ‘Dynamic Tool for Dynamic Apps’ and resource allocation is an integral part of your application architecture, so use only the resources you need and allocate /de-allocate resources on the fly.
A strange thing is happening along the way to the Internet of Things, namely far too many devices to work with and manage. It has become clear that we'll need much higher efficiency user experiences that can allow us to more easily and scalably work with the thousands of devices that will soon be in each of our lives. Enter the conversational interface revolution, combining bots we can literally talk with, gesture to, and even direct with our thoughts, with embedded artificial intelligence, wh...
19th Cloud Expo, taking place November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Meanwhile, 94% of enterpri...
SYS-CON Events announced today that Bsquare has been named “Silver Sponsor” of SYS-CON's @ThingsExpo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. For more than two decades, Bsquare has helped its customers extract business value from a broad array of physical assets by making them intelligent, connecting them, and using the data they generate to optimize business processes.
Internet of @ThingsExpo, taking place November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 19th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal and enterprise IT since the creation of the Worldwide Web more than 20 years ago. All major researchers estimate there will be tens of billions devices - comp...
There is little doubt that Big Data solutions will have an increasing role in the Enterprise IT mainstream over time. Big Data at Cloud Expo - to be held November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA - has announced its Call for Papers is open. Cloud computing is being adopted in one form or another by 94% of enterprises today. Tens of billions of new devices are being connected to The Internet of Things. And Big Data is driving this bus. An exponential increase is...
Machine Learning helps make complex systems more efficient. By applying advanced Machine Learning techniques such as Cognitive Fingerprinting, wind project operators can utilize these tools to learn from collected data, detect regular patterns, and optimize their own operations. In his session at 18th Cloud Expo, Stuart Gillen, Director of Business Development at SparkCognition, discussed how research has demonstrated the value of Machine Learning in delivering next generation analytics to imp...
The 19th International Cloud Expo has announced that its Call for Papers is open. Cloud Expo, to be held November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, Big Data, Internet of Things, DevOps, Digital Transformation, Microservices and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding business opportuni...
Cloud computing is being adopted in one form or another by 94% of enterprises today. Tens of billions of new devices are being connected to The Internet of Things. And Big Data is driving this bus. An exponential increase is expected in the amount of information being processed, managed, analyzed, and acted upon by enterprise IT. This amazing is not part of some distant future - it is happening today. One report shows a 650% increase in enterprise data by 2020. Other estimates are even higher....
The cloud market growth today is largely in public clouds. While there is a lot of spend in IT departments in virtualization, these aren’t yet translating into a true “cloud” experience within the enterprise. What is stopping the growth of the “private cloud” market? In his general session at 18th Cloud Expo, Nara Rajagopalan, CEO of Accelerite, explored the challenges in deploying, managing, and getting adoption for a private cloud within an enterprise. What are the key differences between wh...
Internet of @ThingsExpo, taking place November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with the 19th International Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world and ThingsExpo Silicon Valley Call for Papers is now open.
It is one thing to build single industrial IoT applications, but what will it take to build the Smart Cities and truly society changing applications of the future? The technology won’t be the problem, it will be the number of parties that need to work together and be aligned in their motivation to succeed. In his Day 2 Keynote at @ThingsExpo, Henrik Kenani Dahlgren, Portfolio Marketing Manager at Ericsson, discussed how to plan to cooperate, partner, and form lasting all-star teams to change t...
Connected devices and the industrial internet are growing exponentially every year with Cisco expecting 50 billion devices to be in operation by 2020. In this period of growth, location-based insights are becoming invaluable to many businesses as they adopt new connected technologies. Knowing when and where these devices connect from is critical for a number of scenarios in supply chain management, disaster management, emergency response, M2M, location marketing and more. In his session at @Th...
SYS-CON Events announced today that ReadyTalk, a leading provider of online conferencing and webinar services, has been named Vendor Presentation Sponsor at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. ReadyTalk delivers audio and web conferencing services that inspire collaboration and enable the Future of Work for today’s increasingly digital and mobile workforce. By combining intuitive, innovative tec...
Amazon has gradually rolled out parts of its IoT offerings, but these are just the tip of the iceberg. In addition to optimizing their backend AWS offerings, Amazon is laying the ground work to be a major force in IoT - especially in the connected home and office. In his session at @ThingsExpo, Chris Kocher, founder and managing director of Grey Heron, explained how Amazon is extending its reach to become a major force in IoT by building on its dominant cloud IoT platform, its Dash Button strat...
industrial company for a multi-year contract initially valued at over $4.0 million. In addition to DataV software, Bsquare will also provide comprehensive systems integration, support and maintenance services. DataV leverages advanced data analytics, predictive reasoning, data-driven diagnostics, and automated orchestration of remediation actions in order to improve asset uptime while reducing service and warranty costs.
Vidyo, Inc., has joined the Alliance for Open Media. The Alliance for Open Media is a non-profit organization working to define and develop media technologies that address the need for an open standard for video compression and delivery over the web. As a member of the Alliance, Vidyo will collaborate with industry leaders in pursuit of an open and royalty-free AOMedia Video codec, AV1. Vidyo’s contributions to the organization will bring to bear its long history of expertise in codec technolo...