Project

Profile

Help

How to connect?
Download (3.8 KB) Statistics
| Branch: | Tag: | Revision:

he / latest9.3 / hej / net / sf / saxon / evpull / package.html @ 9acaa097

1
<html>
2

    
3
<head>
4
<title>Package overview for net.sf.saxon.evpull</title>
5
</head>
6

    
7
<body>
8

    
9
<p>This package provides classes that implement a StAX-like pull pipeline in which a recieving component
10
makes calls on a provider component to supply information from the XML stream one event at a time. The
11
object that is supplied in response to these calls is a {@link net.sf.saxon.evpull.PullEvent}, and
12
a component that can be invoked to deliver a sequence of these objects is a {@link net.sf.saxon.evpull.EventIterator}.</p>
13

    
14
<p>An {@link net.sf.saxon.evpull.EventIterator} is itself a {@link net.sf.saxon.evpull.PullEvent}, so an event provider
15
may return a sequence of events in response to a single call by returning an iterator. A sequence of events containing
16
no iterators is referred to as a <i>flat</i> sequence, and any sequence of events can be converted to a flat
17
sequence by inserting an {@link net.sf.saxon.evpull.EventStackIterator} into the pipeline.</p>
18

    
19
<p>Pull processing is not used extensively in Saxon, and is generally not used at all unless explicitly
20
requested. It can be requested, for example, by supplying a {@link net.sf.saxon.evpull.PullEventSource} object to an interface
21
that expects an XML document to be supplied as a JAXP {@link javax.xml.transform.Source}. It is also used
22
in XQJ when methods such as {@link javax.xml.xquery.XQDataFactory#createItemFromDocument} are used
23
to construct an XML document from a supplied {@link javax.xml.stream.XMLStreamReader}. In such cases
24
Saxon uses the class {@link net.sf.saxon.evpull.StaxToEventBridge} to convert StAX events to its own
25
{@link net.sf.saxon.evpull.PullEvent} events. Conversion in the opposite direction uses the class
26
{@link net.sf.saxon.evpull.EventToStaxBridge}.</p>
27

    
28
<p>It is possible to request pull-mode evaluation of XQuery code using the method
29
{@link net.sf.saxon.query.XQueryExpression#iterateEvents}. This causes any document and element
30
node constructors to be evaluated in pull mode, returning events representing start/end document/element
31
rather than actually constructing the result tree in memory. The relevant expressions in the expression
32
tree provide an <code>iterateEvents()</code> method to support this mode of execution.</p>
33

    
34
<p>A sequence of events is said to be <i>composed</i> if it consists entirely of items (that is, a node
35
is passed as a single event, rather than by walking the tree); it is said to be <i>decomposed</i>
36
if if consists entirely of StAX-like events. In general, the classes in this package handle sequences
37
that mix both styles. A fully-composed sequence, however, is normally handled using the
38
    {@link net.sf.saxon.om.SequenceIterator} interface rather than by the classes in this package.
39
    The {@link net.sf.saxon.evpull.SequenceComposer} returns a full composed event stream
40
    from a decomposed or mixed stream, constructing tree fragments when
41
necessary to achieve this; the {@link net.sf.saxon.evpull.Decomposer}
42
does the inverse, walking any tree fragments to deliver the corresponding start-element and end-element
43
events.</p>
44

    
45
<p>The class {@link net.sf.saxon.evpull.EventIteratorOverSequence} converts a stream of items obtained
46
from a {@link net.sf.saxon.om.SequenceIterator} into a composed stream of {@link net.sf.saxon.evpull.PullEvent} events.</p>
47

    
48
<p>The class {@link net.sf.saxon.evpull.EventIteratorToReceiver} reads a sequence of events from a pull pipeline
49
and outputs the same sequence of events to a push pipeline using the {@link net.sf.saxon.event.Receiver}
50
interface.</p>
51

    
52
<p>The package {@link net.sf.saxon.pull} represents an earlier attempt at pull-mode processing in Saxon.
53
It is retained because it provides some capabilities not yet present in this package.</p>
54

    
55
<hr>
56

    
57
<p align="center"><i>Michael H. Kay<br/>
58
Saxonica Limited<br/>
59
30 July 2010</i></p>
60
</body>
61
</html>
(27-27/27)