Package net.sf.saxon.evpull

This package provides classes that implement a StAX-like pull pipeline in which a recieving component makes calls on a provider component to supply information from the XML stream one event at a time.

See: Description

Package net.sf.saxon.evpull Description

This package provides classes that implement a StAX-like pull pipeline in which a recieving component makes calls on a provider component to supply information from the XML stream one event at a time. The object that is supplied in response to these calls is a PullEvent, and a component that can be invoked to deliver a sequence of these objects is a EventIterator.

An EventIterator is itself a PullEvent, so an event provider may return a sequence of events in response to a single call by returning an iterator. A sequence of events containing no iterators is referred to as a flat sequence, and any sequence of events can be converted to a flat sequence by inserting an EventStackIterator into the pipeline.

Pull processing is not used extensively in Saxon, and is generally not used at all unless explicitly requested. It can be requested, for example, by supplying a PullEventSource object to an interface that expects an XML document to be supplied as a JAXP Source. It is also used in XQJ when methods such as XQDataFactory.createItemFromDocument(java.lang.String, java.lang.String, javax.xml.xquery.XQItemType) are used to construct an XML document from a supplied XMLStreamReader. In such cases Saxon uses the class StaxToEventBridge to convert StAX events to its own PullEvent events. Conversion in the opposite direction uses the class EventToStaxBridge.

It is possible to request pull-mode evaluation of XQuery code using the method XQueryExpression.iterateEvents(net.sf.saxon.Controller, net.sf.saxon.query.DynamicQueryContext). This causes any document and element node constructors to be evaluated in pull mode, returning events representing start/end document/element rather than actually constructing the result tree in memory. The relevant expressions in the expression tree provide an iterateEvents() method to support this mode of execution.

A sequence of events is said to be composed if it consists entirely of items (that is, a node is passed as a single event, rather than by walking the tree); it is said to be decomposed if if consists entirely of StAX-like events. In general, the classes in this package handle sequences that mix both styles. A fully-composed sequence, however, is normally handled using the SequenceIterator interface rather than by the classes in this package. The SequenceComposer returns a full composed event stream from a decomposed or mixed stream, constructing tree fragments when necessary to achieve this; the Decomposer does the inverse, walking any tree fragments to deliver the corresponding start-element and end-element events.

The class EventIteratorOverSequence converts a stream of items obtained from a SequenceIterator into a composed stream of PullEvent events.

The class EventIteratorToReceiver reads a sequence of events from a pull pipeline and outputs the same sequence of events to a push pipeline using the Receiver interface.

The package net.sf.saxon.pull represents an earlier attempt at pull-mode processing in Saxon. It is retained because it provides some capabilities not yet present in this package.


Michael H. Kay
Saxonica Limited
30 July 2010

Copyright (c) 2004-2014 Saxonica Limited. All rights reserved.