zorba.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 XQP_ZORBA_API_H
17 #define XQP_ZORBA_API_H
18 
19 #include <istream>
20 
21 #include <zorba/config.h>
22 #include <zorba/api_shared_types.h>
23 #include <zorba/collection.h>
24 #include <zorba/dynamic_context.h>
26 #include <zorba/item.h>
27 #include <zorba/item_factory.h>
28 #include <zorba/options.h>
29 #include <zorba/static_context.h>
30 #include <zorba/version.h>
31 #include <zorba/xmldatamanager.h>
32 #include <zorba/document_manager.h>
34 #include <zorba/xquery.h>
35 #include <zorba/zorba_string.h>
36 #include <zorba/iterator.h>
37 #include <zorba/properties_base.h>
38 
39 namespace zorba {
40 
41 /**
42  * The Zorba class is the single point of access to the %Zorba engine.
43  * There exists one instance of the Zorba class per process.
44  * It can be used to (1) create and compile queries,
45  * (2) create static contexts,
46  * (3) provides access to the XmlDataManager,
47  * (4) provides access to the ItemFactory, and
48  * (5) provides access to the PropertiesGlobal.
49  */
50 class ZORBA_DLL_PUBLIC Zorba
51 {
52  public:
53 
54  /** \brief Gets the singleton instance of the Zorba object.
55  *
56  * The Zorba object provides factory methods for creating and/or compiling
57  * XQuery objects, creating StaticContext objects, and accessing components
58  * as, for example, the ItemFactory or the XmlDataManager.
59  *
60  * The first time this function is called, the %Zorba Engine is initialized.
61  * Thereby, it initializes all the libraries that are used in the system, i.e.
62  * ICU, libxml2, xerces, and libcurl.
63  *
64  * @return Zorba the singleton Zorba object
65  *
66  */
67  static Zorba*
68  getInstance(void* store);
69 
70  /** \brief Get information about the used version of %Zorba.
71  *
72  * @return Version information about the used %Zorba version.
73  */
74  static const Version&
75  version();
76 
77 
78  /** \brief Destructor.
79  *
80  * The destructor is called during static deinitialization if getInstance
81  * has been called at least once before.
82  */
83  virtual ~Zorba();
84 
85  /** \brief Releases all resources aquired by the Zorba %XQuery Engine.
86  *
87  * Also releases resources aquired by the libraries used (i.e. icu,
88  * libxml2, xerces, libcurl).
89  *
90  * Before calling shutdown, all xquery objects, items, contexts, ... have
91  * to be closed or gone out of scope; otherwise this call may fail.
92  *
93  * After shutdown has been called, any calls to zorba are invalid.
94  *
95  * getInstance may be used to reinitialize the engine.
96  *
97  */
98  virtual void
99  shutdown() = 0;
100 
101  /** \brief Creates an XQuery object.
102  *
103  * This methods creates an XQuery object without implicitliy assigning it
104  * a query. An object returned by this method can be compiled (see compileQuery).
105  *
106  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
107  * an DiagnosticHandler is passed as parameter, each error that occurs during
108  * compiling or executing the query, is reported to the passed error handler.
109  * If no DiagnosticHandler is given, exceptions are thrown for each of these errors.
110  *
111  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
112  * @return XQuery the newly created XQuery object.
113  */
114  virtual XQuery_t
115  createQuery(DiagnosticHandler* aDiagnosticHandler = 0) = 0;
116 
117  /** \brief Creates and compiles an XQuery object.
118  *
119  * This methods creates an XQuery object and compiles the query string
120  * passed to this method.
121  *
122  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
123  * an DiagnosticHandler is passed as parameter, each error that occurs during
124  * compiling or executing the query, is reported to the passed error handler.
125  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
126  *
127  * @param aQuery the query string for the new XQuery object.
128  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
129  * @return XQuery the newly created and compiled XQuery object.
130  */
131  virtual XQuery_t
132  compileQuery(const String& aQuery, DiagnosticHandler* aDiagnosticHandler = 0) = 0;
133 
134  /** \brief Creates and compiles an XQuery object using a StaticContext.
135  *
136  * This methods creates an XQuery object and compiles the query string
137  * passed to this method. Compilation is done using the information
138  * contained in the StaticContext that is passed as parameter.
139  *
140  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
141  * an DiagnosticHandler is passed as parameter, each error that occurs during
142  * compiling or executing the query, is reported to the passed error handler.
143  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
144  *
145  * @param aQuery the query string for the new XQuery object.
146  * @param aContext the StaticContext that contains information used for compiling the query.
147  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
148  * @return XQuery the newly created and compiled XQuery object.
149  */
150  virtual XQuery_t
151  compileQuery(const String& aQuery,
152  const StaticContext_t& aContext,
153  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
154 
155  /** \brief Creates and compiles an XQuery object using the given CompilerHints.
156  *
157  * This methods creates an XQuery object and compiles the query string
158  * passed to this method. Compilation and optimization is done with respect
159  * to the given CompilerHints.
160  *
161  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
162  * an DiagnosticHandler is passed as parameter, each error that occurs during
163  * compiling or executing the query, is reported to the passed error handler.
164  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
165  *
166  * @param aQuery the query string for the new XQuery object.
167  * @param aCompilerHints the CompilerHints used to compile the query.
168  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
169  * @return XQuery the newly created and compiled XQuery object.
170  */
171  virtual XQuery_t
172  compileQuery(const String& aQuery,
173  const Zorba_CompilerHints_t& aCompilerHints,
174  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
175 
176  /** \brief Creates and compiles an XQuery object using the given
177  * CompilerHints and StaticContext.
178  *
179  * This methods creates an XQuery object and compiles the query string
180  * passed to this method. Compilation and optimization is done with respect
181  * to the given CompilerHints. Moreover, compilation is done using the
182  * information contained in the StaticContext.
183  *
184  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
185  * an DiagnosticHandler is passed as parameter, each error that occurs during
186  * compiling or executing the query, is reported to the passed error handler.
187  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
188  *
189  * @param aQuery the query string for the new XQuery object.
190  * @param aContext the StaticContext that contains information used for compiling the query.
191  * @param aCompilerHints the CompilerHints used to compile the query.
192  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
193  * @return XQuery the newly created and compiled XQuery object.
194  */
195  virtual XQuery_t
196  compileQuery(const String& aQuery,
197  const StaticContext_t& aContext,
198  const Zorba_CompilerHints_t& aCompilerHints,
199  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
200 
201  /** \brief Creates and compiles an XQuery object.
202  *
203  * This methods creates an XQuery object and compiles the query that is
204  * passed to this method as an input stream.
205  *
206  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
207  * an DiagnosticHandler is passed as parameter, each error that occurs during
208  * compiling or executing the query, is reported to the passed error handler.
209  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
210  *
211  * @param aQuery the input stream providing the query.
212  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
213  * @return XQuery the newly created and compiled XQuery object.
214  */
215  virtual XQuery_t
216  compileQuery(std::istream& aQuery, DiagnosticHandler* aDiagnosticHandler = 0) = 0;
217 
218  /** \brief Creates and compiles an XQuery object using a StaticContext.
219  *
220  * This methods creates an XQuery object and compiles the query that is
221  * passed to this method as an input stream. Compilation is done using
222  * the information contained in the StaticContext that is passed as
223  * parameter.
224  *
225  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
226  * an DiagnosticHandler is passed as parameter, each error that occurs during
227  * compiling or executing the query, is reported to the passed error handler.
228  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
229  *
230  * @param aQuery the input stream providing the query.
231  * @param aContext the StaticContext that contains information used for compiling the query.
232  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
233  * @return XQuery the newly created and compiled XQuery object.
234  */
235  virtual XQuery_t
236  compileQuery(std::istream& aQuery,
237  const StaticContext_t& aContext,
238  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
239 
240  /** \brief Creates and compiles an XQuery object using the given CompilerHints.
241  *
242  * This methods creates an XQuery object and compiles the query that is
243  * passed to this method as an input stream. Compilation and optimization
244  * is done with respect to the given CompilerHints.
245  *
246  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
247  * an DiagnosticHandler is passed as parameter, each error that occurs during
248  * compiling or executing the query, is reported to the passed error handler.
249  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
250  *
251  * @param aQuery the input stream providing the query.
252  * @param aCompilerHints the CompilerHints used to compile the query.
253  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
254  * @return XQuery the newly created and compiled XQuery object.
255  */
256  virtual XQuery_t
257  compileQuery(std::istream& aQuery,
258  const Zorba_CompilerHints_t& aCompilerHints,
259  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
260 
261  /** \brief Creates and compiles an XQuery object using the given
262  * CompilerHints and StaticContext.
263  *
264  * This methods creates an XQuery object and compiles the query that is
265  * passed to this method as an input stream. Compilation and optimization
266  * is done with respect to the given CompilerHints. Moreover, compilation
267  * is done using the information contained in the StaticContext.
268  *
269  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
270  * an DiagnosticHandler is passed as parameter, each error that occurs during
271  * compiling or executing the query, is reported to the passed error handler.
272  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
273  *
274  * @param aQuery the input stream providing the query.
275  * @param aContext the StaticContext that contains information used for compiling the query.
276  * @param aCompilerHints the CompilerHints used to compile the query.
277  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
278  * @return XQuery the newly created and compiled XQuery object.
279  */
280  virtual XQuery_t
281  compileQuery(std::istream& aQuery,
282  const StaticContext_t& aContext,
283  const Zorba_CompilerHints_t& aCompilerHints,
284  DiagnosticHandler* aDiagnosticHandler = 0) = 0;
285 
286  /** \brief Creates a new StaticContext.
287  *
288  * The method returns a StaticContext object that can be used
289  * for compiling a query. Instances of the StaticContext class are
290  * returned as a smart pointer.
291  * That is, objects of type StaticContext_t are reference counted object
292  * to an dynamically allocated StaticContext object. Hence, each object can h
293  * have multiple owners. The object is deleted if nobody holds on to an StaticContext_t
294  * object anymore.
295  *
296  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
297  * an DiagnosticHandler is passed as parameter, each error that occurs during
298  * setting or getting information out of the StaticContext, is reported to the passed
299  * DiagnosticHandler.
300  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
301  *
302  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
303  * @return StaticContext_t a new StaticContext object.
304  */
305  virtual StaticContext_t
306  createStaticContext(DiagnosticHandler* aDiagnosticHandler = 0) = 0;
307 
308  /** \brief Gets the singleton instance of the ItemFactory.
309  *
310  * @return ItemFactory the singleton instance of the ItemFactory.
311  */
312  virtual ItemFactory*
313  getItemFactory() = 0;
314 
315  /** \brief Gets the singleton instance of the XmlDataManager object.
316  *
317  * @return XmlDataManager the singleton instance of the XmlDataManager.
318  */
319  virtual XmlDataManager*
320  getXmlDataManager() = 0;
321 
322  /** \brief Gets the singleton instance of Zorba's audit provider object.
323  *
324  * @return audit::Provider the singeleton instance of Zorba's audit provider.
325  */
326  virtual audit::Provider*
327  getAuditProvider() = 0;
328 
329  /** \brief Gets the singleton instance of Zorba's properties object.
330  *
331  * @return zorba::Properties the singleton instance of Zorba's properties object.
332  */
333  virtual PropertiesGlobal* getPropertiesGlobal() = 0;
334 
335 }; /* class Zorba */
336 
337 
338 } /* namespace zorba */
339 
340 /**
341  * \example simple.cpp
342  * This is a simple example that demonstrate how to create, compile, and execute queries.
343  *
344  * \example datamanager.cpp
345  * This file contains some examples that demonstrate how the XmlDataManager can be used
346  * to load files, create collection, etc.
347  *
348  * \example context.cpp
349  * This file demonstrates how the ItemFactory can be used to create new Items and
350  * bind the Items to external variables in the dynamic context of a query.
351  *
352  * \example errors.cpp
353  * This file demonstrates how error management and handling is done in Zorba.
354  *
355  * \example serialization.cpp
356  * This file shows examples of how to serialize query results, for example as XML.
357  *
358  * \example sax2.cpp
359  * An example showing XML serialization that is performed using SAX2.
360  *
361  * \example external_functions.cpp
362  * This file shows some simple examples of external functions.
363  *
364  */
365 #endif /* XQP_ZORBA_API_H */
366 
367 /*
368  * Local variables:
369  * mode: c++
370  * End:
371  */
372 /* vim:set et sw=2 ts=2: */
This class provides access to global properties.
Set of hints that can be passed to the query compiler.
Definition: options.h:54
Using the XmlDataManager one can manage documents and collections.
Provide access to the version of Zorba that is used.
Definition: version.h:28
The Zorba string class.
Definition: zorba_string.h:33
When registered with an XQuery object, a DiagnosticHandler handles all exceptions and warnings that o...
The Zorba class is the single point of access to the Zorba engine.
Definition: zorba.h:50
ItemFactory to create Items.
Definition: item_factory.h:38