Qizx/open 4.1 API

com.qizx.api
Interface Expression

All Superinterfaces:
ItemFactory

public interface Expression
extends ItemFactory

Compiled XML Query expression.

An Expression is created with the compileExpression method of Library or XQuerySession.

Once compiled, an Expression can be evaluated several times. Preparing an Expression for execution involves optional operations like:

Execution can be aborted by cancelEvaluation() or by a time-out (see setTimeOut).

This class is not thread safe (an Expression is built from an XQuery session which is itself not thread safe).


Method Summary
 void bindImplicitCollection(ItemSequence nodes)
          Defines the Implicit Collection as a set of Nodes defined by a sequence (see above for a definition of Implicit Collection).
 void bindVariable(QName varName, boolean value)
          Binds a variable to a sequence made of a single boolean value.
 void bindVariable(QName varName, double value)
          Binds a variable to a sequence made of a single item of type xs:double.
 void bindVariable(QName varName, float value)
          Binds a variable to a sequence made of a single item of type xs:float.
 void bindVariable(QName varName, Item value)
          Binds a variable to a sequence made of a single item.
 void bindVariable(QName varName, ItemSequence value)
          Binds a variable to a sequence.
 void bindVariable(QName varName, long value, ItemType type)
          Binds a variable to a value obtained by converting a long integer to an Item.
 void bindVariable(QName varName, Object value, ItemType type)
          Binds a variable to a value obtained by converting a Java object to an Item or a ItemSequence, according to the general Java to XQuery type mapping (see the documentation for details).
 void cancelEvaluation()
          Cancels the evaluation started by evaluate().
 ItemSequence evaluate()
          Evaluation of the expression, returns a sequence of Items.
 XQueryContext getContext()
          Access to the XQuery Context.
 Item getCurrentItem()
          Gets the initial value of the current item, accessible by the expression '.'.
 Object getProperty(String name)
          Gets a property set by setProperty.
 String getSource()
          Returns the source code of the compiled expression.
 SequenceType getStaticType()
          Returns the static (or formal) type of the compiled expression.
 int getTimeOut()
          Returns the maximum evaluation time, as defined by setTimeOut(int).
 TraceObserver getTraceObserver()
          Gets the listener used to receive evaluation traces.
 void setCurrentItem(Item item)
          Sets the initial value of the current item, accessible by the expression '.'.
 void setProperty(String name, Object value)
          Sets a property which can be used by extension functions.
 void setTimeOut(int maxTime)
          Defines a maximum time for evaluation.
 void setTraceObserver(TraceObserver listener)
          Sets a listener to receive evaluation traces.
 
Methods inherited from interface com.qizx.api.ItemFactory
copySequence, createItem, createItem, createItem, createItem, createItem, createItem, createItem, createSequence, getNodeType, getQName, getQName, getQName, getType
 

Method Detail

getContext

XQueryContext getContext()
Access to the XQuery Context.

Returns:
the XQuery Context of this expression. This context is initially defined by the context of the XQuery session (or Library) and by the expression itself. It can be modified before each execution.

getStaticType

SequenceType getStaticType()
Returns the static (or formal) type of the compiled expression.

Since:
3.1

getSource

String getSource()
Returns the source code of the compiled expression.

Since:
4.0

bindVariable

void bindVariable(QName varName,
                  Item value)
                  throws CompilationException
Binds a variable to a sequence made of a single item.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - an item create by ItemFactory or obtained from an ItemSequence
Throws:
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  ItemSequence value)
                  throws CompilationException
Binds a variable to a sequence.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - sequence bound to the variable, it is first cloned.
Throws:
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  boolean value)
                  throws CompilationException
Binds a variable to a sequence made of a single boolean value.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - boolean value
Throws:
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  long value,
                  ItemType type)
                  throws CompilationException,
                         EvaluationException
Binds a variable to a value obtained by converting a long integer to an Item.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - a long integer value
type - optional type. If non null, the value is converted to this type. If null, the default type xs:integer is used.
Throws:
EvaluationException - if the type is invalid
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  double value)
                  throws CompilationException
Binds a variable to a sequence made of a single item of type xs:double.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - double value
Throws:
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  float value)
                  throws CompilationException
Binds a variable to a sequence made of a single item of type xs:float.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - float value
Throws:
CompilationException - if the variable name is not declared as global in the expression.

bindVariable

void bindVariable(QName varName,
                  Object value,
                  ItemType type)
                  throws CompilationException,
                         EvaluationException
Binds a variable to a value obtained by converting a Java object to an Item or a ItemSequence, according to the general Java to XQuery type mapping (see the documentation for details). The object can be an array: it will be converted to a Sequence.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - object to convert to XQuery value
type - optional type. If non null, the object (or its items) will be converted to this type. If null, the object will be converted to the most general applicable type: for example a Java String to xs:string type, an array of double to a sequence of xs:double and so on.
Throws:
EvaluationException - if the conversion cannot be performed
CompilationException - if the variable name is not declared as global in the expression.

bindImplicitCollection

void bindImplicitCollection(ItemSequence nodes)
                            throws EvaluationException
Defines the Implicit Collection as a set of Nodes defined by a sequence (see above for a definition of Implicit Collection).

Parameters:
nodes - a sequence of Nodes
Throws:
EvaluationException - if one of the items in the sequence is not a node, or if the enumeration of the sequence causes a runtime error.

setCurrentItem

void setCurrentItem(Item item)
Sets the initial value of the current item, accessible by the expression '.'.

Parameters:
item - the current item. If the value is null, the current item becomes undefined.

getCurrentItem

Item getCurrentItem()
Gets the initial value of the current item, accessible by the expression '.'.

Returns:
the current item set by setCurrentItem.

evaluate

ItemSequence evaluate()
                      throws EvaluationException
Evaluation of the expression, returns a sequence of Items.

Returns:
a sequence of Items which is the result of the evaluation
Throws:
EvaluationException - thrown by an XQuery dynamic error

cancelEvaluation

void cancelEvaluation()
Cancels the evaluation started by evaluate(). Most likely called from a different thread than the evaluation thread (where evaluate is called).


getTimeOut

int getTimeOut()
Returns the maximum evaluation time, as defined by setTimeOut(int). By default, this value is 0, meaning no time limit.

Returns:
an int representing the current time out value in milliseconds

setTimeOut

void setTimeOut(int maxTime)
Defines a maximum time for evaluation. If this time is defined and exceeded, the evaluation aborts with a "TIME0000" error code.

Parameters:
maxTime - maximum execution time in milliseconds. A value <= 0 can be used to specify an unlimited time.

setTraceObserver

void setTraceObserver(TraceObserver listener)
Sets a listener to receive evaluation traces.

Parameters:
listener - an implementation of TraceObserver whose method trace is called each time the fn:trace is called in the expression.

getTraceObserver

TraceObserver getTraceObserver()
Gets the listener used to receive evaluation traces.

Returns:
the trace observer set by setTraceObserver, or null by default

getProperty

Object getProperty(String name)
Gets a property set by setProperty.

Parameters:
name - name of the property
Returns:
value of the property

setProperty

void setProperty(String name,
                 Object value)
Sets a property which can be used by extension functions.

Parameters:
name - name of the property
value - value of the property

© 2010 Axyana Software