Qizx/open 4.1 API

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.


© 2010 Axyana Software