public interface ResultSequence extends XdmSequence<ResultItem>
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 XdmItem
s 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.
Modifier and Type | Method and Description |
---|---|
void |
close()
Release any resources being held by this ResultSequence.
|
ResultItem |
current()
Fetch the current
ResultItem object in the ResultSequence. |
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. |
java.util.Iterator<ResultItem> |
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
ResultItem s, 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 . |
java.lang.String |
toString()
Return a textual description of this ResultSequence object, NOT the value of
the items in the sequence.
|
asString, asString, asStrings, isEmpty, toArray
getValueType
int size()
Returns the number of ResultItem
s, if known, in this ResultSequence. For streaming
(non-cached) ResultSequences, ResultItem
s are processed sequentially from the
communication channel and so the size of the full sequence is not known during iteration.
size
in interface XdmSequence<ResultItem>
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.
void close()
ResultItem
s 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.boolean isClosed()
boolean hasNext()
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.
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.java.lang.IllegalStateException
- If this ResultSequence is closed.ResultItem current()
Fetch the current ResultItem
object in the ResultSequence. 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.
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.java.lang.IllegalStateException
- If this method is called before the first call to next()
or after
next()
returns null or if closed.ResultItem.isFetchable()
,
isCached()
,
XdmItem.isCached()
ResultItem resultItemAt(int index)
Returns the ResultItem
from this ResultSequence, if possible, at the given positional
index. Accessing ResultItem
s 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.
index
- The position (zero-based) of the ResultItem
to return.ResultItem
at the given index.java.lang.IllegalArgumentException
- If index is negative or greater than or equal to size()
.java.lang.IllegalStateException
- If this ResultSequence is not cached (isCached()
returns false) and the
index does not match the current cursor value, or if closed.XdmItem itemAt(int index)
XdmItem
wrapped by the ResultItem
at the given index.itemAt
in interface XdmSequence<ResultItem>
index
- The position (zero-based) of the ResultItem
to return.XdmItem
for the ResultItem
at the requested index.java.lang.IllegalArgumentException
- If index is negative or greater than or equal to size()
.java.lang.IllegalStateException
- If this ResultSequence is not cached (isCached()
returns false) and the
index xdoes not match the current cursor value, or if closed.void rewind()
ResultItem
in the sequence. This operation is only supported if isCached()
returns true.java.lang.IllegalStateException
- If called on a non-cached (streaming) ResultSequence (isCached()
returns
false).java.lang.IllegalStateException
- If this ResultSequence streaming or is closed.java.util.Iterator<ResultItem> iterator()
ResultItem
.iterator
in interface XdmSequence<ResultItem>
java.lang.IllegalStateException
- If this ResultSequence is closed.ResultSequence toCached()
isCached()
returns true), then nothing is done and this instance returns
itself. Otherwise, a new, cached ResultSequence instance is created and populated with the
XdmItem
s in the sequence. If the non-cached input
ResultSequence has been partially iterated, only the remaining
XdmItem
s will be cached. If the current item is not fetchable
(ResultItem.isFetchable()
returns false), it will be ignored.java.lang.IllegalStateException
- If this ResultSequence is closed.isCached()
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
.
ResultItem
instances, all of which will be cached.java.lang.IllegalStateException
- If this ResultSequence is closed.StreamingResultException
- If an IOException ocurrs while buffering a ResultItem
ResultSequence getChannel(ResultChannelName channel)
ResultSequence
for an alternate ResultChannelName
. The
ResultSequence
returned by Session.submitRequest(Request)
is the sequence of
XdmItem
s 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.channel
- An instance of ResultChannelName
that indicates which channel to return.ResultSequence
, possibly empty.java.lang.IllegalStateException
- If this ResultSequence is closed.java.lang.String toString()
XdmSequence.asString()
or XdmSequence.asStrings()
methods to
obtain String
representations of the item values.toString
in interface XdmSequence<ResultItem>
toString
in class java.lang.Object
XdmSequence.asString()
,
XdmSequence.asStrings()
Copyright © 2019 MarkLogic Corporation. All Rights Reserved.
Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com