xquery.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2006-2008 The FLWOR Foundation.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef ZORBA_XQUERY_API_H
00017 #define ZORBA_XQUERY_API_H
00018 
00019 #include <ostream>
00020 
00021 #include <zorba/config.h>
00022 #include <zorba/sax2.h>
00023 #include <zorba/api_shared_types.h>
00024 #include <zorba/options.h>
00025 
00026 
00027 namespace zorba {
00028 
00029 typedef Zorba_SerializerOptions_t* (*itemHandler)(void* aUserData);
00030 
00031 /** 
00032  * \brief This class is the representation of an %XQuery in the %Zorba engine.
00033  *
00034  * To compile and execute an XQuery, an instance of this class must be created. 
00035  * This is done by using either the createQuery or compileQuery methods of the
00036  * Zorba class. These methods return an instance of XQuery_t, which is a 
00037  * reference counted smart pointer to a dynamically allocated XQuery object.
00038  * After receiving an XQuery_t, an application can make multiple copies of it.
00039  * Hence, an XQuery object can have multiple users, potentially in different
00040  * threads. The XQuery object is deleted when all XQuery_t objects that point 
00041  * to it are destroyed.
00042  *
00043  * The file \link simple.cpp \endlink contains some basic examples the demonstrate
00044  * the use of this class.
00045  *
00046  * Note: This class is reference counted. When writing multi-threaded clients,
00047  * it is the responibility of the client code to synchronize assignments to the
00048  * SmartPtr holding this object.
00049  */
00050 class ZORBA_DLL_PUBLIC XQuery : public SmartObject
00051 {
00052  public:
00053   /** 
00054    * \brief Destructor that destroys this XQuery object. 
00055    * 
00056    * The destructor is called automatically when there are no more XQuery_t
00057    * smart pointers pointing to this XQuery instance.
00058    */
00059   virtual ~XQuery() {}
00060 
00061   /** 
00062    * \brief Set the filename of a query.
00063    *
00064    * This (after URI-encoding) becomes the encapsulating entity's
00065    * retrieval URI (in RFC 3986 terms).
00066    */
00067   virtual void
00068   setFileName(const String&) = 0;
00069   
00070   /** 
00071    * \brief Register an DiagnosticHandler to which errors during compilation or
00072    * execution/serialization are reported.
00073    *
00074    * If no DiagnosticHandler has been set via this function, the default error
00075    * handling mechanism is to throw instances of the ZorbaException class.
00076    *
00077    * @param aDiagnosticHandler DiagnosticHandler to which errors are reported. The
00078    *        caller retains ownership over the DiagnosticHandler passed as
00079    *        parameter.
00080    * @throw SystemException if the query has been closed.
00081    * @see close()
00082    */
00083   virtual void
00084   registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
00085   
00086   /** 
00087    * \brief Reset the error handling mechanism back to the default,
00088    * i.e.\ behave as if no DiagnosticHandler had been set.
00089    *   
00090    *  @throw SystemException if the query has been closed already.
00091    *  @see registerDiagnosticHandler(DiagnosticHandler*)
00092    */
00093   virtual void
00094   resetDiagnosticHandler() = 0;
00095   
00096   /**
00097    * \brief Set a timeout, after which the execution of the query will be
00098    * aborted.
00099    *
00100    * @param aTimeout is an optional argument, which declares, that the
00101    *        execution of a query will be aborted after aTimeout number of
00102    *        seconds. If aTimeout is set to -1 (default), the query will
00103    *        never abort.
00104    */
00105   virtual void
00106   setTimeout(long aTimeout = -1) = 0;
00107   
00108   /**
00109    * \brief Execute the query and write the result to the given output stream.
00110    *        The query only has a result if it's a non-updating query.
00111    *
00112    * @param aOutStream the output stream on which the result is written.
00113    * @param aSerOptions an optional set of serialization options.
00114    * @throw ZorbaException if an error occurs (e.g. the query is closed or
00115    *        has not been compiled)
00116    */
00117   virtual void
00118   execute(std::ostream& aOutStream,
00119           const Zorba_SerializerOptions_t* aSerOptions = NULL) = 0;
00120   
00121   /**
00122    * \brief Execute the query and write the result to the given output stream.
00123    * A handler function gets called before the serialization of each item.
00124    *
00125    * @param aOutStream the output stream on which the result is written.
00126    * @param aCallbackFunction a call back function which is called every time,
00127    *        before the serialization of an item.
00128    * @param aCallbackData data which is passed to the call back function.
00129    * @param aSerOptions Serializer options.
00130    * @throw ZorbaException if an error occurs (e.g. the query is closed or
00131    *        has not been compiled)
00132    */
00133   virtual void
00134   execute(std::ostream& aOutStream,
00135           itemHandler aCallbackFunction,
00136           void* aCallbackData,
00137           const Zorba_SerializerOptions_t* aSerOptions = NULL) = 0;
00138   
00139   /**
00140    * \brief Execute the (updating) query. The query can be executed with this
00141    * function only if it is an updating query.
00142    *
00143    * @see isUpdating
00144    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00145    *        not been compiled or is not updating)
00146    */
00147   virtual void
00148   execute() = 0;
00149   
00150   /**
00151    * \brief Get an iterator for the result of the query. Allows an application
00152    * to lazily execute the query, retrieving the result one item at a time.
00153    *
00154    * @return Iterator iterator over the result sequence.
00155    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00156    *        not been compiled).
00157    */
00158   virtual Iterator_t
00159   iterator() = 0;
00160   
00161   /**
00162    * \brief Register a SAX2_ContentHandler for retrieving the serialized 
00163    *         query result as SAX events when executeSAX() is called.
00164    *
00165    * @param aContentHandler the content handler on which SAX callbacks are called.
00166    */
00167   virtual void
00168   registerSAXHandler( SAX2_ContentHandler* aContentHandler ) = 0;
00169   
00170   /**
00171    * \brief Serialize the query result as SAX events and call the callbacks
00172    *        of the SAX2_ContentHandler that is given as input
00173    *
00174    * @param aContentHandler the content handler on which SAX callbacks are called.
00175    */
00176   virtual void
00177   executeSAX( SAX2_ContentHandler* aContentHandler) = 0;
00178   
00179   /** 
00180    * \brief Serialize the query result as SAX events and call the callbacks
00181    *        of the SAX2_ContentHandler that has been set using registerSAXHandler.
00182    *
00183    * @throw ZorbaException if an error occurs (e.g. no SAX2_ContentHandler has
00184    *        been registered).
00185    */
00186   virtual void
00187   executeSAX() = 0;
00188 
00189   /** 
00190    * \brief Get the dynamic context of this query.
00191    *
00192    * This function returns the dynamic context that belongs to this query and
00193    * is used during query execution. The context can be used, for example, to
00194    * set values of external variables, the default collation, or the current
00195    * datetime. It is only available if the query has been compiled, otherwise
00196    * an error is reported. Moreover, the context must not be modified during the
00197    * execution of a query (i.e. if a Iterator is opened). The lifetime of the
00198    * context returned by this function is restricted by the lifetime of the
00199    * according query object.
00200    *
00201    * @throw SystemException if the query has not been compiled or is closed.
00202    * @return DynamicContext of this query.
00203    */
00204   virtual DynamicContext*
00205   getDynamicContext() const = 0;
00206 
00207   /** 
00208    * \brief Get the static context of this query.
00209    *
00210    * This function returns the static context that belongs to this query. The
00211    * static context is only available if the query has been compiled, otherwise
00212    * an error is reported. The context has all the components and values that 
00213    * were set in the static context that was passed when creating the query and
00214    * those that were set in the prolog of the query. Note that after compilation
00215    * of the query the static context is a read only structure. Moreover, the
00216    * lifetime of the context returned by this function is restricted by the
00217    * lifetime of the corresponding query object.
00218    *
00219    * @throw SystemException if the query has not been compiled or is closed.
00220    * @return StaticContext of this query.
00221    */
00222   virtual const StaticContext*
00223   getStaticContext() const = 0;
00224   
00225   /** 
00226    * \brief Parse the given query String.
00227    *
00228    * @param aQuery the query file to parse.
00229    * @throw ZorbaException if an error occurs while parsing the query.
00230    */
00231   virtual void
00232   parse(std::istream& aQuery) = 0;
00233   
00234   /** 
00235    * \brief Compile a query given as a String.
00236    *
00237    * @param aQuery the query String to compile.
00238    * @throw ZorbaException if the query has been closed, is already compiled, or
00239    *        an error occurs while compiling the query.
00240    */
00241   virtual void
00242   compile(const String& aQuery) = 0;
00243   
00244   /** 
00245    * \brief Compile a query given as a String, using the given compiler hints.
00246    *
00247    * @param aQuery the query String to compile.
00248    * @param aHints hints passed to the query compiler.
00249    * @throw ZorbaException if the query has been closed, is already compiled, or
00250    *        an error occurs while compiling the query.
00251    */
00252   virtual void 
00253   compile(const String& aQuery, const Zorba_CompilerHints_t& aHints) = 0;
00254   
00255   /** 
00256    * \brief Compile a query given as an input stream, using the given compiler hints.
00257    *
00258    * @param aQuery the query input stream.
00259    * @param aHints hints passed to the query compiler.
00260    * @throw ZorbaException if the query has been closed, is already compiled, or
00261    *        an error occurs while compiling the query.
00262    */
00263   virtual void 
00264   compile(std::istream& aQuery, const Zorba_CompilerHints_t& aHints) = 0;
00265   
00266   /** 
00267    * \brief Compile a query given as a String, using a given static context and  
00268    *         compiler hints.
00269    *
00270    * @param aQuery the query String to compile.
00271    * @param aStaticContext the static context.
00272    * @param aHints hints passed to the query compiler.
00273    * @throw ZorbaException if the query has been closed, is already compiled, or
00274    *        an error occurs while compiling the query.
00275    */
00276   virtual void 
00277   compile(const String& aQuery,
00278           const StaticContext_t& aStaticContext, 
00279           const Zorba_CompilerHints_t& aHints) = 0;
00280   
00281   /** 
00282    * \brief Compile a query given as an input stream, using a given static
00283    * context and compiler hints.
00284    *
00285    * @param aQuery the query input stream.
00286    * @param aStaticContext the static context.
00287    * @param aHints hints passed to the query compiler.
00288    * @throw ZorbaException if the query has been closed, is already compiled, or
00289    *        an error occurs while compiling the query.
00290    */
00291   virtual void 
00292   compile(std::istream& aQuery,
00293           const StaticContext_t& aStaticContext, 
00294           const Zorba_CompilerHints_t& aHints) = 0;
00295   
00296   /** 
00297    * \brief Print the execution plan of this query to the given output stream.
00298    *
00299    * @param aStream the output stream to which the execution plan is printed
00300    * @param aDotFormat specifies the format of the printed execution plan. 
00301    *        If this is true, then the execution plan is printed in the DOT
00302    *        format. If this is false, the plan is printed as XML.
00303    * @throw ZorbaException if the query has been closed or is not compiled.
00304    */
00305   virtual void
00306   printPlan(std::ostream& aStream, bool aDotFormat = false) const = 0;
00307 
00308   /** 
00309    * \brief Check if this query is an updating query.
00310    *
00311    * @return true if the query is an updating query, false otherwise.
00312    * @throw SystemException if the query is not compiled or has been closed.
00313    * @see close()
00314    * @see compile(...)
00315    */
00316   virtual bool
00317   isUpdating() const = 0;
00318   
00319    /** 
00320    * \brief Check if this query is a sequential query.
00321    *
00322    * @return true if the query is a sequential query, false otherwise.
00323    * @throw SystemException if the query is not compiled or has been closed.
00324    * @see close()
00325    * @see compile(...)
00326    */
00327   virtual bool 
00328   isSequential() const = 0;
00329 
00330   /** \brief Save the compiled execution plan.
00331    *
00332    * After compiling an XQuery program you can save the execution plan in some
00333    * persistent storage. The execution plan is saved in a platform-independent
00334    * format. You can later load this execution plan into a different XQuery
00335    * object (potentially  on a different machine) and execute it like it was 
00336    * compiled in place.
00337    *
00338    * @param os The output stream into which the execution plan is saved.
00339    * @param archive_format Specify which output format to use. Possible values
00340    *        are ZORBA_USE_BINARY_ARCHIVE and ZORBA_USE_XML_ARCHIVE. The binary
00341    *        format is much smaller than XML format, but is not human readable.
00342    * @param save_options Specify some options to the plan serializer.
00343    *    Current possible values are: 
00344    *      \li DONT_SAVE_UNUSED_FUNCTIONS (default): 
00345    *        to eliminate unused functions and reduce plan size
00346    *      \li SAVE_UNUSED_FUNCTIONS:
00347    *        to save everything, as if the xquery contains an eval instruction.
00348    *        This is useful if you intend to use StaticContext::containsFunction 
00349    *        or StaticContext::findFunctions.
00350    * @return true if success.
00351    * @throw ZorbaException if the query has not been compiled or there are
00352    *        problems serializing the execution plan.
00353    */
00354   virtual bool
00355   saveExecutionPlan(std::ostream &os, 
00356                     Zorba_binary_plan_format_t archive_format = ZORBA_USE_BINARY_ARCHIVE,
00357                     Zorba_save_plan_options_t save_options = DONT_SAVE_UNUSED_FUNCTIONS) = 0;
00358   
00359   /** 
00360    * \brief Load execution plan.
00361    *
00362    * The serialized execution plan contains a general version for the entire
00363    * archive and specific versions for each class. Zorba does not quarantee
00364    * that it can load execution plans saved with previous versions of Zorba.
00365    * In most cases there will be no problems, but the complete backward
00366    * compatibility cannot be quaranteed.
00367    *
00368    * The engine automatically detects the format of the input, either XML or binary.
00369    *
00370    * @param is Reference to std::istream.
00371    * @param aCallback optional callback handler (see SerializationCallback)
00372    *        that is used to retrieve information that has not been serialized
00373    *        (e.g. external modules).
00374    * @return true if success.
00375    * @throw ZorbaException if there are problems loading the execution plan.
00376    */
00377   virtual bool
00378   loadExecutionPlan(std::istream& is, SerializationCallback* aCallback = 0) = 0;
00379   
00380   /** 
00381    * \brief Close the query and release all of its aquired ressources.
00382    *
00383    * While a query is compiled and/or active, it holds on to a number of
00384    * resources. Before Zorba can be safely shutdown, all resources must
00385    * be released. For queries this can be done by calling close. However,
00386    * if close is not called explicitly, it will be automatically called by
00387    * the XQuery object's destructor, when the last smart pointer pointing
00388    * this XQuery object is destroyed. 
00389    *
00390    * Note: After an XQuery object is closed, calling close() again on the
00391    * same object is a noop. However, calling any method other than close()
00392    * on a closed XQuery object is prohibited (an error will be raised).
00393    *
00394    * Note: if an iterator has been created to retreive the result of an
00395    * XQuery object (@see iterator()), that itrator will be closed when 
00396    * the query is closed, and the association between XQuery object and
00397    * Iterator object will be destroyed.
00398    */
00399   virtual void
00400   close() = 0;
00401 
00402   /** 
00403    * \brief Check if this query object has already been closed.
00404    *
00405    * @return true if the query has been closed already or false otherwise.
00406    */
00407   virtual bool
00408   isClosed() const = 0;
00409 
00410   /** 
00411    * \brief Clone this query object in order to execute the query in another
00412    * thread.
00413    *
00414    * Although two or more threads may invoke one of the execute methods on the
00415    * same XQuery object, these invocations are serialized internally. For true
00416    * parallel excetution of a query by multiple threads, the XQuery object needs
00417    * to be cloned, using this method. However, note that if an DiagnosticHandler has
00418    * been provided by the user (see registerDiagnosticHandler()), this DiagnosticHandler
00419    * will also be used in the cloned query, and as a result, the user should
00420    * provide a thread-safe DiagnosticHandler. Alternatively, a new DiagnosticHandler can
00421    * be registered in the cloned query by using registerDiagnosticHandler again.
00422    * Or, the cloned query can be reset to use the default DiagnosticHandler (which 
00423    * just throws exceptions) by calling resetDiagnosticHandler.
00424    *
00425    * This function also clones the StaticContext and DynamicContext of the
00426    * XQuery object. In the DynamicContext of the cloned query different 
00427    * variable values can be used, e.g. set different external variable
00428    * values. For an example of cloning a query and setting different values
00429    * in the dynamic context see example_10 in file \link simple.cpp \endlink.
00430    *
00431    * @return The cloned XQuery object.
00432    * @throw SystemException if the query has not been compiled or is closed.
00433    */
00434   virtual XQuery_t
00435   clone() const = 0;
00436 
00437 #ifdef ZORBA_WITH_DEBUGGER
00438   /**
00439    * \brief Enable/disable debug mode on the query
00440    */
00441   virtual void
00442   setDebugMode(bool aDebugMode) = 0;
00443   
00444   /**
00445    * \brief Check if the debug mode is activated.
00446    *
00447    * @return true if the debug mode is enabled, false otherwise.
00448    */
00449   virtual bool
00450   isDebugMode() const = 0;
00451 #endif
00452   
00453   /** 
00454    * \brief Set the filename of the profile
00455    *
00456    * This file will contain the output of Zorba profiler.
00457    */
00458   virtual void
00459   setProfileName( std::string aProfileName ) = 0;
00460   
00461   /**
00462    * \brief Get the filename of the profile
00463    *
00464    * This file will contain the output of Zorba profiler.
00465    */
00466   virtual std::string
00467   getProfileName() const = 0;
00468   
00469 #ifdef ZORBA_WITH_DEBUGGER
00470   /**
00471    * \brief Start a debugger server.
00472    *
00473    * This method will start a debugger server that will try to connect 
00474    * to a DBGP-enabled debugger client on the indicated socket (host and port).
00475    * In order to call this method, the query has to be compiled.
00476    *
00477    * @param hort the host where the debugger client is listening.
00478    * @param port the port on which the debugger client is listening.
00479    *
00480    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00481    *        not been compiled, the server cannot connect to the client, etc.)
00482    */
00483   virtual void
00484   debug(
00485     const std::string& host,
00486     unsigned short port) = 0;
00487 
00488   /**
00489    * \brief Start a debugger server.
00490    *
00491    * This method will start a debugger server that will try to connect 
00492    * to a DBGP-enabled debugger client on the indicated socket (host and port).
00493    * In order to call this method, the query has to be compiled.
00494    * You can specify an output stream and serialization options that can be used
00495    * by the serializer.
00496    *
00497    * @param outStream the output stream on which the result is written.
00498    * @param serOptions the serialization options.
00499    * @param hort the host where the debugger client is listening.
00500    * @param port the port on which the debugger client is listening.
00501    *
00502    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00503    *        not been compiled, the server cannot connect to the client, etc.)
00504    */
00505   virtual void
00506   debug(
00507     std::ostream& outStream,
00508     Zorba_SerializerOptions& serOptions,
00509     const std::string& host,
00510     unsigned short port) = 0;
00511 
00512 
00513   virtual void
00514   debug(
00515     std::ostream& outStream,
00516     itemHandler callbackFunction,
00517     void* callbackData,
00518     Zorba_SerializerOptions& serOptions,
00519     const std::string& host,
00520     unsigned short port) = 0;
00521 #endif
00522 
00523   /** \brief Returns a CollectionManager responsible for all collections
00524    * which are statically declared in the static context of this query
00525    * (main module) or any transitively imported library module.
00526    *
00527    * The collection manager provides a set of functions for managing
00528    * collections and their contents.
00529    *
00530    * @return The collection manager responsible for managing
00531    *   collections of this query.
00532    *
00533    */
00534   virtual StaticCollectionManager*
00535   getStaticCollectionManager() const = 0;
00536 
00537   /** \brief Returns the QName of all external variables 
00538    *
00539    * @param aVarsIter iterator to store the results.
00540    * @throw ZorbaException if an error occured.
00541    */
00542   virtual void
00543   getExternalVariables(Iterator_t& aVarsIter) const = 0;
00544 
00545   /**
00546    *
00547    */
00548   virtual double
00549   getDocLoadingUserTime() const = 0;
00550   
00551   /**
00552    *
00553    */
00554   virtual double
00555   getDocLoadingTime() const = 0;
00556 };
00557   
00558 
00559 // xml serialization of the query (equiv to calling serialize(os) 
00560 ZORBA_DLL_PUBLIC
00561 std::ostream& operator<< (std::ostream& os, const XQuery_t& aQuery); 
00562 
00563 ZORBA_DLL_PUBLIC
00564 std::ostream& operator<< (std::ostream& os, XQuery* aQuery); 
00565 
00566 
00567 } /* namespace zorba */
00568 
00569 #endif
00570 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus