public abstract class ItemFeed extends ProxyOutputter
Expressions are thus evaluated "bottom up": instead of a parent expression triggering the evaluation of its children, the appearance of data needed by a child expression causes evaluation of the child expression, which then triggers evaluation of its parent, and so on.
One consequence of this is that special mechanisms are needed for error handling. In particular, it's not possible for a child expression to notify its parent expression of dynamic errors simply by throwing a Java exception: the error information needs to be passed up the pipeline in the same way as regular results.
Some expressions (inspection expressions) are only interested in top-level events:
for example count()
, exists
, and instance of
only need to know
about a startElement
event, they are not interested in the content of the element,
only in its existence. Other expressions (absorption expression) need access to the content
of the element: in most cases, the typed value of the element, but in some cases (such as
copy-of()
or snapshot()
a finer-grained representation of the content.
In such cases the startSelectedParentNode(FleetingParentNode, Location)
method
(which is notified of a top-level event in the input stream) returns a Receiver
,
which is then notified of all the contained events up to the corresponding endElement
.
Some expressions (transmission expression) pass data on to their parent expressions directly, and in these cases the decision whether to ask for full details of the content is delegated to the parent expression, or beyond.
An expression whose result is known before all the input is available (for example,
exists()
can call a supplied Terminator
to indicate that no more input is
required. In some cases (where the expression would otherwise read an entire document)
this enables parsing of the streamed input file to be abandoned.
The events passed up the pipeline will usually correspond to nodes in the streamed source document, or to atomic values computed from those nodes. In unusual edge cases, however, a consuming expression may generate new element or document nodes, which are still delivered incrementally because their content is established by streaming the source document. Events representing these constructed elements are passed up the pipeline as if they came from the source document. (Note, because this situation is unusual and somewhat contrived, it probably has incomplete test coverage and may not be fully implemented for all kinds of expression).
The start of an element may be represented either as a single event containing all the
attributes and namespaces, or as a sequence of separate events (start element, attributes,
namespaces, then startContent
). Events coming directly from parsing the streamed
input will use the more efficient "bundled" form, but events representing constructed nodes
may be "unbundled" because attributes and namespaces can be constructed incrementally as the
streamed input is processed. An ItemFeed
for a parent expression should therefore
be prepared to accept either form.
pipelineConfiguration, systemId
Constructor and Description |
---|
ItemFeed(Expression exp,
ItemFeed result,
XPathContext context) |
ItemFeed(ItemFeed result,
XPathContext context) |
ItemFeed(Outputter result,
XPathContext context,
boolean thisIsAnExceptionalCase)
Special constructor for the last ItemFeed in the pipeline, which feeds into an Outputter
rather than into another ItemFeed.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
append(Item item)
Supply one item towards the streamed input of the expression
|
void |
append(Item item,
Location locationId,
int properties)
Supply one item towards the streamed input of the expression.
|
void |
close()
Finish evaluating the expression.
|
void |
dynamicError(XPathException error)
Report a dynamic error.
|
void |
endSelectedParentNode(Location locationId)
Signal that the endElement event has occurred for the element whose startElement
event caused the Watch to be activated.
|
XPathContext |
getContext()
Get the dynamic evaluation context
|
Expression |
getExpression()
Get the expression being evaluated by this ItemFeed.
|
ItemFeed |
getResult()
Get the result, that is, the ItemFeed to which the items in the result
of the expression should be supplied
|
Terminator |
getTerminator()
Get the Terminator which can be used to request early termination of the Feed
|
boolean |
hasFailed() |
void |
open(Terminator terminator)
Start evaluating the expression.
|
static void |
processItems(SequenceIterator iter,
Outputter result)
Convenience method to process all the items selected by an iterator and push them to the next
feed in the push pipeline
|
void |
setExpression(Expression exp)
Set the expression being evaluated by this ItemFeed
|
void |
setHasFailed()
Mark this feed as having failed (that is, as having detected and reported
a dynamic error).
|
void |
setTerminator(Terminator terminator)
Provide a callback that can be used to request early termination of the
streaming of this input document
|
Receiver |
startSelectedParentNode(FleetingParentNode node,
Location locationId)
Signal that an element or document node has been found that matches the selection that this
Watch is looking for.
|
attribute, characters, comment, endDocument, endElement, getNextOutputter, namespace, open, processingInstruction, setUnparsedEntity, startContent, startDocument, startElement, startElement, usesTypeAnnotations
getConfiguration, getPipelineConfiguration, getStringReceiver, getSystemId, namespaces, setPipelineConfiguration, setSystemId
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
handlesAppend
public ItemFeed(ItemFeed result, XPathContext context)
public ItemFeed(Expression exp, ItemFeed result, XPathContext context)
public ItemFeed(Outputter result, XPathContext context, boolean thisIsAnExceptionalCase)
result
- the resulting outputtercontext
- the dynamic evaluation contextthisIsAnExceptionalCase
- value is ignored; the parameter is there simply to flag
this constructor as a special casepublic static void processItems(SequenceIterator iter, Outputter result) throws XPathException
iter
- iterator over the selected itemsresult
- the next feed in the pipelineXPathException
- if any dynamic error occurspublic void setExpression(Expression exp)
exp
- the relevant expressionpublic Expression getExpression()
public void setTerminator(Terminator terminator)
terminator
- the class that can be called to request terminationpublic void setHasFailed()
public Terminator getTerminator()
public ItemFeed getResult()
public XPathContext getContext()
public void open(Terminator terminator) throws XPathException
terminator
- used to achieve early exitXPathException
- if a dynamic error occurspublic Receiver startSelectedParentNode(FleetingParentNode node, Location locationId) throws XPathException
node
- the element or document node whose start event has been matchedlocationId
- the location associated with the element or document node (may be
the location of the instruction that created it)XPathException
- May be raised if a dynamic error occurspublic abstract void append(Item item) throws XPathException
append
in interface Receiver
append
in class ProxyOutputter
item
- the item to be suppliedXPathException
- if the operation failspublic final void append(Item item, Location locationId, int properties) throws XPathException
append(Item)
, and it is final so subclasses do not have to cater for
this eventappend
in interface Receiver
append
in class ProxyOutputter
item
- the item to be suppliedlocationId
- the location of the calling instruction, for diagnosticsproperties
- if the item is an element node, this indicates whether its namespaces
need to be copied. Values are ReceiverOption.ALL_NAMESPACES
; the default (0) meansXPathException
- if an error occurspublic void endSelectedParentNode(Location locationId) throws XPathException
locationId
- the location of the elementXPathException
- May be raised if a constraint implemented by this
Watch is violatedpublic void close() throws XPathException
close
in interface Receiver
close
in class ProxyOutputter
XPathException
- if a dynamic error occurspublic void dynamicError(XPathException error) throws XPathException
error
- the exception representing the dynamic errorXPathException
- if there is no try/catch expression wanting to catch this errorpublic boolean hasFailed()
Copyright (c) 2004-2020 Saxonica Limited. All rights reserved.