com.marklogic.xcc
Interface ResultSequence

All Superinterfaces:

XdmSequence, XdmValue

public interface ResultSequence

extends XdmSequence

A sequence of ResultItem values as returned from a query or module execution. A ResultSequence instance is stateful, it holds an internal positional index (cursor) which is updated on successive accesses. It is therefore not recommended that ResultSequence objects be accessed concurrently by multiple threads.

ResultSequence instances can operate in two modes: cached and non-cached. If a ResultSequence is cached (default) then all XdmItems have been read and buffered. If non-cached, then items may only be accessed sequentially and some values may only be fetched once if accessed as an InputStream or Reader.

Cached ResultSequences need not be closed. Upon return, they no longer tie up any connection resources. However, closing a cached ResultSequence will invalidate it and prevent further access to its contents.

Streaming (non-cached) ResultSequences should always be promptly closed. They hold a server connection until closed. If not closed, connections may be tied up indefinitely. Additionally, you should always consume the ResultSequence in a timely manner, because the server may close the connection if the (server-side configurable) request tiemout expires before the data is read out.

In general, it is preferable to use cached ResultSequences (this is the default) unless you have reason to believe the amount of data returned may be too large to be fully buffered in memory.

Method Summary

void	close() Release any resources being held by this ResultSequence.
ResultItem	current() Fetch the current ResultItem object in the 1ResultSequence.
ResultSequence	getChannel(ResultChannelName channel) Return the ResultSequence for an alternate ResultChannelName.
boolean	hasNext() Returns true if this sequence contains another item beyond the currently active one.
boolean	isCached() Indicates whether this is a cached (detached) ResultSequence.
boolean	isClosed() Indicates whether this ResultSequence is closed.
XdmItem	itemAt(int index) Returns the XdmItem wrapped by the ResultItem at the given index.
Iterator	iterator() Returns a java.util.Iterator instance that may be used to iterate over this result sequence.
ResultItem	next() Advance the logical cursor to the next ResultItem in this ResultSequence and return that item.
ResultItem	resultItemAt(int index) Returns the ResultItem from this ResultSequence, if possible, at the given positional index.
void	rewind() Reset the internal positional index (cursor) of this ResultSequence to before the first ResultItem in the sequence.
int	size() Returns the number of ResultItems, if known, in this ResultSequence.
ResultSequence	toCached() Produce a cached version of this ResultSequence.
ResultItem[]	toResultItemArray() This method is identical to the superclass method XdmSequence.toArray(), but returns an array typed as ResultItem.
String	toString() Return a textual description of this ResultSequence object, NOT the value of the items in the sequence.

Methods inherited from interface com.marklogic.xcc.types.XdmSequence

asString, asString, asStrings, isEmpty, toArray

Methods inherited from interface com.marklogic.xcc.types.XdmValue

getValueType

Method Detail

size

public int size()

Returns the number of ResultItems, if known, in this ResultSequence. For streaming (non-cached) ResultSequences, ResultItems are processed sequentially from the communication channel and so the size of the full sequence is not known during iteration.

Specified by:

size in interface XdmSequence

Returns:

The size, if this ResultSequence is cached, otherwise -1.

isCached

public boolean isCached()

Indicates whether this is a cached (detached) ResultSequence. A cached ResultSequence has fully buffered all the ResultItem data values and no longer depends on an active server connection. A cached ResultSequence may be accessed repeatedly and/or randomly.

