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

Interface Summary

Interface	Description
EventIterator	An iterator over a sequence of events
EventMappingFunction	EventMappingFunction is an interface that must be satisfied by an object passed to an EventMappingIterator.
PullEvent	A PullEvent is one of the following: An item (that is, a node or an atomic value) A startElement, endElement, startDocument, or endDocument event An EventIterator, representing a sequence of PullEvents

Class Summary

Class	Description
BlockEventIterator	Iterate over the instructions in a Block, concatenating the result of each instruction into a single combined sequence.
BracketedDocumentIterator	The class is an EventIterator that handles the events arising from a document node constructor: that is, the start/end event pair for the document node, bracketing a sequence of events for the content of the document.
BracketedElementIterator	The class is an EventIterator that handles the events arising from an element constructor: that is, the start/end event pair for the element node, bracketing a sequence of events for the content of the element.
ComplexContentProcessor	The ComplexContentProcessor is an EventIterator that deals with the events occurring between a startElement and endElement (or startDocument and endDocument) according to the XSLT/XQuery rules for constructing complex content.
Decomposer	This class takes a sequence of pull events and turns it into fully-decomposed form, that is, it takes and document and element nodes in the sequence and turns them into a subsequence consisting of a start element|document event, a content sequence, and an end element|document event, recursively.
EmptyEventIterator	This class is an EventIterator over an empty sequence.
EndDocumentEvent	Pull event representing the end of a document
EndElementEvent	Pull event representing the end of an element node
EventAnnotationStripper	This class is an EventIterator that filters a stream of pull events setting the type annotation on element nodes to xs:untyped and on attribute nodes to xs:untypedAtomic
EventIteratorOverSequence	This class maps a SequenceIterator to an EventIterator, by simply returning the items in the sequence as PullEvents.
EventIteratorToReceiver	Class to read pull events from an EventIterator and write them to a Receiver
EventMappingIterator	MappingIterator merges a sequence of sequences into a single sequence.
EventStackIterator	An EventStackIterator is an EventIterator that delivers a flat sequence of PullEvents containing no nested EventIterators
EventToStaxBridge	This class bridges EventIterator events to XMLStreamReader (Stax) events.
NamespaceMaintainer	NamespaceMaintainer is an EventIterator responsible for maintaining namespace context in an event stream.
PullEventSource	A PullSource is a JAXP Source that encapsulates a PullProvider - that is, an object that supplies an XML document as a sequence of events that are read under the control of the recipient.
PullEventTracer	Diagnostic class to display the sequence of events reported by an EventIterator
SequenceComposer	This class takes a sequence of pull events and composes them into a sequence of items.
SingletonEventIterator	This class represents an EventIterator over a sequence containing a single pull event.
StartDocumentEvent	A PullEvent representing the start of a document node
StartElementEvent	This is a PullEvent representing the start of an element node.
StaxToEventBridge	This class implements the Saxon EventIterator API on top of a standard StAX parser (or any other StAX XMLStreamReader implementation)
TracingEventIterator	This class is a filter for a sequence of pull events; it returns the input sequence unchanged, but traces execution to System.err

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