StaxMate - the perfect companion for your Stax processor!
(or: "StaxMate: Automatic Shifting for Streaming XML Processing")
- 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)
StaxMate is a light-weight framework that aims to offer:
for XML processing.
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.
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)
- 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:
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 in the project is via StaxMate mailing lists.
CowTalk Blog features StaxMate as well, and often has other relevant content.
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.
Interesting Related Things
- https://stax-utils.dev.java.net/ has lots of utilities for integrating StAX with SAX components, amongst other things.