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.
long	getPosition() Returns the current position.
void	moveTo(int 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

public 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

public 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

public long countItems()
                throws EvaluationException

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

Performs lazy evaluation if possible.

Attention: this method does not take into account the access control. The value returned can therefore be higher than the actual count, because some items can be silently discarded due to access control.

Returns:

the number of items as a long integer

Throws:

EvaluationException - if the expansion of the sequence caused a runtime error

moveTo

public void moveTo(int 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

public 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

skip

public 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

public 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.