Public Member Functions | Protected Attributes
zorba::XQuery Class Reference

This class is the representation of an XQuery in the Zorba engine. More...

#include <zorba/xquery.h>

Inheritance diagram for zorba::XQuery:
Inheritance graph
[legend]
Collaboration diagram for zorba::XQuery:
Collaboration graph
[legend]

List of all members.

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, 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 compile (const String &aQuery)=0
 Compile a query given as a String.
virtual void execute ()=0
 Execute the (updating) query.
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 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 DynamicContextgetDynamicContext () 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 StaticCollectionManagergetStaticCollectionManager () 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 StaticContextgetStaticContext () 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

Detailed Description

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.

Definition at line 50 of file xquery.h.


Constructor & Destructor Documentation

virtual zorba::XQuery::~XQuery ( ) [inline, virtual]

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.

Definition at line 59 of file xquery.h.


Member Function Documentation

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.

Returns:
The cloned XQuery object.
Exceptions:
SystemExceptionif 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 (

See also:
iterator()), that itrator will be closed when the query is closed, and the association between XQuery object and Iterator object will be destroyed.
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.

Parameters:
aQuerythe query String to compile.
aHintshints passed to the query compiler.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aQuerythe query input stream.
aHintshints passed to the query compiler.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aQuerythe query String to compile.
aStaticContextthe static context.
aHintshints passed to the query compiler.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aQuerythe query input stream.
aStaticContextthe static context.
aHintshints passed to the query compiler.
Exceptions:
ZorbaExceptionif 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 a query given as a String.

Parameters:
aQuerythe query String to compile.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aOutStreamthe output stream on which the result is written.
aSerOptionsan optional set of serialization options.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aOutStreamthe output stream on which the result is written.
aCallbackFunctiona call back function which is called every time, before the serialization of an item.
aCallbackDatadata which is passed to the call back function.
aSerOptionsSerializer options.
Exceptions:
ZorbaExceptionif 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.

See also:
isUpdating
Exceptions:
ZorbaExceptionif 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.

Parameters:
aContentHandlerthe 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.

Exceptions:
ZorbaExceptionif 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.

Exceptions:
SystemExceptionif the query has not been compiled or is closed.
Returns:
DynamicContext of this query.
virtual void zorba::XQuery::getExternalVariables ( Iterator_t aVarsIter) const [pure virtual]

Returns the QName of all external variables.

Parameters:
aVarsIteriterator to store the results.
Exceptions:
ZorbaExceptionif 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.

Returns:
The collection manager responsible for managing collections of this query.
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.

Exceptions:
SystemExceptionif the query has not been compiled or is closed.
Returns:
StaticContext of this query.
virtual bool zorba::XQuery::isClosed ( ) const [pure virtual]

Check if this query object has already been closed.

Returns:
true if the query has been closed already or false otherwise.
virtual bool zorba::XQuery::isSequential ( ) const [pure virtual]

Check if this query is a sequential query.

Returns:
true if the query is a sequential query, false otherwise.
Exceptions:
SystemExceptionif the query is not compiled or has been closed.
See also:
close()
compile(...)
virtual bool zorba::XQuery::isUpdating ( ) const [pure virtual]

Check if this query is an updating query.

Returns:
true if the query is an updating query, false otherwise.
Exceptions:
SystemExceptionif the query is not compiled or has been closed.
See also:
close()
compile(...)
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.

Returns:
Iterator iterator over the result sequence.
Exceptions:
ZorbaExceptionif 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.

Parameters:
isReference to std::istream.
aCallbackoptional callback handler (see SerializationCallback) that is used to retrieve information that has not been serialized (e.g. external modules).
Returns:
true if success.
Exceptions:
ZorbaExceptionif there are problems loading the execution plan.
virtual void zorba::XQuery::parse ( std::istream &  aQuery) [pure virtual]

Parse the given query String.

Parameters:
aQuerythe query file to parse.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aStreamthe output stream to which the execution plan is printed
aDotFormatspecifies 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.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aDiagnosticHandlerDiagnosticHandler to which errors are reported. The caller retains ownership over the DiagnosticHandler passed as parameter.
Exceptions:
SystemExceptionif the query has been closed.
See also:
close()
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.

Parameters:
aContentHandlerthe 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.

Exceptions:
SystemExceptionif the query has been closed already.
See also:
registerDiagnosticHandler(DiagnosticHandler*)
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.

Parameters:
osThe output stream into which the execution plan is saved.
archive_formatSpecify 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_optionsSpecify some options to the plan serializer.
possible values are: DONT_SAVE_UNUSED_FUNCTIONS (default): to eliminate unused functions and reduce plan size SAVE_UNUSED_FUNCTIONS: to save everything, as if the xquery contains an eval instruction. This is useful if you intend to use StaticContext::containsFunction or StaticContext::findFunctions.
Returns:
true if success.
Exceptions:
ZorbaExceptionif 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.

Parameters:
aTimeoutis 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.

Member Data Documentation

unsigned int zorba::SmartObject::theRefCount [mutable, protected, inherited]

Definition at line 27 of file smart_ptr.h.


The documentation for this class was generated from the following file:
blog comments powered by Disqus