Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Qizx/open 4.1 API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.qizx.api
Interface ItemSequence

All Superinterfaces:
  Item

    public interface ItemSequence

extends Item

Sequence of Items returned by the evaluation of a XQuery Expression.

It can be used as input if bound to a variable of an expression.

Attention: the expansion of a result sequence through moveToNextItem or moveTo can cause runtime errors (EvaluationException) due to lazy - or late - evaluation mechanisms used in Qizx.

Method Summary
`void` | `close()` Closes the sequence after use, and releases resources immediately, instead of waiting for this to happen automatically.
`long` | `countItems()` Returns the total number of items, without moving the current position.
`Item` | `getCurrentItem()` Returns the current item of the sequence.
`double` | `getFulltextScore()` Returns the full-text score, if applicable.
`long` | `getPosition()` Returns the current position.
`void` | `moveTo(long position)` Moves the current position to the specified value.
`boolean` | `moveToNextItem()` Moves to the next item.
`int` | `skip(int count)` Skips items in forward direction.

Methods inherited from interface com.qizx.api.Item
`export, exportNode, getBoolean, getDecimal, getDouble, getFloat, getInteger, getNode, getObject, getQName, getString, getType, isNode`

Method Detail

### moveToNextItem

    boolean moveToNextItem()
                           throws EvaluationException

  Moves to the next item. An iteration loop typically looks like this:

        ItemSequence seq = ...;
        while(seq.moveToNextItem()) {
            Item item = seq.getCurrentItem();
            // process item...
        }

  Attention: if access control is enabled, a result item belonging to a blocked document is silently discarded.

  Returns:
    true if another item has been found. The item is available through `getCurrentItem()`).
  Throws:
    `EvaluationException`

### getCurrentItem

    Item getCurrentItem()

  Returns the current item of the sequence. If the sequence is in an invalid state, the result is indetermined.

  Returns:
    a non-null Item.

### countItems

    long countItems()
                    throws EvaluationException

  Returns the total number of items, without moving the current position.

  Performs lazy evaluation if possible.

  This method does not take into account items rejected by Access Control (change from v2.1).

  Returns:
    the number of items as a long integer
  Throws:
    `EvaluationException` - if the expansion of the sequence caused a runtime error

### moveTo

    void moveTo(long position)
                throws EvaluationException

  Moves the current position to the specified value.

  Attention: if the sequence is returned by an XQuery expression evaluation, moving backwards involves reevaluating the expression and therefore can be inefficient and potentially have side-effects if extension functions are used in the expression.

  Parameters:
    `position` - number of items before desired position: moveTo(0) is equivalent to rewind.
  Throws:
    `EvaluationException` - if the expansion of the sequence caused a runtime error

### getPosition

    long getPosition()

  Returns the current position. Position 0 corresponds to "before first", position N means just after the N-th item (which is available through `getCurrentItem()`).

  Returns:
    the current item position, 0 initially

### getFulltextScore

    double getFulltextScore()
                            throws EvaluationException

  Returns the full-text score, if applicable.

  If this sequence is produced by evaluating an XQuery expression that contains a `ftcontains` operator, then the value returned is the score of the current document evaluated against the top-level full-text selection. Otherwise the value returned is 0.

  This is the value returned by the score clause of `for` and `let`.

  Returns:
    a value between 0 and 1 which represents the score of the current document evaluated against the `ftcontains` expression.
  Throws:
    `EvaluationException`

### skip

    int skip(int count)
             throws EvaluationException

  Skips items in forward direction.

  Performs lazy evaluation if possible.

  Parameters:
    `count` - number of items to skip. Must be >= 0 otherwise ignored.
  Returns:
    the actual number of skipped items: smaller than `count` if the end of the sequence is reached.
  Throws:
    `EvaluationException` - if the expansion of the sequence caused a runtime error

### close

    void close()

  Closes the sequence after use, and releases resources immediately, instead of waiting for this to happen automatically.

  It is recommended to call this method when a sequence is no more needed. Failing to do so could result into errors due to an excess of used up resources.

  The sequence can no more be used after calling this method. Calling this method twice has no effect.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| © 2010 Axyana Software
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD