# 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

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