Nux 1.0

nux.xom.xquery
Interface ResultSequence


public interface ResultSequence

A forward-only iterator representing an XQuery result sequence of zero or more results; allows to stream (pipeline) execution output, or to conveniently collect it 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 Nodeobjects, via the toNodes() method. This is more convenient, but also more memory-intensive. In fact, toNodes() is typically just a convenience loop around next().

The result of an XQuery is a sequence of nodes or a sequence of atomic values - which means it is not, in general, an XML document.

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

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

public 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

public 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

Nux 1.0