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

(for older news, check out full News page)

Introduction

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

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 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:

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: