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