com.marklogic.xcc

## Interface ResultSequence

- All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable, XdmSequence<ResultItem>, XdmValue

      public interface ResultSequence
      extends XdmSequence<ResultItem>, java.io.Closeable

  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.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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.

    - ### 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

          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.

      Specified by:
        `size` in interface `XdmSequence<ResultItem>`
      Returns:
        The size, if this ResultSequence is cached, otherwise -1.

    - #### isCached

          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

          void close()

      Release any resources being held by this ResultSequence. If cached, this is a no-op an the cached `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.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`

    - #### isClosed

          boolean isClosed()

      Indicates whether this ResultSequence is closed.
      Returns:
        true if closed, false if open.

    - #### hasNext

          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

          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:
        `java.lang.IllegalStateException` - If this ResultSequence is closed.

    - #### current

          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.

      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:
        `java.lang.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

          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.

      Parameters:
        `index` - The position (zero-based) of the `ResultItem` to return.
      Returns:
        The `ResultItem` at the given index.
      Throws:
        `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.

    - #### itemAt

          XdmItem itemAt(int index)

      Returns the `XdmItem` wrapped by the `ResultItem` at the given index.
      Specified by:
        `itemAt` in interface `XdmSequence<ResultItem>`
      Parameters:
        `index` - The position (zero-based) of the `ResultItem` to return.
      Returns:
        The underlying `XdmItem` for the `ResultItem` at the requested index.
      Throws:
        `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.

    - #### rewind

          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:
        `java.lang.IllegalStateException` - If called on a non-cached (streaming) ResultSequence (`isCached()` returns false).
        `java.lang.IllegalStateException` - If this ResultSequence streaming or is closed.

    - #### iterator

          java.util.Iterator<ResultItem> 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<ResultItem>`
      Returns:
        An Iterator instance for this ResultSequence.
      Throws:
        `java.lang.IllegalStateException` - If this ResultSequence is closed.

    - #### toCached

          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 `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.
      Returns:
        A Cached ResultSequence.
      Throws:
        `java.lang.IllegalStateException` - If this ResultSequence is closed.
      See Also:
        `isCached()`

    - #### toResultItemArray

          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:
        `java.lang.IllegalStateException` - If this ResultSequence is closed.
        `StreamingResultException` - If an IOException ocurrs while buffering a `ResultItem`

    - #### getChannel

          ResultSequence getChannel(ResultChannelName channel)

      Return the `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.
      Parameters:
        `channel` - An instance of `ResultChannelName` that indicates which channel to return.
      Returns:
        An instance of `ResultSequence`, possibly empty.
      Throws:
        `java.lang.IllegalStateException` - If this ResultSequence is closed.

    - #### toString

          java.lang.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<ResultItem>`
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        A textual description of this object, appropriate for use in a debug or log message.
      See Also:
        `XdmSequence.asString()`, `XdmSequence.asStrings()`

Copyright © 2025 MarkLogic Corporation. All Rights Reserved.

Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com