Project

Profile

Help

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

he / tags / 9.7.0.3 / hej / net / sf / saxon / evpull / package.html @ cb770b3c

1
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
2
<!-- Copyright (c) 2014 Saxonica Limited. -->
3
<!-- This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. -->
4
<!-- If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
5
<!-- This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0. -->
6
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
7

    
8
<html>
9

    
10
<head>
11
    <title>Package overview for net.sf.saxon.evpull</title>
12
</head>
13

    
14
<body>
15

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

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

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

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

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

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

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

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

    
66
<hr>
67

    
68
<p align="center"><i>Michael H. Kay<br/>
69
    Saxonica Limited<br/>
70
    30 July 2010</i></p>
71
</body>
72
</html>
(27-27/27)