net.sf.saxon.evpull.package.html Maven / Gradle / Ivy
Show all versions of saxon-he Show documentation
Package overview for 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. The
object that is supplied in response to these calls is a {@link net.sf.saxon.evpull.PullEvent}, and
a component that can be invoked to deliver a sequence of these objects is a {@link net.sf.saxon.evpull.EventIterator}.
An {@link net.sf.saxon.evpull.EventIterator} is itself a {@link net.sf.saxon.evpull.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 {@link net.sf.saxon.evpull.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 {@link net.sf.saxon.evpull.PullEventSource} object to an interface
that expects an XML document to be supplied as a JAXP {@link javax.xml.transform.Source}. It is also used
in XQJ when methods such as {@link javax.xml.xquery.XQDataFactory#createItemFromDocument} are used
to construct an XML document from a supplied {@link javax.xml.stream.XMLStreamReader}. In such cases
Saxon uses the class {@link net.sf.saxon.evpull.StaxToEventBridge} to convert StAX events to its own
{@link net.sf.saxon.evpull.PullEvent} events. Conversion in the opposite direction uses the class
{@link net.sf.saxon.evpull.EventToStaxBridge}.
It is possible to request pull-mode evaluation of XQuery code using the method
{@link net.sf.saxon.query.XQueryExpression#iterateEvents}. 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
{@link net.sf.saxon.om.SequenceIterator} interface rather than by the classes in this package.
The {@link net.sf.saxon.evpull.SequenceComposer} returns a full composed event stream
from a decomposed or mixed stream, constructing tree fragments when
necessary to achieve this; the {@link net.sf.saxon.evpull.Decomposer}
does the inverse, walking any tree fragments to deliver the corresponding start-element and end-element
events.
The class {@link net.sf.saxon.evpull.EventIteratorOverSequence} converts a stream of items obtained
from a {@link net.sf.saxon.om.SequenceIterator} into a composed stream of {@link net.sf.saxon.evpull.PullEvent} events.
The class {@link net.sf.saxon.evpull.EventIteratorToReceiver} reads a sequence of events from a pull pipeline
and outputs the same sequence of events to a push pipeline using the {@link net.sf.saxon.event.Receiver}
interface.
The package {@link 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