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