# 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`.

Next