zorba.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 XQP_ZORBA_API_H
00017 #define XQP_ZORBA_API_H
00018 
00019 #include <istream>
00020 
00021 #include <zorba/config.h>
00022 #include <zorba/api_shared_types.h>
00023 #include <zorba/collection.h>
00024 #include <zorba/dynamic_context.h>
00025 #include <zorba/diagnostic_handler.h>
00026 #include <zorba/item.h>
00027 #include <zorba/item_factory.h>
00028 #include <zorba/options.h>
00029 #include <zorba/static_context.h>
00030 #include <zorba/version.h>
00031 #include <zorba/xmldatamanager.h>
00032 #include <zorba/document_manager.h>
00033 #include <zorba/collection_manager.h>
00034 #include <zorba/xquery.h>
00035 #include <zorba/zorba_string.h>
00036 
00037 namespace zorba {
00038 
00039 /**
00040  * The Zorba class is the single point of access to the %Zorba engine.
00041  * There exists one instance of the Zorba class per process.
00042  * It can be used to (1) create and compile queries, (2) create static contexts,
00043  * (3) provides access to the XmlDataManager, and (4) provides access to the ItemFactory.
00044  */
00045 class ZORBA_DLL_PUBLIC Zorba
00046 {
00047  public:
00048 
00049   /** \brief Gets the singleton instance of the Zorba object.
00050    *
00051    * The Zorba object provides factory methods for creating and/or compiling
00052    * XQuery objects, creating StaticContext objects, and accessing components
00053    * as, for example, the ItemFactory or the XmlDataManager.
00054    *
00055    * The first time this function is called, the %Zorba Engine is initialized.
00056    * Thereby, it initializes all the libraries that are used in the system, i.e.
00057    * ICU, libxml2, xerces, and libcurl.
00058    *
00059    * @return Zorba the singleton Zorba object
00060    *
00061    */
00062   static Zorba*
00063   getInstance(void* store);
00064 
00065   /** \brief Get information about the used version of %Zorba.
00066    *
00067    * @return Version information about the used %Zorba version.
00068    */
00069   static const Version&
00070   version();
00071 
00072 
00073   /** \brief Destructor.
00074    *
00075    * The destructor is called during static deinitialization if getInstance
00076    * has been called at least once before.
00077    */
00078   virtual ~Zorba();
00079 
00080   /** \brief Releases all resources aquired by the Zorba %XQuery Engine.
00081    *
00082    * Also releases resources aquired by the libraries used (i.e. icu,
00083    * libxml2, xerces, libcurl).
00084    *
00085    * Before calling shutdown, all xquery objects, items, contexts, ... have
00086    * to be closed or gone out of scope; otherwise this call may fail.
00087    *
00088    * After shutdown has been called, any calls to zorba are invalid.
00089    *
00090    * getInstance may be used to reinitialize the engine.
00091    *
00092    */
00093   virtual void
00094   shutdown() = 0;
00095 
00096   /** \brief Creates an XQuery object.
00097    *
00098    * This methods creates an XQuery object without implicitliy assigning it
00099    * a query. An object returned by this method can be compiled (see compileQuery).
00100    *
00101    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00102    * an DiagnosticHandler is passed as parameter, each error that occurs during
00103    * compiling or executing the query, is reported to the passed error handler.
00104    * If no DiagnosticHandler is given, exceptions are thrown for each of these errors.
00105    *
00106    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00107    * @return XQuery the newly created XQuery object.
00108    */
00109   virtual XQuery_t
00110   createQuery(DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00111 
00112   /** \brief Creates and compiles an XQuery object.
00113    *
00114    * This methods creates an XQuery object and compiles the query string
00115    * passed to this method.
00116    *
00117    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00118    * an DiagnosticHandler is passed as parameter, each error that occurs during
00119    * compiling or executing the query, is reported to the passed error handler.
00120    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00121    *
00122    * @param aQuery the query string for the new XQuery object.
00123    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00124    * @return XQuery the newly created and compiled XQuery object.
00125    */
00126   virtual XQuery_t
00127   compileQuery(const String& aQuery, DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00128 
00129   /** \brief Creates and compiles an XQuery object using a StaticContext.
00130    *
00131    * This methods creates an XQuery object and compiles the query string
00132    * passed to this method. Compilation is done using the information
00133    * contained in the StaticContext that is passed as parameter.
00134    *
00135    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00136    * an DiagnosticHandler is passed as parameter, each error that occurs during
00137    * compiling or executing the query, is reported to the passed error handler.
00138    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00139    *
00140    * @param aQuery the query string for the new XQuery object.
00141    * @param aContext the StaticContext that contains information used for compiling the query.
00142    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00143    * @return XQuery the newly created and compiled XQuery object.
00144    */
00145   virtual XQuery_t
00146   compileQuery(const String& aQuery,
00147                const StaticContext_t& aContext,
00148                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00149 
00150   /** \brief Creates and compiles an XQuery object using the given CompilerHints.
00151    *
00152    * This methods creates an XQuery object and compiles the query string
00153    * passed to this method. Compilation and optimization is done with respect
00154    * to the given CompilerHints.
00155    *
00156    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00157    * an DiagnosticHandler is passed as parameter, each error that occurs during
00158    * compiling or executing the query, is reported to the passed error handler.
00159    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00160    *
00161    * @param aQuery the query string for the new XQuery object.
00162    * @param aCompilerHints the CompilerHints used to compile the query.
00163    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00164    * @return XQuery the newly created and compiled XQuery object.
00165    */
00166   virtual XQuery_t
00167   compileQuery(const String& aQuery,
00168                const Zorba_CompilerHints_t& aCompilerHints,
00169                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00170 
00171   /** \brief Creates and compiles an XQuery object using the given
00172    * CompilerHints and StaticContext.
00173    *
00174    * This methods creates an XQuery object and compiles the query string
00175    * passed to this method. Compilation and optimization is done with respect
00176    * to the given CompilerHints. Moreover, compilation is done using the
00177    * information contained in the StaticContext.
00178    *
00179    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00180    * an DiagnosticHandler is passed as parameter, each error that occurs during
00181    * compiling or executing the query, is reported to the passed error handler.
00182    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00183    *
00184    * @param aQuery the query string for the new XQuery object.
00185    * @param aContext the StaticContext that contains information used for compiling the query.
00186    * @param aCompilerHints the CompilerHints used to compile the query.
00187    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00188    * @return XQuery the newly created and compiled XQuery object.
00189    */
00190   virtual XQuery_t
00191   compileQuery(const String& aQuery,
00192                const StaticContext_t& aContext,
00193                const Zorba_CompilerHints_t& aCompilerHints,
00194                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00195 
00196   /** \brief Creates and compiles an XQuery object.
00197    *
00198    * This methods creates an XQuery object and compiles the query that is
00199    * passed to this method as an input stream.
00200    *
00201    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00202    * an DiagnosticHandler is passed as parameter, each error that occurs during
00203    * compiling or executing the query, is reported to the passed error handler.
00204    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00205    *
00206    * @param aQuery the input stream providing the query.
00207    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00208    * @return XQuery the newly created and compiled XQuery object.
00209    */
00210   virtual XQuery_t
00211   compileQuery(std::istream& aQuery, DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00212 
00213   /** \brief Creates and compiles an XQuery object using a StaticContext.
00214    *
00215    * This methods creates an XQuery object and compiles the query that is
00216    * passed to this method as an input stream. Compilation is done using
00217    * the information contained in the StaticContext that is passed as
00218    * parameter.
00219    *
00220    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00221    * an DiagnosticHandler is passed as parameter, each error that occurs during
00222    * compiling or executing the query, is reported to the passed error handler.
00223    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00224    *
00225    * @param aQuery the input stream providing the query.
00226    * @param aContext the StaticContext that contains information used for compiling the query.
00227    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00228    * @return XQuery the newly created and compiled XQuery object.
00229    */
00230   virtual XQuery_t
00231   compileQuery(std::istream& aQuery,
00232                const StaticContext_t& aContext,
00233                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00234 
00235   /** \brief Creates and compiles an XQuery object using the given CompilerHints.
00236    *
00237    * This methods creates an XQuery object and compiles the query that is
00238    * passed to this method as an input stream. Compilation and optimization
00239    * is done with respect to the given CompilerHints.
00240    *
00241    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00242    * an DiagnosticHandler is passed as parameter, each error that occurs during
00243    * compiling or executing the query, is reported to the passed error handler.
00244    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00245    *
00246    * @param aQuery the input stream providing the query.
00247    * @param aCompilerHints the CompilerHints used to compile the query.
00248    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00249    * @return XQuery the newly created and compiled XQuery object.
00250    */
00251   virtual XQuery_t
00252   compileQuery(std::istream& aQuery,
00253                const Zorba_CompilerHints_t& aCompilerHints,
00254                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00255 
00256   /** \brief Creates and compiles an XQuery object using the given
00257    * CompilerHints and StaticContext.
00258    *
00259    * This methods creates an XQuery object and compiles the query that is
00260    * passed to this method as an input stream. Compilation and optimization
00261    * is done with respect to the given CompilerHints. Moreover, compilation
00262    * is done using the information contained in the StaticContext.
00263    *
00264    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00265    * an DiagnosticHandler is passed as parameter, each error that occurs during
00266    * compiling or executing the query, is reported to the passed error handler.
00267    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00268    *
00269    * @param aQuery the input stream providing the query.
00270    * @param aContext the StaticContext that contains information used for compiling the query.
00271    * @param aCompilerHints the CompilerHints used to compile the query.
00272    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00273    * @return XQuery the newly created and compiled XQuery object.
00274    */
00275   virtual XQuery_t
00276   compileQuery(std::istream& aQuery,
00277                const StaticContext_t& aContext,
00278                const Zorba_CompilerHints_t& aCompilerHints,
00279                DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00280 
00281   /** \brief Creates a new StaticContext.
00282    *
00283    * The method returns a StaticContext object that can be used
00284    * for compiling a query. Instances of the StaticContext class are
00285    * returned as a smart pointer.
00286    * That is, objects of type StaticContext_t are reference counted object
00287    * to an dynamically allocated StaticContext object. Hence, each object can h
00288    * have multiple owners. The object is deleted if nobody holds on to an StaticContext_t
00289    * object anymore.
00290    *
00291    * Optionally, this method takes an DiagnosticHandler as parameter. In the case
00292    * an DiagnosticHandler is passed as parameter, each error that occurs during
00293    * setting or getting information out of the StaticContext, is reported to the passed
00294    * DiagnosticHandler.
00295    * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
00296    *
00297    * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
00298    * @return StaticContext_t a new StaticContext object.
00299    */
00300   virtual StaticContext_t
00301   createStaticContext(DiagnosticHandler* aDiagnosticHandler = 0) = 0;
00302 
00303   /** \brief Gets the singelton instance of the ItemFactory.
00304    *
00305    * @return ItemFactory the singleton instance of the ItemFactory.
00306    */
00307   virtual ItemFactory*
00308   getItemFactory() = 0;
00309 
00310   /** \brief Gets the singleton instance of the XmlDataManager object.
00311    *
00312    * @return XmlDataManager the singelton instance of the XmlDataManager.
00313    */
00314   virtual XmlDataManager*
00315   getXmlDataManager() = 0;
00316 
00317   /** \brief Gets the singleton instance of Zorba's audit provider object.
00318    *
00319    * @return audit::Provider the singelton instance of Zorba's audit provider.
00320    */
00321   virtual audit::Provider*
00322   getAuditProvider() = 0;
00323 
00324 }; /* class Zorba */
00325 
00326 
00327 } /* namespace zorba */
00328 
00329 /**
00330  * \example simple.cpp
00331  *  This is a simple example that demonstrate how to create, compile, and execute queries.
00332  *
00333  * \example datamanager.cpp
00334  *  This file contains some examples that demonstrate how the XmlDataManager can be used
00335  *  to load files, create collection, etc.
00336  *
00337  * \example context.cpp
00338  *  This file demonstrates how the ItemFactory can be used to create new Items and
00339  *  bind the Items to external variables in the dynamic context of a query.
00340  *
00341  * \example errors.cpp
00342  *  This file demonstrates how error management and handling is done in Zorba.
00343  *
00344  * \example serialization.cpp
00345  * This file shows examples of how to serialize query results, for example as XML.
00346  *
00347  * \example sax2.cpp
00348  * An example showing XML serialization that is performed using SAX2.
00349  *
00350  * \example external_functions.cpp
00351  * This file shows some simple examples of external functions.
00352  *
00353  */
00354 #endif /* XQP_ZORBA_API_H */
00355 
00356 /*
00357  * Local variables:
00358  * mode: c++
00359  * End:
00360  */
00361 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus