> The XQuery Processor
#include <zorba/xquery.h>
Public Member Functions | |
| void | addReference () const |
| 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 Zorba_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 Zorba_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 Zorba_CompilerHints_t &aHints)=0 |
| Compile the query given as an input stream with the given compiler hints. | |
| virtual void | compile (const String &aQuery, const Zorba_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 void | free () |
| virtual DynamicContext * | getDynamicContext () const =0 |
| Get the dynamic context of this query. | |
| long | getRefCount () const |
| 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. | |
| void | removeReference () |
| 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 Zorba_SerializerOptions_t &aSerOptions=Zorba_SerializerOptions_default())=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. | |
Protected Attributes | |
| unsigned int | theRefCount |
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, each XQuery object can have multiple owners, potentially in different threads. The XQuery object is deleted when all XQuery_t objects that point to it are destroyed.
Although an XQuery instance may be accessible from multiple threads, the instance is not thread safe, i.e. its methods should not be invoked in parallel by multiple threads. The only exception to this rule is the clone() method. Cloning is the way to execute the same query from multiple threads. Cloning can be done only after the query has been compiled. The clone() method creates and returns a new XQuery object that shares the same execution plan as the original XQuery object. After clone() returns, the calling thread can invoke the various execution methods on the XQuery clone.
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.
Definition at line 56 of file xquery.h.
| virtual zorba::XQuery::~XQuery | ( | ) | [inline, virtual] |
| void zorba::SmartObject::addReference | ( | ) | const [inline, inherited] |
Definition at line 39 of file smart_ptr.h.
| 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. However, please note that if an ErrorHandler has been provided by the user (see registerErrorHandler()), this ErrorHandler will also be used in the cloned query, and as a result, the user should provide a thread-safe ErrorHandler. Alternatively, a new ErrorHandler can be registered in the cloned query by using registerErrorHandler again. Or, the cloned query can be reset to use the default ErrorHandler (which just throws exceptions) by calling resetErrorHandler.
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 smart pointer holding 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 Zorba_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 Zorba_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 Zorba_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 Zorba_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 void zorba::SmartObject::free | ( | ) | [inline, virtual, inherited] |
Definition at line 35 of file smart_ptr.h.
| 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. |
| long zorba::SmartObject::getRefCount | ( | ) | const [inline, inherited] |
Definition at line 37 of file smart_ptr.h.
| 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 no 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. |
| void zorba::SmartObject::removeReference | ( | ) | [inline, inherited] |
Definition at line 41 of file smart_ptr.h.
| 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 Zorba_SerializerOptions_t & | aSerOptions = Zorba_SerializerOptions_default() | |||
| ) | [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 (after URI-encoding) becomes the encapsulating entity's retrieval URI (in RFC 3986 terms).
unsigned int zorba::SmartObject::theRefCount [mutable, protected, inherited] |
Definition at line 26 of file smart_ptr.h.