nux.xom.xquery
Interface ResultSequence

public interface ResultSequence

A forward-only iterator representing an XQuery result sequence of zero or more ordered items.

The XQuery/XPath data model is based on the notion of a result sequence. A result sequence is an ordered collection of zero or more items. An item may be a node (document, element, attribute, namespace, text, processing-instruction or comment) or an atomic value. This means that a result sequence is not, in general, an XML document.

This interface does not mandate how an implementation should convert top-level atomic values to Node objects; an implementation is encouraged to document how it converts such atomic values. For example, see the default implementation in XQuery.newResultSequence(net.sf.saxon.query.XQueryExpression, net.sf.saxon.query.DynamicQueryContext).

This interface allows to stream (pipeline) execution results, or to conveniently collect them in a batched manner.

In streamed manner, result nodes are lazily produced via the pipelined next() method, one result at a time. This is useful if output is very large, since only one node at a time needs to be materialized in memory. Here, each node can immediately be garbage collected after the application has processed it (e.g. has written it to disk or the network). Further, an application should choose streamed mode if it is known that it will use only the first or the first few result nodes anyway, ignoring other potentially remaining results.

In batched manner all execution output results are eagerly collected together into a node list containing zero or more Node objects, via the toNodes() method. This is more convenient, but also more memory-intensive. In fact, toNodes() is typically just a convenience loop around next().

Author:

whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Method Summary

Node	next() Returns the next node from the result sequence, or null if there are no more nodes available due too iterator exhaustion.
Nodes	toNodes() Returns all remaining nodes from the result sequence, collected into a list of zero or more Node objects.

Method Detail

next

Node next()
          throws XQueryException

Returns the next node from the result sequence, or null if there are no more nodes available due too iterator exhaustion.

Returns:

the next node, or null if no more nodes are available

Throws:

XQueryException - if an error occurs during execution

toNodes

Nodes toNodes()
              throws XQueryException

Returns all remaining nodes from the result sequence, collected into a list of zero or more Node objects.

Returns:

a node list

Throws:

XQueryException - if an error occurs during execution