This class is the representation of an XQuery in the Zorba engine. More...
#include <zorba/xquery.h>
Public Member Functions | |
void | addReference () const |
virtual XQuery_t | clone () const =0 |
Clone this query object in order to execute the query in another thread. | |
virtual void | close ()=0 |
Close the query and release all of its aquired ressources. | |
virtual void | compile (const String &aQuery)=0 |
Compile a query given as a String. | |
virtual void | compile (const String &aQuery, const Zorba_CompilerHints_t &aHints)=0 |
Compile a query given as a String, using the given compiler hints. | |
virtual void | compile (std::istream &aQuery, const Zorba_CompilerHints_t &aHints)=0 |
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)=0 |
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)=0 |
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)=0 |
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)=0 |
Execute the query and write the result to the given output stream. | |
virtual void | execute ()=0 |
Execute the (updating) query. | |
virtual void | executeSAX (SAX2_ContentHandler *aContentHandler)=0 |
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that is given as input. | |
virtual void | executeSAX ()=0 |
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that has been set using registerSAXHandler. | |
virtual void | free () |
virtual double | getDocLoadingTime () const =0 |
virtual double | getDocLoadingUserTime () const =0 |
virtual DynamicContext * | getDynamicContext () const =0 |
Get the dynamic context of this query. | |
virtual void | getExternalVariables (Iterator_t &aVarsIter) const =0 |
Returns the QName of all external variables. | |
virtual std::string | getProfileName () const =0 |
Get the filename of the profile. | |
long | getRefCount () const |
virtual StaticCollectionManager * | getStaticCollectionManager () const =0 |
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. | |
virtual const StaticContext * | getStaticContext () const =0 |
Get the static context of this query. | |
virtual bool | isClosed () const =0 |
Check if this query object has already been closed. | |
virtual bool | isSequential () const =0 |
Check if this query is a sequential query. | |
virtual bool | isUpdating () const =0 |
Check if this query is an updating query. | |
virtual Iterator_t | iterator ()=0 |
Get an iterator for the result of the query. | |
virtual bool | loadExecutionPlan (std::istream &is, SerializationCallback *aCallback=0)=0 |
Load execution plan. | |
virtual void | parse (std::istream &aQuery)=0 |
Parse the given query String. | |
virtual void | printPlan (std::ostream &aStream, bool aDotFormat=false) const =0 |
Print the execution plan of this query to the given output stream. | |
virtual void | registerDiagnosticHandler (DiagnosticHandler *aDiagnosticHandler)=0 |
Register an DiagnosticHandler to which errors during compilation or execution/serialization are reported. | |
virtual void | registerSAXHandler (SAX2_ContentHandler *aContentHandler)=0 |
Register a SAX2_ContentHandler for retrieving the serialized query result as SAX events when executeSAX() is called. | |
void | removeReference () |
virtual void | resetDiagnosticHandler ()=0 |
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)=0 |
Save the compiled execution plan. | |
virtual void | setFileName (const String &)=0 |
Set the filename of a query. | |
virtual void | setProfileName (std::string aProfileName)=0 |
Set the filename of the profile. | |
virtual void | setTimeout (long aTimeout=-1)=0 |
Set a timeout, after which the execution of the query will be aborted. | |
virtual | ~XQuery () |
Destructor that destroys this XQuery object. | |
Protected Attributes | |
unsigned int | theRefCount |
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.
virtual zorba::XQuery::~XQuery | ( | ) | [inline, virtual] |
void zorba::SmartObject::addReference | ( | ) | const [inline, inherited] |
Definition at line 40 of file smart_ptr.h.
virtual XQuery_t zorba::XQuery::clone | ( | ) | const [pure virtual] |
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.
SystemException | if the query has not been compiled or is closed. |
virtual void zorba::XQuery::close | ( | ) | [pure virtual] |
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 (
virtual void zorba::XQuery::compile | ( | const String & | aQuery | ) | [pure virtual] |
Compile a query given as a String.
aQuery | the query String to compile. |
ZorbaException | if the query has been closed, is already compiled, or an error occurs while compiling the query. |
virtual void zorba::XQuery::compile | ( | const String & | aQuery, |
const Zorba_CompilerHints_t & | aHints | ||
) | [pure virtual] |
Compile a query given as a String, using the given compiler hints.
aQuery | the query String to compile. |
aHints | hints passed to the query compiler. |
ZorbaException | if the query has been closed, is already compiled, or an error occurs while compiling the query. |
virtual void zorba::XQuery::compile | ( | std::istream & | aQuery, |
const Zorba_CompilerHints_t & | aHints | ||
) | [pure virtual] |
Compile a query given as an input stream, using the given compiler hints.
aQuery | the query input stream. |
aHints | hints passed to the query compiler. |
ZorbaException | if the query has been closed, is already compiled, or an error occurs while compiling the query. |
virtual void zorba::XQuery::compile | ( | const String & | aQuery, |
const StaticContext_t & | aStaticContext, | ||
const Zorba_CompilerHints_t & | aHints | ||
) | [pure virtual] |
Compile a query given as a String, using a given static context and compiler hints.
aQuery | the query String to compile. |
aStaticContext | the static context. |
aHints | hints passed to the query compiler. |
ZorbaException | if the query has been closed, is already compiled, or an error occurs while compiling the query. |
virtual void zorba::XQuery::compile | ( | std::istream & | aQuery, |
const StaticContext_t & | aStaticContext, | ||
const Zorba_CompilerHints_t & | aHints | ||
) | [pure virtual] |
Compile a query given as an input stream, using a given static context and compiler hints.
aQuery | the query input stream. |
aStaticContext | the static context. |
aHints | hints passed to the query compiler. |
ZorbaException | if the query has been closed, is already compiled, or an error occurs while compiling the query. |
virtual void zorba::XQuery::execute | ( | std::ostream & | aOutStream, |
const Zorba_SerializerOptions_t * | aSerOptions = NULL |
||
) | [pure virtual] |
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.
aOutStream | the output stream on which the result is written. |
aSerOptions | an optional set of serialization options. |
ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled) |
virtual void zorba::XQuery::execute | ( | std::ostream & | aOutStream, |
itemHandler | aCallbackFunction, | ||
void * | aCallbackData, | ||
const Zorba_SerializerOptions_t * | aSerOptions = NULL |
||
) | [pure virtual] |
Execute the query and write the result to the given output stream.
A handler function gets called before the serialization of each item.
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. |
ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled) |
virtual void zorba::XQuery::execute | ( | ) | [pure virtual] |
Execute the (updating) query.
The query can be executed with this function only if it is an updating query.
ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled or is not updating) |
virtual void zorba::XQuery::executeSAX | ( | SAX2_ContentHandler * | aContentHandler | ) | [pure virtual] |
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that is given as input.
aContentHandler | the content handler on which SAX callbacks are called. |
virtual void zorba::XQuery::executeSAX | ( | ) | [pure virtual] |
Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that has been set using registerSAXHandler.
ZorbaException | if an error occurs (e.g. no SAX2_ContentHandler has been registered). |
virtual void zorba::SmartObject::free | ( | ) | [virtual, inherited] |
virtual double zorba::XQuery::getDocLoadingTime | ( | ) | const [pure virtual] |
virtual double zorba::XQuery::getDocLoadingUserTime | ( | ) | const [pure virtual] |
virtual DynamicContext* zorba::XQuery::getDynamicContext | ( | ) | const [pure virtual] |
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.
SystemException | if the query has not been compiled or is closed. |
virtual void zorba::XQuery::getExternalVariables | ( | Iterator_t & | aVarsIter | ) | const [pure virtual] |
Returns the QName of all external variables.
aVarsIter | iterator to store the results. |
ZorbaException | if an error occured. |
virtual std::string zorba::XQuery::getProfileName | ( | ) | const [pure virtual] |
Get the filename of the profile.
This file will contain the output of Zorba profiler.
long zorba::SmartObject::getRefCount | ( | ) | const [inline, inherited] |
Definition at line 38 of file smart_ptr.h.
virtual StaticCollectionManager* zorba::XQuery::getStaticCollectionManager | ( | ) | const [pure virtual] |
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.
virtual const StaticContext* zorba::XQuery::getStaticContext | ( | ) | const [pure virtual] |
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.
SystemException | if the query has not been compiled or is closed. |
virtual bool zorba::XQuery::isClosed | ( | ) | const [pure virtual] |
Check if this query object has already been closed.
virtual bool zorba::XQuery::isSequential | ( | ) | const [pure virtual] |
virtual bool zorba::XQuery::isUpdating | ( | ) | const [pure virtual] |
virtual Iterator_t zorba::XQuery::iterator | ( | ) | [pure virtual] |
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.
ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled). |
virtual bool zorba::XQuery::loadExecutionPlan | ( | std::istream & | is, |
SerializationCallback * | aCallback = 0 |
||
) | [pure virtual] |
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.
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). |
ZorbaException | if there are problems loading the execution plan. |
virtual void zorba::XQuery::parse | ( | std::istream & | aQuery | ) | [pure virtual] |
Parse the given query String.
aQuery | the query file to parse. |
ZorbaException | if an error occurs while parsing the query. |
virtual void zorba::XQuery::printPlan | ( | std::ostream & | aStream, |
bool | aDotFormat = false |
||
) | const [pure virtual] |
Print the execution plan of this query to the given output stream.
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. |
ZorbaException | if the query has been closed or is not compiled. |
virtual void zorba::XQuery::registerDiagnosticHandler | ( | DiagnosticHandler * | aDiagnosticHandler | ) | [pure virtual] |
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.
aDiagnosticHandler | DiagnosticHandler to which errors are reported. The caller retains ownership over the DiagnosticHandler passed as parameter. |
SystemException | if the query has been closed. |
virtual void zorba::XQuery::registerSAXHandler | ( | SAX2_ContentHandler * | aContentHandler | ) | [pure virtual] |
Register a SAX2_ContentHandler for retrieving the serialized query result as SAX events when executeSAX() is called.
aContentHandler | the content handler on which SAX callbacks are called. |
void zorba::SmartObject::removeReference | ( | ) | [inline, inherited] |
Definition at line 42 of file smart_ptr.h.
virtual void zorba::XQuery::resetDiagnosticHandler | ( | ) | [pure virtual] |
Reset the error handling mechanism back to the default, i.e. behave as if no DiagnosticHandler had been set.
SystemException | if the query has been closed already. |
virtual bool zorba::XQuery::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 |
||
) | [pure virtual] |
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.
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:
|
ZorbaException | if the query has not been compiled or there are problems serializing the execution plan. |
virtual void zorba::XQuery::setFileName | ( | const String & | ) | [pure virtual] |
Set the filename of a query.
This (after URI-encoding) becomes the encapsulating entity's retrieval URI (in RFC 3986 terms).
virtual void zorba::XQuery::setProfileName | ( | std::string | aProfileName | ) | [pure virtual] |
Set the filename of the profile.
This file will contain the output of Zorba profiler.
virtual void zorba::XQuery::setTimeout | ( | long | aTimeout = -1 | ) | [pure virtual] |
Set a timeout, after which the execution of the query will be aborted.
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. |
unsigned int zorba::SmartObject::theRefCount [mutable, protected, inherited] |
Definition at line 27 of file smart_ptr.h.