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