# Package com.saxonica.xqj.pull

This package extends the pull API for Saxon that is provided in package `net.sf.saxon.pull` in Saxon-HE. It provides features allowing walking of an existing Saxon tree and delivering events in the same way as a pull parser; it also allows queries and stylesheets to create lazily-constructed document and element nodes which can then be read using the pull interface.

The three main kinds of `PullProvider` supported in this package are:

- StaxBridge, which is an interface to a pull-mode XML parser, and is also present in Saxon-HE

- TreeWalker, which delivers events based on an in-memory tree. There is one general-purpose TreeWalker that can handle any Saxon tree (any tree that implements the NodeInfo interface) and aother that is optimized to the TinyTree implementation.

- VirtualTreeWalker, which delivers events representing the nodes constructed by a stylesheet or query, without actually constructing the nodes in memory. (Note that this doesn't currently work if the constructed nodes need to be schema-validated).

The facility to evaluate the results of a query in pull mode using the `PullProvider` interface are largely superseded by the `net.sf.saxon.evpull.EventIterator` interface, which is directly or indirectly supported by all expressions.

Some examples of application code using the pull interface with Saxon are provided in the `PullExamples.java` file in the samples directory.

- Class Summary
  Class | Description
  --- | ---
  DocumentWrappingPullProvider | Returns the events provided by an underlying PullProvider, with the addition of a START_DOCUMENT event immediately after the START_OF_INPUT, and an END_DOCUMENT event immediately before the END_OF_INPUT
  ElementNameTracker | This is a filter that can be added to a pull pipeline to remember element names so that they are available immediately after the END_ELEMENT event is notified
  PullFromIterator | This class delivers any XPath sequence through the pull interface.
  PullNamespaceReducer | PullNamespaceReducer is a PullFilter responsible for removing duplicate namespace declarations.
  PullToStax | This class bridges PullProvider events to XMLStreamReader (Stax) events.
  PullToStax.SourceStreamLocation | Bridge a SAX SourceLocator to a javax.xml.stream.Location
  PullTracer | PullTracer is a PullFilter that can be inserted into a pull pipeline for diagnostic purposes.
  TreeWalker | This implementation of the Saxon pull interface starts from any NodeInfo, and returns the events corresponding to that node and its descendants (including their attributes and namespaces).