Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

StaxMate - the perfect companion for your Stax processor!

(or: "StaxMate: Automatic Shifting for Streaming XML Processing")

For the impatient, you can quickly proceed to Download page; or browse Documentation (perhaps Tutorial if you are new here?).


  • 06-Dec-2007: Released 1.3.1 patch release, couple of critical fixes
  • 03-Sep-2008: Released 1.3, with major internal cleanup (including serious addition of JavaDocs); extended functionality, more convenience methods for constructing factories, cursors, output elements and more support for Typed Access API
  • 01-Aug-2008: Released 1.2 maintenance version, which now fully support SJSXP (JDK 1.6 default stax impl), as well as Aalto
  • 29-Nov-2007: Released 1.1, significant internal refactoring (simpler and more robust synchronization of cursors), not many external changes. Tested with Woodstox 3.2.3.
  • 02-May-2007: Released 1.0! (pop up the champagne!)

(for older news, check out full News page)


StaxMate is a light-weight framework that aims to offer:

  • Efficiency
  • Convenience
  • Correctness

for XML processing.

Efficiency is achieved by starting with high performance Stax (JSR-173) XML processors such as Woodstox , Aalto and SJSXP , and keeping additional overhead to minimum.

While efficiency is something StaxMate works hard to retain from underlying components, Convenience is the main thing that StaxMate adds: using "raw" Stax interface (check out for details) is not very convenient way to get things done. StaxMate changes this, and makes XML processing much simpler, more natural; both when reading and writing XML. More on this below.

And finally, StaxMate does not sacrifice correctness to attain the primary goals: it strives to expose right methods for getting well-formed and valid XML to be produced; and accessed in ways that are compatible with the intent of relevant XML standards such as XML Namepsaces. Although Stax processors in general also strive for correctness, there are additional safeguards that StaxMate uses, to make it very hard to produce non-well-formed content.

Brief overview of API

For full overview of functionality and usage, please refer to Documentation page.
But here is a highly condensed executive summary of StaxMate API:

  • Cursors (SMInputCursor) are the main abstraction *for reading XML content
  • Output objects (like SMOutputElement) are the main abstraction for writing XML content

Cursors and output objects encapsulate scoping information to make reading and writing nested XML content more natural than when using basic Stax XMLStreamReader and XMLStreamWriter. Skipping sub-trees is natural; and passing cursors and output objects is safer than passing stream readers/writers. Each object has clear scope for its read/write operations, and you need not worry about closing or skipping sub-trees: this is handled as you would expect. One way to think of this is that StaxMate offers automatic shifting over manual shifting that basic Stax API offers.

Beyond more convenient traversal and scoping, StaxMate also offers convenient access to "data typed" XML reading and writing, without having to use XML Schema or code generation. If you know certain element or attribute values to contain typed content (numbers, boolean values, QNames, lists of simple types), you can read and write them as if XML document itself was fully type-aware. Part of this is implemented by using Stax2 API that some Stax processors implement; and the rest by emulating this API for other processors.

The design ideas and main features of both are listed, respectively, on StaxMateIterators and StaxMateOutputters pages.


StaxMate is licensed under BSD license. Share and Enjoy!

Dependencies / Requirements

To use StaxMate, you need:

  • Stax API jar
  • A Stax implementation (like Woodstox , recommended version 3.2.x (for StaxMate 1.x); or SJSXP (starting with StaxMate 1.2)).
  • Stax2 extension API: either a separate jar, or as part of extended StaxMate jar ("staxmate-with-stax2")

Links to all of above are included on Download page.

Where can I find sources and binaries?

You can find binaries (jars) and sources (tar, zip) on the Download page.

Also, StaxMate sources are stored in Codehaus Subversion; you can access them using anonymous read-only access:

svn co

and registered developers can access it similarly, but adding "--username" (and "--password") switch to allow changes to be committed back in.


Currently the best to reach people involved is via StaxMate mailing lists.

Another useful related mailing list is the "official" StAX mailing list , which is used for more general discussion regarding Stax specification, and issues common to implementations.

CowTalk Blog features StaxMate as well, and often has other relevant content.

And finally, due to its background, Woodstox mailing lists is another place where you can also discuss StaxMate issues, especially if these relate to the underlying Stax parser implementation.

Interesting Related Things

  • No labels