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    *    <ul>Current possible values are: 
00344    *      <li>DONT_SAVE_UNUSED_FUNCTIONS (default): 
00345    *        to eliminate unused functions and reduce plan size</li>
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.</li>
00350    *   </ul>
00351    * @return true if success.
00352    * @throw ZorbaException if the query has not been compiled or there are
00353    *        problems serializing the execution plan.
00354    */
00355   virtual bool
00356   saveExecutionPlan(std::ostream &os, 
00357                     Zorba_binary_plan_format_t archive_format = ZORBA_USE_BINARY_ARCHIVE,
00358                     Zorba_save_plan_options_t save_options = DONT_SAVE_UNUSED_FUNCTIONS) = 0;
00359   
00360   /** 
00361    * \brief Load execution plan.
00362    *
00363    * The serialized execution plan contains a general version for the entire
00364    * archive and specific versions for each class. Zorba does not quarantee
00365    * that it can load execution plans saved with previous versions of Zorba.
00366    * In most cases there will be no problems, but the complete backward
00367    * compatibility cannot be quaranteed.
00368    *
00369    * The engine automatically detects the format of the input, either XML or binary.
00370    *
00371    * @param is Reference to std::istream.
00372    * @param aCallback optional callback handler (see SerializationCallback)
00373    *        that is used to retrieve information that has not been serialized
00374    *        (e.g. external modules).
00375    * @return true if success.
00376    * @throw ZorbaException if there are problems loading the execution plan.
00377    */
00378   virtual bool
00379   loadExecutionPlan(std::istream& is, SerializationCallback* aCallback = 0) = 0;
00380   
00381   /** 
00382    * \brief Close the query and release all of its aquired ressources.
00383    *
00384    * While a query is compiled and/or active, it holds on to a number of
00385    * resources. Before Zorba can be safely shutdown, all resources must
00386    * be released. For queries this can be done by calling close. However,
00387    * if close is not called explicitly, it will be automatically called by
00388    * the XQuery object's destructor, when the last smart pointer pointing
00389    * this XQuery object is destroyed. 
00390    *
00391    * Note: After an XQuery object is closed, calling close() again on the
00392    * same object is a noop. However, calling any method other than close()
00393    * on a closed XQuery object is prohibited (an error will be raised).
00394    *
00395    * Note: if an iterator has been created to retreive the result of an
00396    * XQuery object (@see iterator()), that itrator will be closed when 
00397    * the query is closed, and the association between XQuery object and
00398    * Iterator object will be destroyed.
00399    */
00400   virtual void
00401   close() = 0;
00402 
00403   /** 
00404    * \brief Check if this query object has already been closed.
00405    *
00406    * @return true if the query has been closed already or false otherwise.
00407    */
00408   virtual bool
00409   isClosed() const = 0;
00410 
00411   /** 
00412    * \brief Clone this query object in order to execute the query in another
00413    * thread.
00414    *
00415    * Although two or more threads may invoke one of the execute methods on the
00416    * same XQuery object, these invocations are serialized internally. For true
00417    * parallel excetution of a query by multiple threads, the XQuery object needs
00418    * to be cloned, using this method. However, note that if an DiagnosticHandler has
00419    * been provided by the user (see registerDiagnosticHandler()), this DiagnosticHandler
00420    * will also be used in the cloned query, and as a result, the user should
00421    * provide a thread-safe DiagnosticHandler. Alternatively, a new DiagnosticHandler can
00422    * be registered in the cloned query by using registerDiagnosticHandler again.
00423    * Or, the cloned query can be reset to use the default DiagnosticHandler (which 
00424    * just throws exceptions) by calling resetDiagnosticHandler.
00425    *
00426    * This function also clones the StaticContext and DynamicContext of the
00427    * XQuery object. In the DynamicContext of the cloned query different 
00428    * variable values can be used, e.g. set different external variable
00429    * values. For an example of cloning a query and setting different values
00430    * in the dynamic context see example_10 in file \link simple.cpp \endlink.
00431    *
00432    * @return The cloned XQuery object.
00433    * @throw SystemException if the query has not been compiled or is closed.
00434    */
00435   virtual XQuery_t
00436   clone() const = 0;
00437 
00438 #ifdef ZORBA_WITH_DEBUGGER
00439   /**
00440    * \brief Enable/disable debug mode on the query
00441    */
00442   virtual void
00443   setDebugMode(bool aDebugMode) = 0;
00444   
00445   /**
00446    * \brief Check if the debug mode is activated.
00447    *
00448    * @return true if the debug mode is enabled, false otherwise.
00449    */
00450   virtual bool
00451   isDebugMode() const = 0;
00452 #endif
00453   
00454   /** 
00455    * \brief Set the filename of the profile
00456    *
00457    * This file will contain the output of Zorba profiler.
00458    */
00459   virtual void
00460   setProfileName( std::string aProfileName ) = 0;
00461   
00462   /**
00463    * \brief Get the filename of the profile
00464    *
00465    * This file will contain the output of Zorba profiler.
00466    */
00467   virtual std::string
00468   getProfileName() const = 0;
00469   
00470 #ifdef ZORBA_WITH_DEBUGGER
00471   /**
00472    * \brief Start a debugger server.
00473    *
00474    * This method will start a debugger server that will try to connect 
00475    * to a DBGP-enabled debugger client on the indicated socket (host and port).
00476    * In order to call this method, the query has to be compiled.
00477    *
00478    * @param hort the host where the debugger client is listening.
00479    * @param port the port on which the debugger client is listening.
00480    *
00481    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00482    *        not been compiled, the server cannot connect to the client, etc.)
00483    */
00484   virtual void
00485   debug(
00486     const std::string& host,
00487     unsigned short port) = 0;
00488 
00489   /**
00490    * \brief Start a debugger server.
00491    *
00492    * This method will start a debugger server that will try to connect 
00493    * to a DBGP-enabled debugger client on the indicated socket (host and port).
00494    * In order to call this method, the query has to be compiled.
00495    * You can specify an output stream and serialization options that can be used
00496    * by the serializer.
00497    *
00498    * @param outStream the output stream on which the result is written.
00499    * @param serOptions the serialization options.
00500    * @param hort the host where the debugger client is listening.
00501    * @param port the port on which the debugger client is listening.
00502    *
00503    * @throw ZorbaException if an error occurs (e.g. the query is closed or has
00504    *        not been compiled, the server cannot connect to the client, etc.)
00505    */
00506   virtual void
00507   debug(
00508     std::ostream& outStream,
00509     Zorba_SerializerOptions& serOptions,
00510     const std::string& host,
00511     unsigned short port) = 0;
00512 
00513 
00514   virtual void
00515   debug(
00516     std::ostream& outStream,
00517     itemHandler callbackFunction,
00518     void* callbackData,
00519     Zorba_SerializerOptions& serOptions,
00520     const std::string& host,
00521     unsigned short port) = 0;
00522 #endif
00523 
00524   /** \brief Returns a CollectionManager responsible for all collections
00525    * which are statically declared in the static context of this query
00526    * (main module) or any transitively imported library module.
00527    *
00528    * The collection manager provides a set of functions for managing
00529    * collections and their contents.
00530    *
00531    * @return The collection manager responsible for managing
00532    *   collections of this query.
00533    *
00534    */
00535   virtual StaticCollectionManager*
00536   getStaticCollectionManager() const = 0;
00537 
00538   /** \brief Returns the QName of all external variables 
00539    *
00540    * @param aVarsIter iterator to store the results.
00541    * @throw ZorbaException if an error occured.
00542    */
00543   virtual void
00544   getExternalVariables(Iterator_t& aVarsIter) const = 0;
00545 
00546   /**
00547    *
00548    */
00549   virtual double
00550   getDocLoadingUserTime() const = 0;
00551   
00552   /**
00553    *
00554    */
00555   virtual double
00556   getDocLoadingTime() const = 0;
00557 };
00558   
00559 
00560 // xml serialization of the query (equiv to calling serialize(os) 
00561 ZORBA_DLL_PUBLIC
00562 std::ostream& operator<< (std::ostream& os, const XQuery_t& aQuery); 
00563 
00564 ZORBA_DLL_PUBLIC
00565 std::ostream& operator<< (std::ostream& os, XQuery* aQuery); 
00566 
00567 
00568 } /* namespace zorba */
00569 
00570 #endif
00571 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus