zorba::XQuery
This class is the representation of an XQuery in the Zorba engine.
To compile and execute an XQuery, an instance of this class must be created. This is done by using either the createQuery or compileQuery methods of the Zorba class. These methods return an instance of XQuery_t, which is a reference counted smart pointer to a dynamically allocated XQuery object. After receiving an XQuery_t, an application can make multiple copies of it. Hence, an XQuery object can have multiple users, potentially in different threads. The XQuery object is deleted when all XQuery_t objects that point to it are destroyed.
The file simple.cpp contains some basic examples the demonstrate the use of this class.
Note: This class is reference counted. When writing multi-threaded clients, it is the responibility of the client code to synchronize assignments to the SmartPtr holding this object.
#include <zorba/xquery.h>
Inherited by: zorba::SmartObject
Public Functions
| const inline void | addReference() |
| const virtual XQuery_t | clone() Clone this query object in order to execute the query in another thread. |
| virtual void | close() Close the query and release all of its aquired ressources. |
| virtual void | compile( const String & aQuery ) Compile a query given as a String. |
| virtual void | compile( const String & aQuery, const Zorba_CompilerHints_t & aHints ) Compile a query given as a String, using the given compiler hints. |
| virtual void | compile( std::istream & aQuery, const Zorba_CompilerHints_t & aHints ) Compile a query given as an input stream, using the given compiler hints. |
| virtual void | compile( const String & aQuery, const StaticContext_t & aStaticContext, const Zorba_CompilerHints_t & aHints ) Compile a query given as a String, using a given static context and compiler hints. |
| virtual void | compile( std::istream & aQuery, const StaticContext_t & aStaticContext, const Zorba_CompilerHints_t & aHints ) Compile a query given as an input stream, using a given static context and compiler hints. |
| virtual void | execute( std::ostream & aOutStream, const Zorba_SerializerOptions_t * aSerOptions=NULL ) Execute the query and write the result to the given output stream. |
| virtual void | execute( std::ostream & aOutStream, itemHandler aCallbackFunction, void * aCallbackData, const Zorba_SerializerOptions_t * aSerOptions=NULL ) Execute the query and write the result to the given output stream. |
| virtual void | execute() Execute the (updating) query. |
| virtual void | executeSAX( SAX2_ContentHandler * aContentHandler ) Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that is given as input. |
| virtual void | executeSAX() Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that has been set using registerSAXHandler. |
| virtual void | free() |
| const virtual double | getDocLoadingTime() |
| const virtual double | getDocLoadingUserTime() |
| const virtual DynamicContext * | getDynamicContext() Get the dynamic context of this query. |
| const virtual void | getExternalVariables( Iterator_t & aVarsIter ) Returns the QName of all external variables. |
| const virtual std::string | getProfileName() Get the filename of the profile. |
| const inline long | getRefCount() |
| const virtual StaticCollectionManager * | getStaticCollectionManager() Returns a CollectionManager responsible for all collections which are statically declared in the static context of this query (main module) or any transitively imported library module. |
| const virtual const StaticContext * | getStaticContext() Get the static context of this query. |
| const virtual bool | isClosed() Check if this query object has already been closed. |
| const virtual bool | isSequential() Check if this query is a sequential query. |
| const virtual bool | isUpdating() Check if this query is an updating query. |
| virtual Iterator_t | iterator() Get an iterator for the result of the query. |
| virtual bool | loadExecutionPlan( std::istream & is, SerializationCallback * aCallback=0 ) Load execution plan. |
| virtual void | parse( std::istream & aQuery ) Parse the given query String. |
| const virtual void | printPlan( std::ostream & aStream, bool aDotFormat=false ) Print the execution plan of this query to the given output stream. |
| virtual void | registerDiagnosticHandler( DiagnosticHandler * aDiagnosticHandler ) Register an DiagnosticHandler to which errors during compilation or execution/serialization are reported. |
| virtual void | registerSAXHandler( SAX2_ContentHandler * aContentHandler ) Register a SAX2_ContentHandler for retrieving the serialized query result as SAX events when executeSAX() is called. |
| inline void | removeReference() |
| virtual void | resetDiagnosticHandler() Reset the error handling mechanism back to the default, i.e. behave as if no DiagnosticHandler had been set. |
| virtual bool | saveExecutionPlan( std::ostream & os, Zorba_binary_plan_format_t archive_format=ZORBA_USE_BINARY_ARCHIVE , Zorba_save_plan_options_t save_options=DONT_SAVE_UNUSED_FUNCTIONS ) Save the compiled execution plan. |
| virtual void | setFileName( const String & ) Set the filename of a query. |
| virtual void | setProfileName( std::string aProfileName ) Set the filename of the profile. |
| virtual void | setTimeout( long aTimeout=-1 ) Set a timeout, after which the execution of the query will be aborted. |
| inline virtual | ~XQuery() Destructor that destroys this XQuery object. |
Protected Attibutes
| unsigned int | theRefCount |
Public Functions
addReference
clone
Clone this query object in order to execute the query in another thread.
Although two or more threads may invoke one of the execute methods on the same XQuery object, these invocations are serialized internally. For true parallel excetution of a query by multiple threads, the XQuery object needs to be cloned, using this method. However, note that if an DiagnosticHandler has been provided by the user (see registerDiagnosticHandler()), this DiagnosticHandler will also be used in the cloned query, and as a result, the user should provide a thread-safe DiagnosticHandler. Alternatively, a new DiagnosticHandler can be registered in the cloned query by using registerDiagnosticHandler again. Or, the cloned query can be reset to use the default DiagnosticHandler (which just throws exceptions) by calling resetDiagnosticHandler.
This function also clones the StaticContext and DynamicContext of the XQuery object. In the DynamicContext of the cloned query different variable values can be used, e.g. set different external variable values. For an example of cloning a query and setting different values in the dynamic context see example_10 in file simple.cpp.
Returns
The cloned XQuery object.
Parameters
| SystemException |
if the query has not been compiled or is closed. |
close
Close the query and release all of its aquired ressources.
While a query is compiled and/or active, it holds on to a number of resources. Before Zorba can be safely shutdown, all resources must be released. For queries this can be done by calling close. However, if close is not called explicitly, it will be automatically called by the XQuery object's destructor, when the last smart pointer pointing this XQuery object is destroyed.
Note: After an XQuery object is closed, calling close() again on the same object is a noop. However, calling any method other than close() on a closed XQuery object is prohibited (an error will be raised).
Note: if an iterator has been created to retreive the result of an XQuery object (
Returns
iterator()), that itrator will be closed when the query is closed, and the association between XQuery object and Iterator object will be destroyed.
compile
Compile a query given as a String.
Parameters
| aQuery |
the query String to compile. |
Parameters
|
if the query has been closed, is already compiled, or an error occurs while compiling the query. |
compile
Compile a query given as a String, using the given compiler hints.
Parameters
| aQuery |
the query String to compile. |
| aHints |
hints passed to the query compiler. |
Parameters
|
if the query has been closed, is already compiled, or an error occurs while compiling the query. |
compile
Compile a query given as an input stream, using the given compiler hints.
Parameters
| aQuery |
the query input stream. |
| aHints |
hints passed to the query compiler. |
Parameters
|
if the query has been closed, is already compiled, or an error occurs while compiling the query. |
compile
const String & aQuery,
const StaticContext_t & aStaticContext,
const Zorba_CompilerHints_t & aHints
)
Compile a query given as a String, using a given static context and compiler hints.
Parameters
| aQuery |
the query String to compile. |
| aStaticContext |
the static context. |
| aHints |
hints passed to the query compiler. |
Parameters
|
if the query has been closed, is already compiled, or an error occurs while compiling the query. |
compile
std::istream & aQuery,
const StaticContext_t & aStaticContext,
const Zorba_CompilerHints_t & aHints
)
Compile a query given as an input stream, using a given static context and compiler hints.
Parameters
| aQuery |
the query input stream. |
| aStaticContext |
the static context. |
| aHints |
hints passed to the query compiler. |
Parameters
|
if the query has been closed, is already compiled, or an error occurs while compiling the query. |
execute
std::ostream & aOutStream,
const Zorba_SerializerOptions_t * aSerOptions=NULL
)
Execute the query and write the result to the given output stream.
The query only has a result if it's a non-updating query.
Parameters
| aOutStream |
the output stream on which the result is written. |
| aSerOptions |
an optional set of serialization options. |
Parameters
|
if an error occurs (e.g. the query is closed or has not been compiled) |
execute
std::ostream & aOutStream,
itemHandler aCallbackFunction,
void * aCallbackData,
const Zorba_SerializerOptions_t * aSerOptions=NULL
)
Execute the query and write the result to the given output stream.
A handler function gets called before the serialization of each item.
Parameters
| aOutStream |
the output stream on which the result is written. |
| aCallbackFunction |
a call back function which is called every time, before the serialization of an item. |
| aCallbackData |
data which is passed to the call back function. |
| aSerOptions |
Serializer options. |
Parameters
|
if an error occurs (e.g. the query is closed or has not been compiled) |
execute
Execute the (updating) query.
The query can be executed with this function only if it is an updating query.
Returns
Parameters
|
if an error occurs (e.g. the query is closed or has not been compiled or is not updating) |
executeSAX
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that is given as input.
Parameters
| aContentHandler |
the content handler on which SAX callbacks are called. |
executeSAX
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that has been set using registerSAXHandler.
Parameters
|
if an error occurs (e.g. no SAX2_ContentHandler has been registered). |
free
getDocLoadingTime
getDocLoadingUserTime
getDynamicContext
Get the dynamic context of this query.
This function returns the dynamic context that belongs to this query and is used during query execution. The context can be used, for example, to set values of external variables, the default collation, or the current datetime. It is only available if the query has been compiled, otherwise an error is reported. Moreover, the context must not be modified during the execution of a query (i.e. if a Iterator is opened). The lifetime of the context returned by this function is restricted by the lifetime of the according query object.
Parameters
| SystemException |
if the query has not been compiled or is closed. |
Returns
DynamicContext of this query.
getExternalVariables
Returns the QName of all external variables.
Parameters
| aVarsIter |
iterator to store the results. |
Parameters
|
if an error occured. |
getProfileName
Get the filename of the profile.
This file will contain the output of Zorba profiler.
getRefCount
getStaticCollectionManager
Returns a CollectionManager responsible for all collections which are statically declared in the static context of this query (main module) or any transitively imported library module.
The collection manager provides a set of functions for managing collections and their contents.
Returns
The collection manager responsible for managing collections of this query.
getStaticContext
Get the static context of this query.
This function returns the static context that belongs to this query. The static context is only available if the query has been compiled, otherwise an error is reported. The context has all the components and values that were set in the static context that was passed when creating the query and those that were set in the prolog of the query. Note that after compilation of the query the static context is a read only structure. Moreover, the lifetime of the context returned by this function is restricted by the lifetime of the corresponding query object.
Parameters
| SystemException |
if the query has not been compiled or is closed. |
Returns
StaticContext of this query.
isClosed
Check if this query object has already been closed.
Returns
true if the query has been closed already or false otherwise.
isSequential
Check if this query is a sequential query.
Returns
true if the query is a sequential query, false otherwise.
Parameters
| SystemException |
if the query is not compiled or has been closed. |
isUpdating
Check if this query is an updating query.
Returns
true if the query is an updating query, false otherwise.
Parameters
| SystemException |
if the query is not compiled or has been closed. |
iterator
Get an iterator for the result of the query.
Allows an application to lazily execute the query, retrieving the result one item at a time.
Returns
Iterator iterator over the result sequence.
Parameters
|
if an error occurs (e.g. the query is closed or has not been compiled). |
loadExecutionPlan
Load execution plan.
The serialized execution plan contains a general version for the entire archive and specific versions for each class. Zorba does not quarantee that it can load execution plans saved with previous versions of Zorba. In most cases there will be no problems, but the complete backward compatibility cannot be quaranteed.
The engine automatically detects the format of the input, either XML or binary.
Parameters
| is |
Reference to std::istream. |
| aCallback |
optional callback handler (see SerializationCallback) that is used to retrieve information that has not been serialized (e.g. external modules). |
Returns
true if success.
Parameters
|
if there are problems loading the execution plan. |
parse
std::istream & aQuery
)
Parse the given query String.
Parameters
| aQuery |
the query file to parse. |
Parameters
|
if an error occurs while parsing the query. |
printPlan
Print the execution plan of this query to the given output stream.
Parameters
| aStream |
the output stream to which the execution plan is printed |
| aDotFormat |
specifies the format of the printed execution plan. If this is true, then the execution plan is printed in the DOT format. If this is false, the plan is printed as XML. |
Parameters
|
if the query has been closed or is not compiled. |
registerDiagnosticHandler
Register an DiagnosticHandler to which errors during compilation or execution/serialization are reported.
If no DiagnosticHandler has been set via this function, the default error handling mechanism is to throw instances of the ZorbaException class.
Parameters
| aDiagnosticHandler |
DiagnosticHandler to which errors are reported. The caller retains ownership over the DiagnosticHandler passed as parameter. |
Parameters
| SystemException |
if the query has been closed. |
Returns
registerSAXHandler
Register a SAX2_ContentHandler for retrieving the serialized query result as SAX events when executeSAX() is called.
Parameters
| aContentHandler |
the content handler on which SAX callbacks are called. |
removeReference
resetDiagnosticHandler
Reset the error handling mechanism back to the default, i.e. behave as if no DiagnosticHandler had been set.
Parameters
| SystemException |
if the query has been closed already. |
saveExecutionPlan
std::ostream & os,
Zorba_binary_plan_format_t archive_format=ZORBA_USE_BINARY_ARCHIVE ,
Zorba_save_plan_options_t save_options=DONT_SAVE_UNUSED_FUNCTIONS
)
Save the compiled execution plan.
After compiling an XQuery program you can save the execution plan in some persistent storage. The execution plan is saved in a platform-independent format. You can later load this execution plan into a different XQuery object (potentially on a different machine) and execute it like it was compiled in place.
Parameters
| os |
The output stream into which the execution plan is saved. |
| archive_format |
Specify which output format to use. Possible values are ZORBA_USE_BINARY_ARCHIVE and ZORBA_USE_XML_ARCHIVE. The binary format is much smaller than XML format, but is not human readable. |
| save_options |
Specify some options to the plan serializer. Current possible values are:
|
Returns
true if success.
Parameters
|
if the query has not been compiled or there are problems serializing the execution plan. |
setFileName
Set the filename of a query.
This (after URI-encoding) becomes the encapsulating entity's retrieval URI (in RFC 3986 terms).
setProfileName
std::string aProfileName
)
Set the filename of the profile.
This file will contain the output of Zorba profiler.
setTimeout
long aTimeout=-1
)
Set a timeout, after which the execution of the query will be aborted.
Parameters
| aTimeout |
is an optional argument, which declares, that the execution of a query will be aborted after aTimeout number of seconds. If aTimeout is set to -1 (default), the query will never abort. |
~XQuery
Destructor that destroys this XQuery object.
The destructor is called automatically when there are no more XQuery_t smart pointers pointing to this XQuery instance.