xquery.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef ZORBA_XQUERY_API_H
17 #define ZORBA_XQUERY_API_H
18 
19 #include <ostream>
20 
21 #include <zorba/config.h>
22 #include <zorba/sax2.h>
23 #include <zorba/api_shared_types.h>
24 #include <zorba/options.h>
25 
26 
27 namespace zorba {
28 
29 typedef Zorba_SerializerOptions_t* (*itemHandler)(void* aUserData);
30 
31 /**
32  * \brief This class is the representation of an %XQuery in the %Zorba engine.
33  *
34  * To compile and execute an XQuery, an instance of this class must be created.
35  * This is done by using either the createQuery or compileQuery methods of the
36  * Zorba class. These methods return an instance of XQuery_t, which is a
37  * reference counted smart pointer to a dynamically allocated XQuery object.
38  * After receiving an XQuery_t, an application can make multiple copies of it.
39  * Hence, an XQuery object can have multiple users, potentially in different
40  * threads. The XQuery object is deleted when all XQuery_t objects that point
41  * to it are destroyed.
42  *
43  * The file \link simple.cpp \endlink contains some basic examples the demonstrate
44  * the use of this class.
45  *
46  * Note: This class is reference counted. When writing multi-threaded clients,
47  * it is the responibility of the client code to synchronize assignments to the
48  * SmartPtr holding this object.
49  */
50 class ZORBA_DLL_PUBLIC XQuery : public SmartObject
51 {
52  public:
53  /**
54  * \brief Destructor that destroys this XQuery object.
55  *
56  * The destructor is called automatically when there are no more XQuery_t
57  * smart pointers pointing to this XQuery instance.
58  */
59  virtual ~XQuery() {}
60 
61  /**
62  * \brief Set the filename of a query.
63  *
64  * This (after URI-encoding) becomes the encapsulating entity's
65  * retrieval URI (in RFC 3986 terms).
66  */
67  virtual void
68  setFileName(const String&) = 0;
69 
70  /**
71  * \brief Register an DiagnosticHandler to which errors during compilation or
72  * execution/serialization are reported.
73  *
74  * If no DiagnosticHandler has been set via this function, the default error
75  * handling mechanism is to throw instances of the ZorbaException class.
76  *
77  * @param aDiagnosticHandler DiagnosticHandler to which errors are reported. The
78  * caller retains ownership over the DiagnosticHandler passed as
79  * parameter.
80  * @throw SystemException if the query has been closed.
81  * @see close()
82  */
83  virtual void
84  registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
85 
86  /**
87  * \brief Reset the error handling mechanism back to the default,
88  * i.e.\ behave as if no DiagnosticHandler had been set.
89  *
90  * @throw SystemException if the query has been closed already.
91  * @see registerDiagnosticHandler(DiagnosticHandler*)
92  */
93  virtual void
94  resetDiagnosticHandler() = 0;
95 
96  /**
97  * \brief Set a timeout, after which the execution of the query will be
98  * aborted.
99  *
100  * @param aTimeout is an optional argument, which declares, that the
101  * execution of a query will be aborted after aTimeout number of
102  * seconds. If aTimeout is set to -1 (default), the query will
103  * never abort.
104  */
105  virtual void
106  setTimeout(long aTimeout = -1) = 0;
107 
108  /**
109  * \brief Execute the query and write the result to the given output stream.
110  * The query only has a result if it's a non-updating query.
111  *
112  * @param aOutStream the output stream on which the result is written.
113  * @param aSerOptions an optional set of serialization options.
114  * @throw ZorbaException if an error occurs (e.g. the query is closed or
115  * has not been compiled)
116  */
117  virtual void
118  execute(std::ostream& aOutStream,
119  const Zorba_SerializerOptions_t* aSerOptions = NULL) = 0;
120 
121  /**
122  * \brief Execute the query and write the result to the given output stream.
123  * A handler function gets called before the serialization of each item.
124  *
125  * @param aOutStream the output stream on which the result is written.
126  * @param aCallbackFunction a call back function which is called every time,
127  * before the serialization of an item.
128  * @param aCallbackData data which is passed to the call back function.
129  * @param aSerOptions Serializer options.
130  * @throw ZorbaException if an error occurs (e.g. the query is closed or
131  * has not been compiled)
132  */
133  virtual void
134  execute(std::ostream& aOutStream,
135  itemHandler aCallbackFunction,
136  void* aCallbackData,
137  const Zorba_SerializerOptions_t* aSerOptions = NULL) = 0;
138 
139  /**
140  * \brief Execute the (updating) query. The query can be executed with this
141  * function only if it is an updating query.
142  *
143  * @see isUpdating
144  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
145  * not been compiled or is not updating)
146  */
147  virtual void
148  execute() = 0;
149 
150  /**
151  * \brief Get an iterator for the result of the query. Allows an application
152  * to lazily execute the query, retrieving the result one item at a time.
153  *
154  * @return Iterator iterator over the result sequence.
155  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
156  * not been compiled).
157  */
158  virtual Iterator_t
159  iterator() = 0;
160 
161  /**
162  * \brief Register a SAX2_ContentHandler for retrieving the serialized
163  * query result as SAX events when executeSAX() is called.
164  *
165  * @param aContentHandler the content handler on which SAX callbacks are called.
166  */
167  virtual void
168  registerSAXHandler( SAX2_ContentHandler* aContentHandler ) = 0;
169 
170  /**
171  * \brief Serialize the query result as SAX events and call the callbacks
172  * of the SAX2_ContentHandler that is given as input
173  *
174  * @param aContentHandler the content handler on which SAX callbacks are called.
175  */
176  virtual void
177  executeSAX( SAX2_ContentHandler* aContentHandler) = 0;
178 
179  /**
180  * \brief Serialize the query result as SAX events and call the callbacks
181  * of the SAX2_ContentHandler that has been set using registerSAXHandler.
182  *
183  * @throw ZorbaException if an error occurs (e.g. no SAX2_ContentHandler has
184  * been registered).
185  */
186  virtual void
187  executeSAX() = 0;
188 
189  /**
190  * \brief Get the dynamic context of this query.
191  *
192  * This function returns the dynamic context that belongs to this query and
193  * is used during query execution. The context can be used, for example, to
194  * set values of external variables, the default collation, or the current
195  * datetime. It is only available if the query has been compiled, otherwise
196  * an error is reported. Moreover, the context must not be modified during the
197  * execution of a query (i.e. if a Iterator is opened). The lifetime of the
198  * context returned by this function is restricted by the lifetime of the
199  * according query object.
200  *
201  * @throw SystemException if the query has not been compiled or is closed.
202  * @return DynamicContext of this query.
203  */
204  virtual DynamicContext*
205  getDynamicContext() const = 0;
206 
207  /**
208  * \brief Get the static context of this query.
209  *
210  * This function returns the static context that belongs to this query. The
211  * static context is only available if the query has been compiled, otherwise
212  * an error is reported. The context has all the components and values that
213  * were set in the static context that was passed when creating the query and
214  * those that were set in the prolog of the query. Note that after compilation
215  * of the query the static context is a read only structure. Moreover, the
216  * lifetime of the context returned by this function is restricted by the
217  * lifetime of the corresponding query object.
218  *
219  * @throw SystemException if the query has not been compiled or is closed.
220  * @return StaticContext of this query.
221  */
222  virtual const StaticContext*
223  getStaticContext() const = 0;
224 
225  /**
226  * \brief Parse the given query String.
227  *
228  * @param aQuery the query file to parse.
229  * @throw ZorbaException if an error occurs while parsing the query.
230  */
231  virtual void
232  parse(std::istream& aQuery) = 0;
233 
234  /**
235  * \brief Compile a query given as a String.
236  *
237  * @param aQuery the query String to compile.
238  * @throw ZorbaException if the query has been closed, is already compiled, or
239  * an error occurs while compiling the query.
240  */
241  virtual void
242  compile(const String& aQuery) = 0;
243 
244  /**
245  * \brief Compile a query given as a String, using the given compiler hints.
246  *
247  * @param aQuery the query String to compile.
248  * @param aHints hints passed to the query compiler.
249  * @throw ZorbaException if the query has been closed, is already compiled, or
250  * an error occurs while compiling the query.
251  */
252  virtual void
253  compile(const String& aQuery, const Zorba_CompilerHints_t& aHints) = 0;
254 
255  /**
256  * \brief Compile a query given as an input stream, using the given compiler hints.
257  *
258  * @param aQuery the query input stream.
259  * @param aHints hints passed to the query compiler.
260  * @throw ZorbaException if the query has been closed, is already compiled, or
261  * an error occurs while compiling the query.
262  */
263  virtual void
264  compile(std::istream& aQuery, const Zorba_CompilerHints_t& aHints) = 0;
265 
266  /**
267  * \brief Compile a query given as a String, using a given static context and
268  * compiler hints.
269  *
270  * @param aQuery the query String to compile.
271  * @param aStaticContext the static context.
272  * @param aHints hints passed to the query compiler.
273  * @throw ZorbaException if the query has been closed, is already compiled, or
274  * an error occurs while compiling the query.
275  */
276  virtual void
277  compile(const String& aQuery,
278  const StaticContext_t& aStaticContext,
279  const Zorba_CompilerHints_t& aHints) = 0;
280 
281  /**
282  * \brief Compile a query given as an input stream, using a given static
283  * context and compiler hints.
284  *
285  * @param aQuery the query input stream.
286  * @param aStaticContext the static context.
287  * @param aHints hints passed to the query compiler.
288  * @throw ZorbaException if the query has been closed, is already compiled, or
289  * an error occurs while compiling the query.
290  */
291  virtual void
292  compile(std::istream& aQuery,
293  const StaticContext_t& aStaticContext,
294  const Zorba_CompilerHints_t& aHints) = 0;
295 
296  /**
297  * \brief Print the execution plan of this query to the given output stream.
298  *
299  * @param aStream the output stream to which the execution plan is printed
300  * @param aDotFormat specifies the format of the printed execution plan.
301  * If this is true, then the execution plan is printed in the DOT
302  * format. If this is false, the plan is printed as XML.
303  * @throw ZorbaException if the query has been closed or is not compiled.
304  */
305  virtual void
306  printPlan(std::ostream& aStream, bool aDotFormat = false) const = 0;
307 
308  /**
309  * \brief Check if this query is an updating query.
310  *
311  * @return true if the query is an updating query, false otherwise.
312  * @throw SystemException if the query is not compiled or has been closed.
313  * @see close()
314  * @see compile(...)
315  */
316  virtual bool
317  isUpdating() const = 0;
318 
319  /**
320  * \brief Check if this query is a sequential query.
321  *
322  * @return true if the query is a sequential query, false otherwise.
323  * @throw SystemException if the query is not compiled or has been closed.
324  * @see close()
325  * @see compile(...)
326  */
327  virtual bool
328  isSequential() const = 0;
329 
330  /** \brief Save the compiled execution plan.
331  *
332  * After compiling an XQuery program you can save the execution plan in some
333  * persistent storage. The execution plan is saved in a platform-independent
334  * format. You can later load this execution plan into a different XQuery
335  * object (potentially on a different machine) and execute it like it was
336  * compiled in place.
337  *
338  * @param os The output stream into which the execution plan is saved.
339  * @param archive_format Specify which output format to use. Possible values
340  * are ZORBA_USE_BINARY_ARCHIVE and ZORBA_USE_XML_ARCHIVE. The binary
341  * format is much smaller than XML format, but is not human readable.
342  * @param save_options Specify some options to the plan serializer.
343  * Current possible values are:
344  * \li DONT_SAVE_UNUSED_FUNCTIONS (default):
345  * to eliminate unused functions and reduce plan size
346  * \li SAVE_UNUSED_FUNCTIONS:
347  * to save everything, as if the xquery contains an eval instruction.
348  * This is useful if you intend to use StaticContext::containsFunction
349  * or StaticContext::findFunctions.
350  * @return true if success.
351  * @throw ZorbaException if the query has not been compiled or there are
352  * problems serializing the execution plan.
353  */
354  virtual bool
355  saveExecutionPlan(std::ostream &os,
358 
359  /**
360  * \brief Load execution plan.
361  *
362  * The serialized execution plan contains a general version for the entire
363  * archive and specific versions for each class. Zorba does not quarantee
364  * that it can load execution plans saved with previous versions of Zorba.
365  * In most cases there will be no problems, but the complete backward
366  * compatibility cannot be quaranteed.
367  *
368  * The engine automatically detects the format of the input, either XML or binary.
369  *
370  * @param is Reference to std::istream.
371  * @param aCallback optional callback handler (see SerializationCallback)
372  * that is used to retrieve information that has not been serialized
373  * (e.g. external modules).
374  * @return true if success.
375  * @throw ZorbaException if there are problems loading the execution plan.
376  */
377  virtual bool
378  loadExecutionPlan(std::istream& is, SerializationCallback* aCallback = 0) = 0;
379 
380  /**
381  * \brief Close the query and release all of its aquired ressources.
382  *
383  * While a query is compiled and/or active, it holds on to a number of
384  * resources. Before Zorba can be safely shutdown, all resources must
385  * be released. For queries this can be done by calling close. However,
386  * if close is not called explicitly, it will be automatically called by
387  * the XQuery object's destructor, when the last smart pointer pointing
388  * this XQuery object is destroyed.
389  *
390  * Note: After an XQuery object is closed, calling close() again on the
391  * same object is a noop. However, calling any method other than close()
392  * on a closed XQuery object is prohibited (an error will be raised).
393  *
394  * Note: if an iterator has been created to retreive the result of an
395  * XQuery object (@see iterator()), that itrator will be closed when
396  * the query is closed, and the association between XQuery object and
397  * Iterator object will be destroyed.
398  */
399  virtual void
400  close() = 0;
401 
402  /**
403  * \brief Check if this query object has already been closed.
404  *
405  * @return true if the query has been closed already or false otherwise.
406  */
407  virtual bool
408  isClosed() const = 0;
409 
410  /**
411  * \brief Clone this query object in order to execute the query in another
412  * thread.
413  *
414  * Although two or more threads may invoke one of the execute methods on the
415  * same XQuery object, these invocations are serialized internally. For true
416  * parallel excetution of a query by multiple threads, the XQuery object needs
417  * to be cloned, using this method. However, note that if an DiagnosticHandler has
418  * been provided by the user (see registerDiagnosticHandler()), this DiagnosticHandler
419  * will also be used in the cloned query, and as a result, the user should
420  * provide a thread-safe DiagnosticHandler. Alternatively, a new DiagnosticHandler can
421  * be registered in the cloned query by using registerDiagnosticHandler again.
422  * Or, the cloned query can be reset to use the default DiagnosticHandler (which
423  * just throws exceptions) by calling resetDiagnosticHandler.
424  *
425  * This function also clones the StaticContext and DynamicContext of the
426  * XQuery object. In the DynamicContext of the cloned query different
427  * variable values can be used, e.g. set different external variable
428  * values. For an example of cloning a query and setting different values
429  * in the dynamic context see example_10 in file \link simple.cpp \endlink.
430  *
431  * @return The cloned XQuery object.
432  * @throw SystemException if the query has not been compiled or is closed.
433  */
434  virtual XQuery_t
435  clone() const = 0;
436 
437 #ifdef ZORBA_WITH_DEBUGGER
438  /**
439  * \brief Enable/disable debug mode on the query
440  */
441  virtual void
442  setDebugMode(bool aDebugMode) = 0;
443 
444  /**
445  * \brief Check if the debug mode is activated.
446  *
447  * @return true if the debug mode is enabled, false otherwise.
448  */
449  virtual bool
450  isDebugMode() const = 0;
451 #endif
452 
453  /**
454  * \brief Set the filename of the profile
455  *
456  * This file will contain the output of Zorba profiler.
457  */
458  virtual void
459  setProfileName( std::string aProfileName ) = 0;
460 
461  /**
462  * \brief Get the filename of the profile
463  *
464  * This file will contain the output of Zorba profiler.
465  */
466  virtual std::string
467  getProfileName() const = 0;
468 
469 #ifdef ZORBA_WITH_DEBUGGER
470  /**
471  * \brief Start a debugger server.
472  *
473  * This method will start a debugger server that will try to connect
474  * to a DBGP-enabled debugger client on the indicated socket (host and port).
475  * In order to call this method, the query has to be compiled.
476  *
477  * @param hort the host where the debugger client is listening.
478  * @param port the port on which the debugger client is listening.
479  *
480  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
481  * not been compiled, the server cannot connect to the client, etc.)
482  */
483  virtual void
484  debug(
485  const std::string& host,
486  unsigned short port) = 0;
487 
488  /**
489  * \brief Start a debugger server.
490  *
491  * This method will start a debugger server that will try to connect
492  * to a DBGP-enabled debugger client on the indicated socket (host and port).
493  * In order to call this method, the query has to be compiled.
494  * You can specify an output stream and serialization options that can be used
495  * by the serializer.
496  *
497  * @param outStream the output stream on which the result is written.
498  * @param serOptions the serialization options.
499  * @param hort the host where the debugger client is listening.
500  * @param port the port on which the debugger client is listening.
501  *
502  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
503  * not been compiled, the server cannot connect to the client, etc.)
504  */
505  virtual void
506  debug(
507  std::ostream& outStream,
508  Zorba_SerializerOptions& serOptions,
509  const std::string& host,
510  unsigned short port) = 0;
511 
512 
513  virtual void
514  debug(
515  std::ostream& outStream,
516  itemHandler callbackFunction,
517  void* callbackData,
518  Zorba_SerializerOptions& serOptions,
519  const std::string& host,
520  unsigned short port) = 0;
521 #endif
522 
523  /** \brief Returns a CollectionManager responsible for all collections
524  * which are statically declared in the static context of this query
525  * (main module) or any transitively imported library module.
526  *
527  * The collection manager provides a set of functions for managing
528  * collections and their contents.
529  *
530  * @return The collection manager responsible for managing
531  * collections of this query.
532  *
533  */
534  virtual StaticCollectionManager*
535  getStaticCollectionManager() const = 0;
536 
537  /** \brief Returns the QName of all external variables
538  *
539  * @param aVarsIter iterator to store the results.
540  * @throw ZorbaException if an error occured.
541  */
542  virtual void
543  getExternalVariables(Iterator_t& aVarsIter) const = 0;
544 
545  /**
546  *
547  */
548  virtual double
549  getDocLoadingUserTime() const = 0;
550 
551  /**
552  *
553  */
554  virtual double
555  getDocLoadingTime() const = 0;
556 
557  /**
558  * \brief Parse the given module String.
559  *
560  * This function parses the module string and returns some information
561  * about the module.
562  *
563  * @param aQuery the query file to parse.
564  * @param aResult some information about the module
565  * @throw ZorbaException if an error occurs while parsing the query.
566  */
567  virtual void
568  parse(std::istream& aQuery, ModuleInfo_t& aResult) = 0;
569 };
570 
571 
572 // xml serialization of the query (equiv to calling serialize(os)
573 ZORBA_DLL_PUBLIC
574 std::ostream& operator<< (std::ostream& os, const XQuery_t& aQuery);
575 
576 ZORBA_DLL_PUBLIC
577 std::ostream& operator<< (std::ostream& os, XQuery* aQuery);
578 
579 
580 } /* namespace zorba */
581 
582 #endif
583 /* vim:set et sw=2 ts=2: */