Qizx fe-4.4p2 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 bindImplicitCollection(LibraryMember root)
          Defines the Implicit Collection, as a Collection or Document.
 void bindImplicitCollection(LibraryMemberIterator roots)
          Defines the Implicit Collection as a set of Documents defined by a query.
 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().
 void close()
          Releases all resources used by this expression.
 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 '.'.
 String getIdentifier()
          Returns a unique identifier of the expression.
 Library getLibrary()
          Returns the XML Library of the compiled expression.
 List<Profiling> getProfilingAnnotations()
          Returns a list of profiling annotations if the expression was executed by profile(), else null.
 String[] getRootPaths()
          Returns a list of document or collection paths used as roots of Path-Expressions.
 XQuerySession getSession()
          Returns the Session of the compiled expression.
 String getSource()
          Returns the source code of the compiled expression.
 int getSpaceLimit()
          Returns the maximum space allowed for evaluation of the expression.
 long getStartTime()
          Returns the start time of the running evaluation.
 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.
 boolean isClosed()
          Returns true if expression was closed by method close().
 boolean isProfiled()
          Returns true if the expression was executed by profile().
 boolean isUpdating()
          Returns true if the Expression updates a database or more generally the context.
 ItemSequence profile()
          Evaluation of the expression, returns a sequence of Items.
 void setCurrentItem(Item item)
          Sets the initial value of the current item, accessible by the expression '.'.
 void setSpaceLimit(int limit)
          Defines a maximum for memory space used by evaluation.
 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.

getIdentifier

String getIdentifier()
Returns a unique identifier of the expression. This identifier is unique within the LibraryManager or the SessionManager.


getSession

XQuerySession getSession()
Returns the Session of the compiled expression.

Since:
4.3

getLibrary

Library getLibrary()
Returns the XML Library of the compiled expression. Returns null if the expression was not compiled from an XML Library session.

Since:
4.3

getSource

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

Since:
4.0

getStaticType

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

Since:
3.1

isUpdating

boolean isUpdating()
Returns true if the Expression updates a database or more generally the context. The expression might use XQuery Update operators, or extension functions.


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 (null not accepted)
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 (null not accepted).
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.

If value null is passed, then the variable is unbound.

Parameters:
varName - name of a variable declared in the prolog of the XQuery expression.
value - object to convert to XQuery value. If value null is passed, then the variable is unbound.
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.

bindImplicitCollection

void bindImplicitCollection(LibraryMember root)
                            throws DataModelException
Defines the Implicit Collection, as a Collection or Document.

This method allows reusing the same query on different collections or documents of a Library.

Parameters:
root - a Document or a Collection, used as implicit root for path expressions.
Throws:
DataModelException - common causes

bindImplicitCollection

void bindImplicitCollection(LibraryMemberIterator roots)
                            throws EvaluationException,
                                   DataModelException
Defines the Implicit Collection as a set of Documents defined by a query.

This is a powerful mechanism allowing queries to be restricted to a set of documents defined by their properties, or the properties of enclosing collections.

The iterator passed as argument can be obtained by calling queryProperties or getChildren on a Collection (typically the root collection). If a Collection is enumerated by the iterator, all its enclosed documents at any level are added to the Implicit Collection.

Attention: the iterator is consumed by this method. It cannot be reused.

Parameters:
roots - a sequence of Documents or Collections
Throws:
EvaluationException - if the enumeration of library members causes a runtime error
DataModelException - common causes

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

profile

ItemSequence profile()
                     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).


getStartTime

long getStartTime()
Returns the start time of the running evaluation.

If the Expression is currently executing (methods evaluate() or profile()), or iterating on the returned ItemSequence, the returned value is a time-stamp in milliseconds, otherwise if the Expression is not being executed, the returned value is 0.


close

void close()
Releases all resources used by this expression.

The expression can no more be used afterwards.


isClosed

boolean isClosed()
Returns true if expression was closed by method close().


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.

getSpaceLimit

int getSpaceLimit()
Returns the maximum space allowed for evaluation of the expression. setSpaceLimit(int). By default, this value is 0, meaning no limit.

Returns:
an int representing the current space limit in bytes

setSpaceLimit

void setSpaceLimit(int limit)
Defines a maximum for memory space used by evaluation. The purpose is to prevent some Expressions to hog the resources of the XQuery engine.

Notice this is approximative: the XQuery engine does its best effort to track the total memory and resources used by an evaluation, but this is a fairly complex task since many resources are cached or shared.

Parameters:
limit - limit in bytes. A value <= 0 means no limit.

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

getRootPaths

String[] getRootPaths()
Returns a list of document or collection paths used as roots of Path-Expressions.


isProfiled

boolean isProfiled()
Returns true if the expression was executed by profile().


getProfilingAnnotations

List<Profiling> getProfilingAnnotations()
Returns a list of profiling annotations if the expression was executed by profile(), else null.


© 2010 Axyana Software