Cached ResultSequence objects do not need to be closed because they no longer have any reference to a server connection. But if they are closed (by invoking close(), then the buffered data values are released and it is no longer usable.

Returns:

True if the entire ResultSequence is cached. If this ResultSequence is closed, then false is returned.

close

public void close()

Release any resources being held by this ResultSequence. If cached, this is a no-op an the cached ResultItems are retained (let the ResultSequence go out of scope to cause the cached data to be reclaimed). If not cached, this ResultSequence will be invalidated and its ResultItem members will no longer be accessible.

isClosed

public boolean isClosed()

Indicates whether this ResultSequence is closed.

Returns:

true if closed, false if open.

hasNext

public boolean hasNext()

Returns true if this sequence contains another item beyond the currently active one. Initially, the result sequence is positioned before the first item, if any, and this method will return false if the sequence is empty. Note that if the current item is large (node, binary, text) and has not yet been fully consumed by the client, it's value may be flushed and lost as the result stream is positioned to the next item.

Returns:

True if at least one more item exists in this ResultSequence. If closed, this method always returns false.

next

public ResultItem next()

Advance the logical cursor to the next ResultItem in this ResultSequence and return that item. The logical cursor is initially positioned before the first item in the sequence.

Unlike Iterator.next(), this method returns null when there is no next item.

Returns:

The next ResultItem in this sequence, or null if the end of the sequence has been reached. Note that the sequence may be empty and this method may return null on the first call.

Throws:

IllegalStateException - If this ResultSequence is closed.

current

public ResultItem current()

Fetch the current ResultItem object in the 1ResultSequence. The method ResultItem.isFetchable() indicates whether the value for this item is available. Simple data values (numbers, dates, durations, etc) are cached and may always be re-fetched.

Large data values (nodes, text, etc) that are read as a stream or a reader are not guaranteed to be fetchable more than once.

Returns:

The currently active ResultItem in this sequence, or null if the cursor is not currently positioned on an item. This will be the case before the first call to next() and after next() returns null.

Throws:

IllegalStateException - If this method is called before the first call to next() or after next() returns null or if closed.

See Also:

ResultItem.isFetchable(), isCached(), XdmItem.isCached()

resultItemAt

public ResultItem resultItemAt(int index)

Returns the ResultItem from this ResultSequence, if possible, at the given positional index. Accessing ResultItems randomly has restrictions if isCached() returns true.

For streaming ResultSequences, if index is equal to the current position, then the current ResultItem is returned. If index is less than the current position, then an exception is thrown. If index is greater than the current position, then items in the sequence are read and discarded until the requested position is achieved. If the requested item is found, it is returned. If the end of the sequence is encountered while trying to seek to the requested position, an exception is thrown.

Parameters:

index - The position (zero-based) of the ResultItem to return.

Returns:

The ResultItem at the given index.

Throws:

IllegalArgumentException - If index is negative or greater than or equal to size().

IllegalStateException - If this ResultSequence is not cached (isCached() returns false) and the index does not match the current cursor value, or if closed.

itemAt

public XdmItem itemAt(int index)

Returns the XdmItem wrapped by the ResultItem at the given index.

Specified by:

itemAt in interface XdmSequence

Parameters:

index - The position (zero-based) of the ResultItem to return.

Returns:

The underlying XdmItem for the ResultItem at the requested index.

Throws:

IllegalArgumentException - If index is negative or greater than or equal to size().

IllegalStateException - If this ResultSequence is not cached (isCached() returns false) and the index xdoes not match the current cursor value, or if closed.

rewind

public void rewind()

Reset the internal positional index (cursor) of this ResultSequence to before the first ResultItem in the sequence. This operation is only supported if isCached() returns true.

Throws:

IllegalStateException - If called on a non-cached (streaming) ResultSequence (isCached() returns false).

IllegalStateException - If this ResultSequence streaming or is closed.

iterator

public Iterator iterator()

Returns a java.util.Iterator instance that may be used to iterate over this result sequence. Each object returned by the Iterator is an instance of ResultItem.

Specified by:

iterator in interface XdmSequence

Returns:

An Iterator instance for this ResultSequence.

Throws:

IllegalStateException - If this ResultSequence is closed.

toCached

public ResultSequence toCached()

Produce a cached version of this ResultSequence. If the provided ResultSequence is already cached (isCached() returns true), then nothing is done and this instance returns itself. Otherwise, a new, cached ResultSequence instance is created and populated with the XdmItems in the sequence. If the non-cached input ResultSequence has been partially iterated, only the remaining XdmItems will be cached. If the current item is not fetchable (ResultItem.isFetchable() returns false), it will be ignored.

Returns:

A Cached ResultSequence.

Throws:

IllegalStateException - If this ResultSequence is closed.

See Also:

isCached()

toResultItemArray

public ResultItem[] toResultItemArray()

This method is identical to the superclass method XdmSequence.toArray(), but returns an array typed as ResultItem.

Invoking XdmSequence.toArray() on a ResultSequence actually invokes this method. If the ResultSequence is streaming (isCached() returns false), then it is consumed and closed after building the returned array. Note also that XdmSequence.asStrings() when called on a ResultSequence will call this method internally, which will also result in the object being closed automatically.

Note that for a streaming ResultSequence, all items will be loaded into memory to build the array. If very large items (node(), text(), etc) are in the stream, it's possible that there may not be enough memory to buffer everything. If the sequence contains too much data to buffer, iterate over each item and use XdmItem.asInputStream() to read each item in turn as an InputStream.

Returns:

An array of ResultItem instances, all of which will be cached.

Throws:

IllegalStateException - If this ResultSequence is closed.

StreamingResultException - If an IOException ocurrs while buffering a ResultItem

getChannel

public ResultSequence getChannel(ResultChannelName channel)

Return the ResultSequence for an alternate ResultChannelName. The ResultSequence returned by Session.submitRequest(Request) is the sequence of XdmItems representing the XQuery result. But there may be alternate channels (each comprising a ResultSequence instance) associated with the result. This method returns the sequence for the given channel. The ResultSequence returned by Session.submitRequest(Request) is always ResultChannelName.PRIMARY. A ResultSequence instance is always returned by this method, though it may be empty.

Parameters:

channel - An instance of ResultChannelName that indicates which channel to return.

Returns:

An instance of ResultSequence, possibly empty.

Throws:

IllegalStateException - If this ResultSequence is closed.

toString

public String toString()

Return a textual description of this ResultSequence object, NOT the value of the items in the sequence. Use the XdmSequence.asString() or XdmSequence.asStrings() methods to obtain String representations of the item values.

Specified by:

toString in interface XdmSequence

Returns:

A textual description of this object, appropriate for use in a debug or log message.

See Also:

XdmSequence.asString(), XdmSequence.asStrings()