Document Information


Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  Java Servlet Technology

5.  JavaServer Pages Technology

6.  JavaServer Pages Documents

7.  JavaServer Pages Standard Tag Library

8.  Custom Tags in JSP Pages

9.  Scripting in JSP Pages

10.  JavaServer Faces Technology

11.  Using JavaServer Faces Technology in JSP Pages

12.  Developing with JavaServer Faces Technology

13.  Creating Custom UI Components

14.  Configuring JavaServer Faces Applications

15.  Internationalizing and Localizing Web Applications

Part III Web Services

16.  Building Web Services with JAX-WS

17.  Binding between XML Schema and Java Classes

18.  Streaming API for XML


Cursor API

Iterator API

Iterator Event Types

Example of Event Mapping

Choosing between Cursor and Iterator APIs

Development Goals

Comparing Cursor and Iterator APIs

Using StAX

StAX Factory Classes

XMLInputFactory Class

XMLOutputFactory Class

XMLEventFactory Class

Resources, Namespaces, and Errors

Resource Resolution

Attributes and Namespaces

Error Reporting and Exception Handling

Reading XML Streams

Using XMLStreamReader

Using XMLEventReader

Writing XML Streams

Using XMLStreamWriter

Using XMLEventWriter

Sun's Streaming XML Parser Implementation

Reporting CDATA Events

Streaming XML Parser Factories Implementation

Example Code

Example Code Organization

Example XML Document

Cursor Example

Stepping through Events

Returning String Representations

Building and Running the Cursor Example Using NetBeans IDE

Building and Running the Cursor Example Using Ant

Cursor-to-Event Example

Instantiating an XMLEventAllocator

Creating an Event Iterator

Creating the Allocator Method

Building and Running the Cursor-to-Event Example Using NetBeans IDE

Building and Running the Cursor-to-Event Example Using Ant

Event Example

Creating an Input Factory

Creating an Event Reader

Creating an Event Iterator

Getting the Event Stream

Returning the Output

Building and Running the Event Example Using NetBeans IDE

Building and Running the Event Example Using Ant

Filter Example

Implementing the StreamFilter Class

Creating an Input Factory

Creating the Filter

Capturing the Event Stream

Filtering the Stream

Returning the Output

Building and Running the Filter Example Using NetBeans IDE

Building and Running the Filter Example Using Ant

Read-and-Write Example

Creating an Event Producer/Consumer

Creating an Iterator

Creating a Writer

Returning the Output

Building and Running the Read-and-Write Example Using NetBeans IDE

Building and Running the Read-and-Write Example Using Ant

Writer Example

Creating the Output Factory

Creating a Stream Writer

Writing the Stream

Returning the Output

Building and Running the Writer Example Using NetBeans IDE

Building and Running the Writer Example Using Ant

Further Information about StAX

19.  SOAP with Attachments API for Java

Part IV Enterprise Beans

20.  Enterprise Beans

21.  Getting Started with Enterprise Beans

22.  Session Bean Examples

23.  A Message-Driven Bean Example

Part V Persistence

24.  Introduction to the Java Persistence API

25.  Persistence in the Web Tier

26.  Persistence in the EJB Tier

27.  The Java Persistence Query Language

Part VI Services

28.  Introduction to Security in the Java EE Platform

29.  Securing Java EE Applications

30.  Securing Web Applications

31.  The Java Message Service API

32.  Java EE Examples Using the JMS API

33.  Transactions

34.  Resource Connections

35.  Connector Architecture

Part VII Case Studies

36.  The Coffee Break Application

37.  The Duke's Bank Application

Part VIII Appendixes

A.  Java Encoding Schemes

B.  About the Authors



Why StAX?

