|
Qizx fe-4.4p2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Expression
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:
getContext()
For example the path expression //foo/bar
has no explicit
root. Supposing that the collection /a/b has been bound as Implicit
Collection in this expression, its evaluation is equivalent to the
evaluation of the path expression collection("/a/b")//foo/bar
.
The implicit collection is also the Default Collection defined by
the XQuery specifications: in the example above, using
collection()//foo/bar
is equivalent to use
//foo/bar
.
This allows reusing the same query on different collections or documents of a Library.
TraceObserver
.
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 |
---|
XQueryContext getContext()
String getIdentifier()
XQuerySession getSession()
Library getLibrary()
String getSource()
SequenceType getStaticType()
boolean isUpdating()
void bindVariable(QName varName, Item value) throws CompilationException
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)
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, ItemSequence value) throws CompilationException
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).
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, boolean value) throws CompilationException
varName
- name of a variable declared in the prolog of the XQuery
expression.value
- boolean value
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, long value, ItemType type) throws CompilationException, EvaluationException
varName
- name of a variable declared in the prolog of the XQuery
expression.value
- a long integer valuetype
- optional type. If non null, the value is converted to this type.
If null, the default type xs:integer is used.
EvaluationException
- if the type is invalid
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, double value) throws CompilationException
varName
- name of a variable declared in the prolog of the XQuery
expression.value
- double value
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, float value) throws CompilationException
varName
- name of a variable declared in the prolog of the XQuery
expression.value
- float value
CompilationException
- if the variable name is not declared as
global in the expression.void bindVariable(QName varName, Object value, ItemType type) throws CompilationException, EvaluationException
The object can be an array: it will be converted to a Sequence.
If value null is passed, then the variable is unbound.
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.
EvaluationException
- if the conversion cannot be performed
CompilationException
- if the variable name is not declared as global
in the expression.void bindImplicitCollection(ItemSequence nodes) throws EvaluationException
nodes
- a sequence of Nodes
EvaluationException
- if one of the items in the sequence is not
a node, or if the enumeration of the sequence causes a runtime error.void bindImplicitCollection(LibraryMember root) throws DataModelException
This method allows reusing the same query on different collections or documents of a Library.
root
- a Document or a Collection, used as implicit root for
path expressions.
DataModelException
- common causesvoid bindImplicitCollection(LibraryMemberIterator roots) throws EvaluationException, DataModelException
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.
roots
- a sequence of Documents or Collections
EvaluationException
- if the enumeration of library members causes
a runtime error
DataModelException
- common causesvoid setCurrentItem(Item item)
item
- the current item. If the value is null, the current item
becomes undefined.Item getCurrentItem()
ItemSequence evaluate() throws EvaluationException
EvaluationException
- thrown by an XQuery dynamic errorItemSequence profile() throws EvaluationException
EvaluationException
- thrown by an XQuery dynamic errorvoid cancelEvaluation()
evaluate()
.
Most likely called from a different thread than the evaluation
thread (where evaluate is called).
long getStartTime()
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.
void close()
The expression can no more be used afterwards.
boolean isClosed()
close()
.
int getTimeOut()
setTimeOut(int)
. By default, this value is 0, meaning no time
limit.
void setTimeOut(int maxTime)
maxTime
- maximum execution time in milliseconds. A value <= 0 can
be used to specify an unlimited time.int getSpaceLimit()
setSpaceLimit(int)
. By default, this value is 0, meaning no limit.
void setSpaceLimit(int limit)
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.
limit
- limit in bytes. A value <= 0 means no limit.void setTraceObserver(TraceObserver listener)
listener
- an implementation of TraceObserver whose method trace
is called each time the fn:trace is called in the expression.TraceObserver getTraceObserver()
String[] getRootPaths()
boolean isProfiled()
profile()
.
List<Profiling> getProfilingAnnotations()
profile()
, else null.
|
© 2010 Axyana Software | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |