StaxMate basics, reader side
Before embarking on journey to build a simple web application (we'll get there), it is necessary to explain the costructs we will use, so that the example itself only needs comments regarding actual functionality. So, here are typical usage patterns on reader side.
1. Getting started
First things first: since StaxMate is built on top of Stax API, you need to create an XMLStreamReader, properly configured. StaxMate is quite adaptive, and Stax defaults are usually sufficient so usually you can just use something like:
XMLInputFactory f = XMLInputFactory.newInstance(); // remember to reuse
XMLStreamReader sr = f.createStreamReader(new FileInputStream("mydoc.xml"));
2. Start iterating
All access to the input document is handled using cursors. Cursors come in two basic types: hierarchic cursors (also known as "child cursor", as they traverse immediate children) and flattening cursors (or descendant cursors, as they traverse all descendants, children, grand-children and so on). In addition to the traversal type, the second important property of a cursor is type of events it filters out: SMFilter interface can be implemented to specify which underlying events to filter out and which not. Most of the time default ones (element-only filter, text filter, mixed filter) are good enough, and there are convenience method for constructing other types you are likely to need.
At this point, we need to obtain the first cursor; and usually it is a hierarchic element-only cursor, since we usually do not care about possible comments or processing instructions outside of the root element, but do we want to handle things hierarchically (level by level). So, most often you will get the root cursor by doing:
SMInputCursor rootCrsr = SMInputFactory.rootElementCursor(sr);
So what does cursor point to having been created? Nothing, as of yet: similar to JDBC result set cursors, StaxMate cursors need to be advanced to point to the next applicable event (if any). They will return type of the event, if there was one (for root element there will always be a root element, for any well-formed document), or null otherwise. Return type is a type-safe enumeration (StaxMate requires Java 5 aka 1.5). So, typically you will see something like this:
rootCrsr.getNext(); // for element cursor, return type will be SM Event.START_ELEMENT
after which you can check that the element is what you think it should be (and/or do other validation):
assert(rootCrsr.getQName(), new QName("root"));
and perhaps access an attribute or two:
String id = rootCrsr.getAttrValue("id"); // convenience method for attrs without namespace
and when you are ready to inspect the sub-tree starting from root, you do:
SMCursor childCrsr = rootCrsr.childElementCursor();
3. Collect text
One common thing to do is accessing textual content of a leaf element. Although Stax XMLStreamReader does have 'getElementText' method, it is bit tricky to use, and will not work for mixed content (if there are child elements). Further, you still need to skip the end element after getting text.
With StaxMate, you just do (assuming crsr points to a SMEvent.START_ELEMENT):
String value = crsr.collectDescendantText()
and you get all text element contains, recursively if necessary, all non-text content being stripped out.
4. Share (and enjoy!) the cursor
One of most mundane chores with Stax is the book-keeping with end tag balancing, and especially so if you want to modularize your code. If so, the called code has to be careful to match and skip all end tags for start tags it has handled. This is tedious and error-prone; and with enough code can make code harder to read than necessary. It also makes it very easy for called code to wreak havoc, by over-iterating over events it is not supposed to read. This because there is just one XMLStreamReader.
Here StaxMate can help, not only because you never need to deal with end tags directly (when underlying stream hits an end tag, cursor knows it can't advance, and this is signalled by returning null -- plus, it is still safe to call getNext() again; you will just get another null), but also because all cursors are scope such that they can only traverse over events within scope. That is, a child or descendant cursor constructed for cursor point to, say, start tag <tag> can only traverse over events up to the </tag> that matches the start tag. And finally, even if the child cursor does NOT traverse through all the events (called code gets bored, or found what it was looking for), parent cursor knows how to automatically skip the "uninteresting" events in-between. That is, cursors are kept in-sync.
So, quite often you will see method calls like:
handleHeadSection(crsr.childElementCursor()); crsr.getNext(); assertElement(crsr, "body"); handleBodySection(crsr.childElementCursor()); crsr.getNext(); assertElement(crsr, "trailer"); handleTrailer(crsr.childElementCursor()); // ...
in which different handlers take care of different parts of the document, and without having to keep track of anything beyond its immediate needs.
5. The limitation
So what's the catch? Can I now freely create and traverse cursors, even if only in forward direction? Yes and no: there is one major fundamental limitation. All access will still have to be done in document order. So that:
- Parent element information has to always be completely accessed before child element information (that is, you can not access parent information [except if tracking is enabled -- but this uses different methods] after a cursor has advanced to a child element). Parent information includes attribute information, so that it is not possible to access attribute values of a parent, after advancing a cursor to a child element.
- Siblings have to be accessed in the document order (although you can use tracking here, too). This is seldom a problem, since cursors only advance in one direction.
Similar limitations apply to the output side as well, although there too there are ways around ordering (specifically it is possible to use feature called "buffering" to delay outputting of an element, allowing limited out-of-order addition of output: this is most often used to add attributes after children are added).
How big is this limitation? It is no worse than the basic Stax API limitations, but it may be easier to ignore. However, if you understand the basic operation, and keep in mind the implied (but strongly enforced!) ordering restriction, you should be able use cursors quite conveniently and efficiently.
6. Advanced Features
In addition to the basic hierarchic iteration, and convenient access to data, there are other more advanced features StaxMate input side offers. Since this is a tutorial article, these will not be explained in detail, but here is a short list of additional advanced features you can learn from the source code (or possibly later tutorials):
- Access to simple positional indexes. StaxMate keeps track of node and element order number for cursor, and offers access to it. So, for example, if you need different handling for the first <li> child element, and following ones, you can do this by checking 'crsr.getElementCount()'.
- Customized event filtering. If you are only interested in, say, comments in the document, you can easily implement SMFilter, or even just construct SimpleFilter with proper (Stax API - based) event flags.
- Tracking: simply put, this allows retaining of parts of the input structure even after cursors have been moved past that content. Tracking can be dynamically enabled on sub-trees: and when enabled, a temporary tree-like (but very light-weight) structure is maintained. This may be useful for simple state-tracking
- Customize (override) all object creation methods, to store additional information in cursor objects, or tracking info objects. All of the factory methods are designed to be overloadable, so if you need a light-weight additional storage for storing state information, you can just sub-class objects you need, and the framework should be able to use your sub-classes instead of the default ones.
