> The XQuery Processor
#include <zorba/xquery.h>
Public Types | |
| typedef struct zorba::XQuery::CompilerHints | CompilerHints_t |
| typedef struct zorba::XQuery::SerializerOptions | SerializerOptions_t |
Public Member Functions | |
| virtual void | applyUpdates ()=0 |
| Apply/execute the query if it is an updating query. | |
| virtual XQuery_t | clone () const =0 |
| Clone this query object for executing it in another thread. | |
| virtual void | close ()=0 |
| Close the query and release all aquired ressources. | |
| virtual void | compile (std::istream &aQuery, const StaticContext_t &aStaticContext, const XQuery::CompilerHints_t &aHints)=0 |
| Compile the query given as an input stream with the given static context and the given compiler hints. | |
| virtual void | compile (const String &aQuery, const StaticContext_t &aStaticContext, const XQuery::CompilerHints_t &aHints)=0 |
| Compile the give query String with the given static context and the given compiler hints. | |
| virtual void | compile (std::istream &aQuery, const XQuery::CompilerHints_t &aHints)=0 |
| Compile the query given as an input stream with the given compiler hints. | |
| virtual void | compile (const String &aQuery, const XQuery::CompilerHints_t &aHints)=0 |
| Compile the give query String with the given compiler hints. | |
| virtual void | compile (const String &aQuery)=0 |
| Compile the give query String. | |
| 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 | executeSAX (SAX2_ContentHandler *aContentHandler)=0 |
| Register a SAX2_ContentHandler for retrieving the serialized query result as SAX. | |
| virtual DynamicContext * | getDynamicContext () const =0 |
| Get the dynamic context of this query. | |
| virtual const StaticContext * | getStaticContext () const =0 |
| Get the static context of this query. | |
| virtual bool | isUpdateQuery () const =0 |
| Check if this query is an updating query. | |
| virtual ResultIterator_t | iterator ()=0 |
| Get an iterator for the result of the query. | |
| virtual void | registerErrorHandler (ErrorHandler *aErrorHandler)=0 |
| Register an ErrorHandler 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. | |
| virtual void | resetErrorHandler ()=0 |
| Reset the error handling mechanism to throwing exceptions, i.e. behave as if no ErrorHandler had been set. | |
| virtual void | serialize (std::ostream &aOutStream, const SerializerOptions_t &aSerOptions=SerializerOptions())=0 |
| Serialize the result of the query as text to the given output stream. | |
| virtual void | setFileName (const String &)=0 |
| Set the filename of a query. | |
| virtual | ~XQuery () |
| Destructor that destroys this XQuery object. | |
Classes | |
| struct | CompilerHints |
| Set of hints that can be passed to the query compiler. More... | |
| struct | SerializerOptions |
| Options that configure the serialization process of a query result. More... | |
It is used for compiling and executing a query. An instance of this class is not thread safe, i.e. on object can not be executed/serialized in multiple threads. To execute on query in several threads the function clone() creates a clone of the same query that can be executed in another thread.
An instance of this class can only be created using either the createQuery or compileQuery functions of the Zorba class. Objects are returned as a boost smart pointer (see http://www.boost.org/doc/libs/1_35_0/libs/smart_ptr/smart_ptr.htm), i.e. objects of type XQuery_t are reference counted boost smart pointers to an dynamically allocated XQuery object. Hence, each object can have multiple owners. The object is deleted if nobody holds on to an XQuery_t object anymore.
The file simple.cpp contains some basic examples the demonstrate the use of this class.
Definition at line 45 of file xquery.h.
| typedef struct zorba::XQuery::CompilerHints zorba::XQuery::CompilerHints_t |
| virtual zorba::XQuery::~XQuery | ( | ) | [inline, virtual] |
| virtual void zorba::XQuery::applyUpdates | ( | ) | [pure virtual] |
Apply/execute the query if it is an updating query.
| ZorbaException | if an error occured, e.g. if the query has been closed, if the query has not been compiled, or an error occures during execution. |
| virtual XQuery_t zorba::XQuery::clone | ( | ) | const [pure virtual] |
Clone this query object for executing it in another thread.
A query object is not thread safe, i.e. it can't be executed in several threads. In order to execute it in another thread it needs to be cloned with this function. Moreover, 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 aquired ressources.
While a query is compiled and/or active, it holds on to a couple of ressources. Before Zorba can be safely shutdown, all ressources 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 objects destructor, i.e. if the last boost smart pointer holding on to this XQuery object is destroyed.
Note that calling close explicitly is usually not necessary.
| SystemException | if the XQuery object has already been closed. |
| virtual void zorba::XQuery::compile | ( | std::istream & | aQuery, | |
| const StaticContext_t & | aStaticContext, | |||
| const XQuery::CompilerHints_t & | aHints | |||
| ) | [pure virtual] |
Compile the query given as an input stream with the given static context and the given 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::compile | ( | const String & | aQuery, | |
| const StaticContext_t & | aStaticContext, | |||
| const XQuery::CompilerHints_t & | aHints | |||
| ) | [pure virtual] |
Compile the give query String with the given static context and the given 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 XQuery::CompilerHints_t & | aHints | |||
| ) | [pure virtual] |
Compile the query given as an input stream with 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 XQuery::CompilerHints_t & | aHints | |||
| ) | [pure virtual] |
Compile the give query String with 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 | ( | const String & | aQuery | ) | [pure virtual] |
Compile the give query 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::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::XQuery::executeSAX | ( | SAX2_ContentHandler * | aContentHandler | ) | [pure virtual] |
Register a SAX2_ContentHandler for retrieving the serialized query result as SAX.
| aContentHandler | the content handler on which SAX callbacks are called. |
| 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 ResultIterator 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 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 have been set by the either the static context that was passed when creating the query and 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 according query object.
| SystemException | if the query has not been compiled or is closed. |
| virtual bool zorba::XQuery::isUpdateQuery | ( | ) | const [pure virtual] |
Check if this query is an updating query.
| SystemException | if the query is not compiled or has been closed. |
| virtual ResultIterator_t zorba::XQuery::iterator | ( | ) | [pure virtual] |
Get an iterator for the result of the query.
| ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled). |
| virtual void zorba::XQuery::registerErrorHandler | ( | ErrorHandler * | aErrorHandler | ) | [pure virtual] |
Register an ErrorHandler to which errors during compilation or execution/serialization are reported.
If not ErrorHandler has been set using this function or when creating/compiling the query using the Zorba object (i.e. createQuery or compileQuery), then subclasses of the ZorbaException class are thrown to report errors.
| aErrorHandler | ErrorHandler to which errors are reported. The caller retains ownership over the ErrorHandler 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. |
| virtual void zorba::XQuery::resetErrorHandler | ( | ) | [pure virtual] |
Reset the error handling mechanism to throwing exceptions, i.e. behave as if no ErrorHandler had been set.
| SystemException | if the query has been closed already. |
| virtual void zorba::XQuery::serialize | ( | std::ostream & | aOutStream, | |
| const SerializerOptions_t & | aSerOptions = SerializerOptions() | |||
| ) | [pure virtual] |
Serialize the result of the query as text to the given output stream.
| aOutStream | the output stream on which the result is written. | |
| aSerOptions | an optinal set of serialization options. |
| ZorbaException | if an error occurs (e.g. the query is closed or has not been compiled) |
| virtual void zorba::XQuery::setFileName | ( | const String & | ) | [pure virtual] |
Set the filename of a query.
This is only needed if debugging a query and for better error reporting