Zorba.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2012 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 API_ZORBA_H
17 #define API_ZORBA_H
18 
19 /**
20  * The Zorba class is the single point of access to the %Zorba engine.
21  * There exists one instance of the Zorba class per process.
22  * It can be used to (1) create and compile queries,
23  * (2) create static contexts,
24  * (3) provides access to the XmlDataManager,
25  * (4) provides access to the ItemFactory, and
26  * (5) provides access to the PropertiesGlobal.
27  */
28 class Zorba
29 {
30  private:
31  zorba::Zorba* theZorba;
32  Zorba(zorba::Zorba* aZorba) : theZorba(aZorba){};
33  public:
34  Zorba():theZorba(0){}
35  Zorba(const Zorba& aZorba) : theZorba(aZorba.theZorba) {};
36 
37  /** \brief Gets the singleton instance of the Zorba object.
38  *
39  * The Zorba object provides factory methods for creating and/or compiling
40  * XQuery objects, creating StaticContext objects, and accessing components
41  * as, for example, the ItemFactory or the XmlDataManager.
42  *
43  * The first time this function is called, the %Zorba Engine is initialized.
44  * Thereby, it initializes all the libraries that are used in the system, i.e.
45  * ICU, libxml2, xerces, and libcurl.
46  *
47  * @return Zorba the singleton Zorba object
48  *
49  */
50  static Zorba getInstance(const Store&);
51 
52  /** \brief Creates a new StaticContext.
53  *
54  * The method returns a StaticContext object that can be used
55  * for compiling a query. Instances of the StaticContext class are
56  * returned as a smart pointer.
57  *
58  * @return StaticContext_t a new StaticContext object.
59  */
61 
62  /** \brief Creates an XQuery object.
63  *
64  * This methods creates an XQuery object without implicitliy assigning it
65  * a query. An object returned by this method can be compiled (see compileQuery).
66  *
67  * @return XQuery the newly created XQuery object.
68  */
70 
71  /** \brief Creates and compiles an XQuery object.
72  *
73  * This methods creates an XQuery object and compiles the query string
74  * passed to this method.
75  *
76  * @param aStr the query string for the new XQuery object.
77  * @return XQuery the newly created and compiled XQuery object.
78  */
79  XQuery compileQuery(const std::string& aStr);
80 
81  /** \brief Creates and compiles an XQuery object using a StaticContext.
82  *
83  * This methods creates an XQuery object and compiles the query string
84  * passed to this method. Compilation is done using the information
85  * contained in the StaticContext that is passed as parameter.
86  *
87  * @param aStr the query string for the new XQuery object.
88  * @param aStaticContext the StaticContext that contains information used for compiling the query.
89  * @return XQuery the newly created and compiled XQuery object.
90  */
91  XQuery compileQuery(const std::string& aStr, StaticContext &aStaticContext );
92 
93  /** \brief Gets the singleton instance of the ItemFactory.
94  *
95  * @return ItemFactory the singleton instance of the ItemFactory.
96  */
98 
99  /** \brief Creates and compiles an XQuery object.
100  *
101  * This methods creates an XQuery object and compiles the query string
102  * passed to this method.
103  *
104  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
105  * an DiagnosticHandler is passed as parameter, each error that occurs during
106  * compiling or executing the query, is reported to the passed error handler.
107  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
108  *
109  * @param aStr the query string for the new XQuery object.
110  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
111  * @return XQuery the newly created and compiled XQuery object.
112  */
113  XQuery compileQuery(const std::string& aStr, DiagnosticHandler* aDiagnosticHandler);
114 
115  /** \brief Creates and compiles an XQuery object using a StaticContext.
116  *
117  * This methods creates an XQuery object and compiles the query string
118  * passed to this method. Compilation is done using the information
119  * contained in the StaticContext that is passed as parameter.
120  *
121  * Optionally, this method takes an DiagnosticHandler as parameter. In the case
122  * an DiagnosticHandler is passed as parameter, each error that occurs during
123  * compiling or executing the query, is reported to the passed error handler.
124  * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
125  *
126  * @param aStr the query string for the new XQuery object.
127  * @param aStaticContext the StaticContext that contains information used for compiling the query.
128  * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
129  * @return XQuery the newly created and compiled XQuery object.
130  */
131  XQuery compileQuery(const std::string& aStr, StaticContext &aStaticContext,
132  DiagnosticHandler* aDiagnosticHandler);
133 
134  /** \brief Creates and compiles an XQuery object using the given CompilerHints.
135  *
136  * This methods creates an XQuery object and compiles the query string
137  * passed to this method. Compilation and optimization is done with respect
138  * to the given CompilerHints.
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 aStr the query string for the new XQuery object.
146  * @param aCompilerHints the CompilerHints used to compile 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  XQuery compileQuery(const std::string& aStr, CompilerHints &aCompilerHints,
151  DiagnosticHandler* aDiagnosticHandler);
152 
153 
154  /** \brief Gets the singleton instance of the XmlDataManager object.
155  *
156  * @return XmlDataManager the singleton instance of the XmlDataManager.
157  */
159 
160  /** \brief Releases all resources aquired by the Zorba %XQuery Engine.
161  *
162  * Also releases resources aquired by the libraries used (i.e. icu,
163  * libxml2, xerces, libcurl).
164  *
165  * Before calling shutdown, all xquery objects, items, contexts, ... have
166  * to be closed or gone out of scope; otherwise this call may fail.
167  *
168  * After shutdown has been called, any calls to zorba are invalid.
169  *
170  * getInstance may be used to reinitialize the engine.
171  *
172  */
173  void shutdown();
174 
175  /** \brief Get information about the used version of %Zorba.
176  *
177  * @return Version information about the used %Zorba version.
178  */
179  std::string getVersion();
180 
181  /** \brief Get information about the used version of %Zorba.
182  *
183  * @return Version information about the used %Zorba version.
184  */
185  int getMajorVersion();
186 
187  /** \brief Get information about the used version of %Zorba.
188  *
189  * @return Version information about the used %Zorba version.
190  */
191  int getMinorVersion();
192 
193  /** \brief Get information about the used version of %Zorba.
194  *
195  * @return Version information about the used %Zorba version.
196  */
197  int getPatchVersion();
198 
199  /** \brief Get a boolean value informing if XQueryX is supported.
200  *
201  * @return A boolean value informing if XQueryX is supported.
202  */
203  bool isXQueryXSupported();
204 
205 }; // class Zorba
206 
207 #endif
blog comments powered by Disqus