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)=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 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 ( )
inlinevirtual

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
inlineinherited

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)
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::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::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 ( )
virtualinherited
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
inlineinherited

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 ( )
inlineinherited

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. Current possible values are:
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
mutableprotectedinherited

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