Pull processing in Java

The internal mechanisms and API for pull processing have been substantially rewritten in this release.

There is a new method iterateEvents() on the Expression class, which evaluates the expression and returns its result as a sequence of PullEvent objects. A PullEvent can be an Item (that is, a NodeInfo or AtomicValue). It can also be a StartElement, EndElement, StartDocument, or EndDocument event. Within the content of a document or element, the child nodes can be represented either as complete nodes (including element nodes, and potentially even document nodes, in which case the document wrapper should be ignored) or as nested event sequences using further StartElement and EndElement events.

An EventIterator is also a PullEvent, so a stream of events can contain nested streams. If you want to process the events without having to handle this nesting, you can flatten the sequence by calling the static method EventStackIterator.flatten().

To serialize the results of a query, there is a static method EventIteratorToReceiver.copy() which reads the events from a pull pipeline (an EventIterator), and pushes them to a push pipeline (a Receiver). However, if you are serializing the results then it probably makes sense in most cases to evaluate the query in push mode to start with.

A sequence in which all the PullEvents are Item objects is called a composed sequence. A sequence in which all document and element nodes are split into their constituent events is called a decomposed sequence. You can turn any sequence of PullEvents into a fully composed sequence by wrapping it in a SequenceComposer. This will physically construct any document or element nodes that were represented in the sequence in decomposed form. Similarly, you can turn any sequence into a fully decomposed sequence by wrapping it in a Decomposer.