# Package com.saxonica.pull

This package extends the pull API for Saxon that is provided in package `net.sf.saxon.pull` in Saxon-HE.

See: Description

- Class Summary
  Class | Description
  --- | ---
  DocumentEventIgnorer | This is a filter that can be added to a pull pipeline to remove START_DOCUMENT and END_DOCUMENT events.
  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.
  TinyTreeWalker | This implementation of the Saxon pull interface starts from a document, element, text, comment, or processing-instruction node in a TinyTree, and returns the events corresponding to that node and its descendants (including their attributes and namespaces).
  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).
  UnconstructedDocument | A document node whose construction is deferred.
  UnconstructedElement | An element node whose construction is deferred.
  UnconstructedParent | This class represents a virtual element node, the result of an element constructor that (in general) hasn't been fully evaluated.
  VirtualTreeWalker | A virtual tree walker provides a sequence of pull events describing the structure and content of a tree that is conceptually being constructed by expressions in a query or stylesheet; in fact the tree is not necessarily constructed in memory, and exists only as this stream of pull events.

## Package com.saxonica.pull Description

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.

Michael H. Kay
Saxonica Limited
10 June 2009

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