Zorba
The XQuery Processor
Documentation
Live Demo
Modules
Download
Tools
Blog
Code
Main Page
Related Pages
Classes
Files
File List
File Members
swig
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
*/
60
StaticContext
createStaticContext
();
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
*/
69
XQuery
createQuery
();
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
*/
97
ItemFactory
getItemFactory
();
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
*/
158
XmlDataManager
getXmlDataManager
();
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
/** \brief Creates and compiles an XQuery object.
206
*
207
* This methods creates an XQuery object and compiles the query string
208
* passed to this method.
209
*
210
* @param stream the query stream, this object is an extension to stream data accross the API.
211
* @return XQuery the newly created and compiled XQuery object.
212
*/
213
XQuery
compileQuery
(
ZorbaIOStream
& stream);
214
215
/** \brief Creates and compiles an XQuery object using a StaticContext.
216
*
217
* This methods creates an XQuery object and compiles the query string
218
* passed to this method. Compilation is done using the information
219
* contained in the StaticContext that is passed as parameter.
220
*
221
* @param stream the query stream, this object is an extension to stream data accross the API.
222
* @param aStaticContext the StaticContext that contains information used for compiling the query.
223
* @return XQuery the newly created and compiled XQuery object.
224
*/
225
XQuery
compileQuery
(
ZorbaIOStream
& stream,
StaticContext
&aStaticContext );
226
227
};
// class Zorba
228
229
#endif