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: */