zorba::XQuery#include <zorba/xquery.h> Inherited from: zorba::SmartObject This class is the representation of an XQuery program in the Zorba engine. To compile and execute an XQuery program, 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. 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.Public Functions
Protected Attributes
Public FunctionsaddReferencevoid addReference() const
cloneXQuery_t clone() const =0 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. ReturnsThe cloned XQuery object.Parameters
closevoid close()=0 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 ( Returnsiterator()), that itrator will be closed when the query is closed, and the association between XQuery object and Iterator object will be destroyed.compilevoid compile(const String &aQuery)=0 compilevoid compile(const String &aQuery, const Zorba_CompilerHints_t &aHints)=0 compilevoid compile(std::istream &aQuery, const Zorba_CompilerHints_t &aHints)=0 Compile a query given as an input stream, using the given compiler hints.
Parameters
Parameters
compilevoid 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.
Parameters
Parameters
compilevoid 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.
Parameters
Parameters
executevoid execute(std::ostream &aOutStream, const Zorba_SerializerOptions_t *aSerOptions=NULL)=0 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
Parameters
executevoid 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. A handler function gets called before the serialization of each item. Parameters
Parameters
executevoid execute()=0 Execute the (updating) query. The query can be executed with this function only if it is an updating query. ReturnsisUpdatingParameters
executeSAXvoid 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.
Parameters
executeSAXvoid executeSAX()=0 Serialize the query result as SAX events and call the callbacks of the SAX2_ContentHandler that has been set using registerSAXHandler.
Parameters
freevoid free()
getDocLoadingTimedouble getDocLoadingTime() const =0
getDocLoadingUserTimedouble getDocLoadingUserTime() const =0
getDynamicContextDynamicContext * getDynamicContext() const =0 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. Parameters
ReturnsDynamicContext of this query.getExternalVariablesvoid getExternalVariables(Iterator_t &aVarsIter) const =0 Returns the QName of all external variables.
Parameters
Parameters
getProfileNamestd::string getProfileName() const =0 Get the filename of the profile. This file will contain the output of Zorba profiler. getRefCountlong getRefCount() const
getStaticCollectionManagerStaticCollectionManager * 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. The collection manager provides a set of functions for managing collections and their contents. ReturnsThe collection manager responsible for managing collections of this query.getStaticContextconst StaticContext * getStaticContext() const =0 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. Parameters
ReturnsStaticContext of this query.isClosedbool isClosed() const =0 Check if this query object has already been closed.
Returnstrue if the query has been closed already or false otherwise.isSequentialbool isSequential() const =0 isUpdatingbool isUpdating() const =0 iteratorIterator_t iterator()=0 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. ReturnsIterator iterator over the result sequence.Parameters
loadExecutionPlanbool loadExecutionPlan(std::istream &is, SerializationCallback *aCallback=0)=0 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
Returnstrue if success.Parameters
parsevoid parse(std::istream &aQuery)=0 Parse the given query String.
Parameters
Parameters
parsevoid parse(std::istream &aQuery, ModuleInfo_t &aResult)=0 Parse the given module String. This function parses the module string and returns some information about the module. Parameters
Parameters
printPlanvoid printPlan(std::ostream &aStream, bool aDotFormat=false) const =0 Print the execution plan of this query to the given output stream.
Parameters
Parameters
registerDiagnosticHandlervoid registerDiagnosticHandler(DiagnosticHandler *handler)=0 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
Parameters
Returnsclose()registerSAXHandlervoid registerSAXHandler(SAX2_ContentHandler *aContentHandler)=0 Register a SAX2_ContentHandler for retrieving the serialized query result as SAX events when executeSAX() is called.
Parameters
removeReferencevoid removeReference()
resetDiagnosticHandlervoid resetDiagnosticHandler()=0 Reset the error handling mechanism back to the default, i.e. behave as if no DiagnosticHandler had been set.
Parameters
saveExecutionPlanbool saveExecutionPlan(std::ostream &os)=0 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
Returnstrue if success.Parameters
setFileNamevoid setFileName(const String &flename)=0 Set the filename of a query. This (after URI-encoding) becomes the encapsulating entity's retrieval URI (in RFC 3986 terms), and may be used in the computation of the program's static base URI property, as described at http://www.w3.org/TR/xquery-30/#dt-base-uri-decl setProfileNamevoid setProfileName(std::string aProfileName)=0 Set the filename of the profile. This file will contain the output of Zorba profiler. setTimeoutvoid setTimeout(long aTimeout=-1)=0 Set a timeout, after which the execution of the query will be aborted.
Parameters
~XQuery ~XQuery() Destructor. The destructor is called automatically when there are no more XQuery_t smart pointers pointing to this XQuery instance. Protected AttributestheRefCountunsigned int theRefCount
|