Qizx fe-4.4p2 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.
 long estimatedDocumentCount()
          Returns an estimation of the number of Documents returned by this sequence.
 long estimatedDocumentCount(int minimalPosition)
          Returns an estimation of the number of Documents returned by this sequence.
 Item getCurrentItem()
          Returns the current item of the sequence.
 Expression getExpression()
          Returns the Expression the evaluation of which this sequence is the result.
 double getFulltextScore()
          Returns the full-text score, if applicable.
 long getPosition()
          Returns the current position.
 List<Profiling> getProfilingAnnotations()
          Returns a list of Profiling annotations when the query was executed through the profile() method.
 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.

Uses lazy evaluation if possible.

This method does not take into account items forbidden 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

estimatedDocumentCount

long estimatedDocumentCount()
                            throws EvaluationException
Returns an estimation of the number of Documents returned by this sequence. This method can be used when an exact count of all results would be too long to compute. It is designed to work on collections of millions of documents.

The value returned by this method is the same as calling estimatedDocumentCount(int) with an argument of 100. See the latter method for more details.

This method is cached, i.e it does not recompute the value if called several times.

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

estimatedDocumentCount

long estimatedDocumentCount(int minimalPosition)
                            throws EvaluationException
Returns an estimation of the number of Documents returned by this sequence. This method can be used when an exact count of all results would be too long to compute. It is designed to work on collections of millions of documents.

The estimated count provided by this method is valid under the following conditions:

This method uses the current position and the 'minimalPosition' argument to estimate the count. A higher value of minimalPosition will provide a more accurate estimation, at the cost of a higher computation time.

Parameters:
minimalPosition - the minimal position to reach before doint the estimation
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.


getExpression

Expression getExpression()
Returns the Expression the evaluation of which this sequence is the result.

When the sequence is not the result of Expression.evaluate(), this method returns null.

Returns:
an Expression or null

getProfilingAnnotations

List<Profiling> getProfilingAnnotations()
Returns a list of Profiling annotations when the query was executed through the profile() method. In embedded mode, this means simply calling getProfilingAnnotations() on the related Expression.


© 2010 Axyana Software