Skip to end of metadata
Go to start of metadata

StaxMate - the perfect companion for your Stax processor!

 

NOTE! Home Page moved to GitHub: documentation at FasterXML StaxMate Wiki.

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

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

News

  • 28-Feb-2013: Fully moved to GitHub, with 2.2.0 release.
  • 20-Nov-2010: Released 2.0.1 patch release, see Download page
  • 17-Jun-2009: added links to FasterXML.com , regarding commercial support.
  • 12-Mar-2009: Released 2.0.0: upgrade to using Stax2 v3.0 (~= Woodstox 4.0), access to Typed Access API
  • 06-Dec-2008: 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)

Introduction

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 javax.xml.stream 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 also strive for correctness, there are additional safeguards that StaxMate uses to make it very hard to produce non-well-formed content. This is possible because of higher level of abstraction at StaxMate API level.

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.

Licensing

StaxMate is licensed under BSD license. Share and Enjoy!

Dependencies / Requirements

To use StaxMate, you need:

  • Stax API jar
  • A Stax implementation: recommended one is Woodstox (version 4.0.x for StaxMate 2.x; 3.2 for earlier StaxMate versions)
    • or, alternatively, Aalto or SJSXP (both usable since StaxMate 1.2)
  • Stax2 extension API: either a separate jar, or as part of extended StaxMate jar ("staxmate-with-stax2")

Where can I find sources and binaries?

See GitHub StaxMate project.

Community

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

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

Also, 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.

Help with StaxMate

There exists two major types of support for StaxMate:

  • Volunteer support:
    • StaxMate authors and users can be most easily reached via mailing lists: feel free to join, volume is fairly low.
  • Professional support:
    • FasterXML offers professional support service for StaxMate as well as many other XML use cases and related services: this makes sense for tight deadlines and when needing to expand beyond in-house expertise.