The StAX project was spearheaded by BEA with support from Sun Microsystems, and the JSR 173 specification passed the Java Community Process final approval ballot in March, 2004 ( The primary goal of the StAX API is to give “parsing control to the programmer by exposing a simple iterator based API. This allows the programmer to ask for the next event (pull the event) and allows state to be stored in procedural fashion.” StAX was created to address limitations in the two most prevalent parsing APIs, SAX and DOM.

Streaming versus DOM

Generally speaking, there are two programming models for working with XML infosets: streaming and the document object model (DOM).

The DOM model involves creating in-memory objects representing an entire document tree and the complete infoset state for an XML document. Once in memory, DOM trees can be navigated freely and parsed arbitrarily, and as such provide maximum flexibility for developers. However, the cost of this flexibility is a potentially large memory footprint and significant processor requirements, because the entire representation of the document must be held in memory as objects for the duration of the document processing. This may not be an issue when working with small documents, but memory and processor requirements can escalate quickly with document size.

Streaming refers to a programming model in which XML infosets are transmitted and parsed serially at application runtime, often in real time, and often from dynamic sources whose contents are not precisely known beforehand. Moreover, stream-based parsers can start generating output immediately, and infoset elements can be discarded and garbage collected immediately after they are used. While providing a smaller memory footprint, reduced processor requirements, and higher performance in certain situations, the primary trade-off with stream processing is that you can only see the infoset state at one location at a time in the document. You are essentially limited to the “cardboard tube” view of a document, the implication being that you need to know what processing you want to do before reading the XML document.

Streaming models for XML processing are particularly useful when your application has strict memory limitations, as with a cell phone running J2ME, or when your application needs to simultaneously process several requests, as with an application server. In fact, it can be argued that the majority of XML business logic can benefit from stream processing, and does not require the in-memory maintenance of entire DOM trees.

Pull Parsing versus Push Parsing

Streaming pull parsing refers to a programming model in which a client application calls methods on an XML parsing library when it needs to interact with an XML infoset; that is, the client only gets (pulls) XML data when it explicitly asks for it.

Streaming push parsing refers to a programming model in which an XML parser sends (pushes) XML data to the client as the parser encounters elements in an XML infoset; that is, the parser sends the data whether or not the client is ready to use it at that time.

Pull parsing provides several advantages over push parsing when working with XML streams:

  • With pull parsing, the client controls the application thread, and can call methods on the parser when needed. By contrast, with push processing, the parser controls the application thread, and the client can only accept invocations from the parser.

  • Pull parsing libraries can be much smaller and the client code to interact with those libraries much simpler than with push libraries, even for more complex documents.

  • Pull clients can read multiple documents at one time with a single thread.

  • A StAX pull parser can filter XML documents such that elements unnecessary to the client can be ignored, and it can support XML views of non-XML data.

StAX Use Cases

The StAX specification defines a number of use cases for the API:

  • Data binding

    • Unmarshalling an XML document

    • Marshalling an XML document

    • Parallel document processing

    • Wireless communication

  • SOAP message processing

    • Parsing simple predictable structures

    • Parsing graph representations with forward references

    • Parsing WSDL

  • Virtual data sources

    • Viewing as XML data stored in databases

    • Viewing data in Java objects created by XML data binding

    • Navigating a DOM tree as a stream of events

  • Parsing specific XML vocabularies

  • Pipelined XML processing

A complete discussion of all these use cases is beyond the scope of this chapter. Please refer to the StAX specification for further information.

Comparing StAX to Other JAXP APIs

As an API in the JAXP family, StAX can be compared, among other APIs, to SAX, TrAX, and JDOM. Of the latter two, StAX is not as powerful or flexible as TrAX or JDOM, but neither does it require as much memory or processor load to be useful, and StAX can, in many cases, outperform the DOM-based APIs. The same arguments outlined above, weighing the cost/benefits of the DOM model versus the streaming model, apply here.

With this in mind, the closest comparisons can be made between StAX and SAX, and it is here that StAX offers features that are beneficial in many cases; some of these include:

  • StAX-enabled clients are generally easier to code than SAX clients. While it can be argued that SAX parsers are marginally easier to write, StAX parser code can be smaller and the code necessary for the client to interact with the parser simpler.

  • StAX is a bidirectional API, meaning that it can both read and write XML documents. SAX is read only, so another API is needed if you want to write XML documents.

  • SAX is a push API, whereas StAX is pull. The trade-offs between push and pull APIs outlined above apply here.

Table 18-1 summarizes the comparative features of StAX, SAX, DOM, and TrAX (table adapted from “Does StAX Belong in Your XML Toolbox?” at by Jeff Ryan).

Table 18-1 XML Parser API Feature Summary






API Type

Pull, streaming

Push, streaming

In memory tree


Ease of Use





XPath Capability

Not supported

Not supported



CPU and Memory Efficiency





Forward Only



Not supported

Not supported

Read XML





Write XML


Not supported



Create, Read, Update, Delete

Not supported

Not supported


Not supported