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