<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--NewPage--> <HTML> <HEAD> <!-- Generated by javadoc (build 1.6.0_18) on Fri Dec 09 20:48:49 GMT 2011 --> <TITLE> net.sf.saxon.evpull </TITLE> <META NAME="date" CONTENT="2011-12-09"> <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style"> <SCRIPT type="text/javascript"> function windowTitle() { if (location.href.indexOf('is-external=true') == -1) { parent.document.title="net.sf.saxon.evpull"; } } </SCRIPT> <NOSCRIPT> </NOSCRIPT> </HEAD> <BODY BGCOLOR="white" onload="windowTitle();"> <HR> <!-- ========= START OF TOP NAVBAR ======= --> <A NAME="navbar_top"><!-- --></A> <A HREF="#skip-navbar_top" title="Skip navigation links"></A> <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> <TR> <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A NAME="navbar_top_firstrow"><!-- --></A> <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> <TR ALIGN="center" VALIGN="top"> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> </TR> </TABLE> </TD> <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> </EM> </TD> </TR> <TR> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../../net/sf/saxon/event/package-summary.html"><B>PREV PACKAGE</B></A> <A HREF="../../../../net/sf/saxon/expr/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../../index.html?net/sf/saxon/evpull/package-summary.html" target="_top"><B>FRAMES</B></A> <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> <SCRIPT type="text/javascript"> <!-- if(window==top) { document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); } //--> </SCRIPT> <NOSCRIPT> <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> </NOSCRIPT> </FONT></TD> </TR> </TABLE> <A NAME="skip-navbar_top"></A> <!-- ========= END OF TOP NAVBAR ========= --> <HR> <H2> Package net.sf.saxon.evpull </H2> 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. <P> <B>See:</B> <BR> <A HREF="#package_description"><B>Description</B></A> <P> <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> <B>Interface Summary</B></FONT></TH> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventIterator.html" title="interface in net.sf.saxon.evpull">EventIterator</A></B></TD> <TD>An iterator over a sequence of events</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventMappingFunction.html" title="interface in net.sf.saxon.evpull">EventMappingFunction</A></B></TD> <TD>EventMappingFunction is an interface that must be satisfied by an object passed to an EventMappingIterator.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/PullEvent.html" title="interface in net.sf.saxon.evpull">PullEvent</A></B></TD> <TD>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 </TD> </TR> </TABLE> <P> <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> <B>Class Summary</B></FONT></TH> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/BlockEventIterator.html" title="class in net.sf.saxon.evpull">BlockEventIterator</A></B></TD> <TD>Iterate over the instructions in a Block, concatenating the result of each instruction into a single combined sequence.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/BracketedDocumentIterator.html" title="class in net.sf.saxon.evpull">BracketedDocumentIterator</A></B></TD> <TD>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.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/BracketedElementIterator.html" title="class in net.sf.saxon.evpull">BracketedElementIterator</A></B></TD> <TD>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.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/ComplexContentProcessor.html" title="class in net.sf.saxon.evpull">ComplexContentProcessor</A></B></TD> <TD>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.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/Decomposer.html" title="class in net.sf.saxon.evpull">Decomposer</A></B></TD> <TD>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.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EmptyEventIterator.html" title="class in net.sf.saxon.evpull">EmptyEventIterator</A></B></TD> <TD>This class is an EventIterator over an empty sequence.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EndDocumentEvent.html" title="class in net.sf.saxon.evpull">EndDocumentEvent</A></B></TD> <TD>Pull event representing the end of a document</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EndElementEvent.html" title="class in net.sf.saxon.evpull">EndElementEvent</A></B></TD> <TD>Pull event representing the end of an element node</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventAnnotationStripper.html" title="class in net.sf.saxon.evpull">EventAnnotationStripper</A></B></TD> <TD>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</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventIteratorOverSequence.html" title="class in net.sf.saxon.evpull">EventIteratorOverSequence</A></B></TD> <TD>This class maps a SequenceIterator to an EventIterator, by simply returning the items in the sequence as PullEvents.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventIteratorToReceiver.html" title="class in net.sf.saxon.evpull">EventIteratorToReceiver</A></B></TD> <TD>Class to read pull events from an EventIterator and write them to a Receiver</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventMappingIterator.html" title="class in net.sf.saxon.evpull">EventMappingIterator</A></B></TD> <TD>MappingIterator merges a sequence of sequences into a single sequence.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventStackIterator.html" title="class in net.sf.saxon.evpull">EventStackIterator</A></B></TD> <TD>An EventStackIterator is an EventIterator that delivers a flat sequence of PullEvents containing no nested EventIterators</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/EventToStaxBridge.html" title="class in net.sf.saxon.evpull">EventToStaxBridge</A></B></TD> <TD>This class bridges EventIterator events to XMLStreamReader (Stax) events.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/NamespaceMaintainer.html" title="class in net.sf.saxon.evpull">NamespaceMaintainer</A></B></TD> <TD>NamespaceMaintainer is an EventIterator responsible for maintaining namespace context in an event stream.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/PullEventSource.html" title="class in net.sf.saxon.evpull">PullEventSource</A></B></TD> <TD>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.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/PullEventTracer.html" title="class in net.sf.saxon.evpull">PullEventTracer</A></B></TD> <TD>Diagnostic class to display the sequence of events reported by an EventIterator</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/SequenceComposer.html" title="class in net.sf.saxon.evpull">SequenceComposer</A></B></TD> <TD>This class takes a sequence of pull events and composes them into a sequence of items.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/SingletonEventIterator.html" title="class in net.sf.saxon.evpull">SingletonEventIterator</A></B></TD> <TD>This class represents an EventIterator over a sequence containing a single pull event.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/StartDocumentEvent.html" title="class in net.sf.saxon.evpull">StartDocumentEvent</A></B></TD> <TD>A PullEvent representing the start of a document node</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/StartElementEvent.html" title="class in net.sf.saxon.evpull">StartElementEvent</A></B></TD> <TD>This is a PullEvent representing the start of an element node.</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/StaxToEventBridge.html" title="class in net.sf.saxon.evpull">StaxToEventBridge</A></B></TD> <TD>This class implements the Saxon EventIterator API on top of a standard StAX parser (or any other StAX XMLStreamReader implementation)</TD> </TR> <TR BGCOLOR="white" CLASS="TableRowColor"> <TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/evpull/TracingEventIterator.html" title="class in net.sf.saxon.evpull">TracingEventIterator</A></B></TD> <TD>This class is a filter for a sequence of pull events; it returns the input sequence unchanged, but traces execution to System.err</TD> </TR> </TABLE> <P> <A NAME="package_description"><!-- --></A><H2> Package net.sf.saxon.evpull Description </H2> <P> <p>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 <A HREF="../../../../net/sf/saxon/evpull/PullEvent.html" title="interface in net.sf.saxon.evpull"><CODE>PullEvent</CODE></A>, and a component that can be invoked to deliver a sequence of these objects is a <A HREF="../../../../net/sf/saxon/evpull/EventIterator.html" title="interface in net.sf.saxon.evpull"><CODE>EventIterator</CODE></A>.</p> <p>An <A HREF="../../../../net/sf/saxon/evpull/EventIterator.html" title="interface in net.sf.saxon.evpull"><CODE>EventIterator</CODE></A> is itself a <A HREF="../../../../net/sf/saxon/evpull/PullEvent.html" title="interface in net.sf.saxon.evpull"><CODE>PullEvent</CODE></A>, 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 <i>flat</i> sequence, and any sequence of events can be converted to a flat sequence by inserting an <A HREF="../../../../net/sf/saxon/evpull/EventStackIterator.html" title="class in net.sf.saxon.evpull"><CODE>EventStackIterator</CODE></A> into the pipeline.</p> <p>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 <A HREF="../../../../net/sf/saxon/evpull/PullEventSource.html" title="class in net.sf.saxon.evpull"><CODE>PullEventSource</CODE></A> object to an interface that expects an XML document to be supplied as a JAXP <A HREF="http://download.oracle.com/javase/6/docs/api/javax/xml/transform/Source.html?is-external=true" title="class or interface in javax.xml.transform"><CODE>Source</CODE></A>. It is also used in XQJ when methods such as <A HREF="../../../../javax/xml/xquery/XQDataFactory.html#createItemFromDocument(java.lang.String, java.lang.String, javax.xml.xquery.XQItemType)"><CODE>XQDataFactory.createItemFromDocument(java.lang.String, java.lang.String, javax.xml.xquery.XQItemType)</CODE></A> are used to construct an XML document from a supplied <A HREF="http://download.oracle.com/javase/6/docs/api/javax/xml/stream/XMLStreamReader.html?is-external=true" title="class or interface in javax.xml.stream"><CODE>XMLStreamReader</CODE></A>. In such cases Saxon uses the class <A HREF="../../../../net/sf/saxon/evpull/StaxToEventBridge.html" title="class in net.sf.saxon.evpull"><CODE>StaxToEventBridge</CODE></A> to convert StAX events to its own <A HREF="../../../../net/sf/saxon/evpull/PullEvent.html" title="interface in net.sf.saxon.evpull"><CODE>PullEvent</CODE></A> events. Conversion in the opposite direction uses the class <A HREF="../../../../net/sf/saxon/evpull/EventToStaxBridge.html" title="class in net.sf.saxon.evpull"><CODE>EventToStaxBridge</CODE></A>.</p> <p>It is possible to request pull-mode evaluation of XQuery code using the method <A HREF="../../../../net/sf/saxon/query/XQueryExpression.html#iterateEvents(net.sf.saxon.Controller, net.sf.saxon.query.DynamicQueryContext)"><CODE>XQueryExpression.iterateEvents(net.sf.saxon.Controller, net.sf.saxon.query.DynamicQueryContext)</CODE></A>. 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 <code>iterateEvents()</code> method to support this mode of execution.</p> <p>A sequence of events is said to be <i>composed</i> 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 <i>decomposed</i> 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 <A HREF="../../../../net/sf/saxon/om/SequenceIterator.html" title="interface in net.sf.saxon.om"><CODE>SequenceIterator</CODE></A> interface rather than by the classes in this package. The <A HREF="../../../../net/sf/saxon/evpull/SequenceComposer.html" title="class in net.sf.saxon.evpull"><CODE>SequenceComposer</CODE></A> returns a full composed event stream from a decomposed or mixed stream, constructing tree fragments when necessary to achieve this; the <A HREF="../../../../net/sf/saxon/evpull/Decomposer.html" title="class in net.sf.saxon.evpull"><CODE>Decomposer</CODE></A> does the inverse, walking any tree fragments to deliver the corresponding start-element and end-element events.</p> <p>The class <A HREF="../../../../net/sf/saxon/evpull/EventIteratorOverSequence.html" title="class in net.sf.saxon.evpull"><CODE>EventIteratorOverSequence</CODE></A> converts a stream of items obtained from a <A HREF="../../../../net/sf/saxon/om/SequenceIterator.html" title="interface in net.sf.saxon.om"><CODE>SequenceIterator</CODE></A> into a composed stream of <A HREF="../../../../net/sf/saxon/evpull/PullEvent.html" title="interface in net.sf.saxon.evpull"><CODE>PullEvent</CODE></A> events.</p> <p>The class <A HREF="../../../../net/sf/saxon/evpull/EventIteratorToReceiver.html" title="class in net.sf.saxon.evpull"><CODE>EventIteratorToReceiver</CODE></A> reads a sequence of events from a pull pipeline and outputs the same sequence of events to a push pipeline using the <A HREF="../../../../net/sf/saxon/event/Receiver.html" title="interface in net.sf.saxon.event"><CODE>Receiver</CODE></A> interface.</p> <p>The package <A HREF="../../../../net/sf/saxon/pull/package-summary.html"><CODE>net.sf.saxon.pull</CODE></A> represents an earlier attempt at pull-mode processing in Saxon. It is retained because it provides some capabilities not yet present in this package.</p> <hr> <p align="center"><i>Michael H. Kay<br/> Saxonica Limited<br/> 30 July 2010</i></p> <P> <P> <DL> </DL> <HR> <!-- ======= START OF BOTTOM NAVBAR ====== --> <A NAME="navbar_bottom"><!-- --></A> <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> <TR> <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A NAME="navbar_bottom_firstrow"><!-- --></A> <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> <TR ALIGN="center" VALIGN="top"> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> </TR> </TABLE> </TD> <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> </EM> </TD> </TR> <TR> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../../net/sf/saxon/event/package-summary.html"><B>PREV PACKAGE</B></A> <A HREF="../../../../net/sf/saxon/expr/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../../index.html?net/sf/saxon/evpull/package-summary.html" target="_top"><B>FRAMES</B></A> <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> <SCRIPT type="text/javascript"> <!-- if(window==top) { document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); } //--> </SCRIPT> <NOSCRIPT> <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> </NOSCRIPT> </FONT></TD> </TR> </TABLE> <A NAME="skip-navbar_bottom"></A> <!-- ======== END OF BOTTOM NAVBAR ======= --> <HR> Copyright (c) 2004-2011 Saxonica Limited. All rights reserved. </BODY> </HTML>