Zorba
The XQuery Processor
Documentation
Live Demo
Modules
Download
Tools
Blog
Code
Main Page
Related Pages
Namespaces
Classes
Files
Examples
File List
File Members
include
zorba
dynamic_context.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_DYNAMIC_CONTEXT_API_H
17
#define ZORBA_DYNAMIC_CONTEXT_API_H
18
19
#include <
time.h
>
20
#include <istream>
21
#include <memory>
22
23
#include <zorba/config.h>
24
#include <
zorba/locale.h
>
25
#include <
zorba/time.h
>
26
#include <
zorba/api_shared_types.h
>
27
#include <
zorba/static_context_consts.h
>
28
#include <
zorba/xmldatamanager.h
>
29
#include <
zorba/external_function_parameter.h
>
30
31
32
namespace
zorba {
33
34
35
/** \brief Instances of the class DynamicContext contain the information that is available at the
36
* time the query is executed.
37
*
38
* The class contains the information that is defined in the %XQuery
39
* specification (see http://www.w3.org/TR/xquery/#eval_context).
40
*
41
* A dynamic context always belongs to a particular query and, hence, can be retrieved by
42
* calling getDynamicContext on a compiled query (see XQuery::getDynamicContext()).
43
*
44
*/
45
class
ZORBA_DLL_PUBLIC
DynamicContext
46
{
47
public
:
48
49
/**
50
* \brief Defines the external variable identified by aQName and assigns it
51
* the value of aItem.
52
*
53
* aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a
54
* James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal
55
* name, then this method will find the named external variable in the main
56
* query or in any modules imported directly or indirectly by the query. If it
57
* is a lexical QName, then it is only possible to resolve the prefix in the
58
* the context of the main query, hence only external variables in the main
59
* query or those in directly-imported modules may be bound.
60
*
61
* @param aQName the QName that identifies the external variable.
62
* @param aItem the Item that is used as value for the variable.
63
* @return true if the variable has been set, false otherwise.
64
* @throw ZorbaException if an error occured (e.g. the given Item is not valid).
65
*/
66
virtual
bool
67
setVariable(
68
const
String
& aQName,
69
const
Item
& aItem) = 0;
70
71
/**
72
* \brief Defines the external variable identified by aQName and assigns it
73
* the sequence that is returned by evaluating aIterator.
74
*
75
* aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a
76
* James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal
77
* name, then this method will find the named external variable in the main
78
* query or in any modules imported directly or indirectly by the query. If it
79
* is a lexical QName, then it is only possible to resolve the prefix in the
80
* the context of the main query, hence only external variables in the main
81
* query or those in directly-imported modules may be bound.
82
*
83
* @param aQName the QName that identifies the external variable.
84
* @param aIterator the Iterator producing the sequence that is assigned
85
* to the variable.
86
* @return true if the variable has been set successfully, false otherwise.
87
* @throw ZorbaException if an error occured (e.g. the given Iterator is not valid).
88
*/
89
virtual
bool
90
setVariable(
91
const
String
& aQName,
92
const
Iterator_t
& aIterator) = 0;
93
94
/**
95
* \brief Defines the external variable identified by an expanded QName and
96
* assigns it the sequence that is returned by evaluating aIterator.
97
*
98
* The named external variable may be located in the main query or in any
99
* modules imported directly or indirectly by the query.
100
*
101
* @param aNamespace the namespace URI of the variable's expanded QName
102
* @param aLocalname the local name of the variable's expanded QName
103
* @param aIterator the Iterator producing the sequence that is assigned
104
* to the variable.
105
* @return true if the variable has been set successfully, false otherwise.
106
* @throw ZorbaException if an error occured (e.g. the given Iterator is not valid).
107
*/
108
virtual
bool
109
setVariable(
110
const
String
& aNamespace,
111
const
String
& aLocalname,
112
const
Iterator_t
& aIterator) = 0;
113
114
/** \brief Returns the current value of an external
115
* variable. Exactly one of the two return values (aItem or
116
* aIterator) will be non-null; that is, have isNull() == false.
117
*
118
* The named external variable may be located in the main query or in any
119
* modules imported directly or indirectly by the query.
120
*
121
* @param aNamespace the namespace URI of the variable's expanded QName
122
* @param aLocalname the local name of the variable's expanded QName
123
* @param aItem an Item representing the current (single-item) value of
124
* the external variable.
125
* @param aIterator an Iterator representing the current (possibly
126
* multi-item) value of the external variable.
127
* @return true if the variable has been retrieved successfully, false otherwise.
128
* @throw ZorbaException if an error occured.
129
*/
130
virtual
bool
131
getVariable(
const
String
& aNamespace,
132
const
String
& aLocalname,
133
Item
& aItem,
134
Iterator_t
& aIterator)
const
= 0;
135
136
/** \brief Defines the context item.
137
*
138
* @param aItem the Item that is used as value for the context item.
139
* @return true if the context item was set, false otherwise.
140
* @throw ZorbaException if an error occured (e.g. the given Item is not valid).
141
*/
142
virtual
bool
143
setContextItem(
const
Item
& aItem) = 0;
144
145
/** \brief Defines the context item size.
146
*
147
* @param aItem the Item that is used as value for the context item size.
148
* @return true if the context item size was set, false otherwise.
149
* @throw ZorbaException if an error occured (e.g. the given Item is not valid).
150
*/
151
virtual
bool
152
setContextSize(
const
Item
& aItem) = 0;
153
154
/** \brief Defines the context item position.
155
*
156
* @param aItem the Item that is used as value for the context item position.
157
* @return true if the context item position was set, false otherwise.
158
* @throw ZorbaException if an error occured (e.g. the given Item is not valid).
159
*/
160
virtual
bool
161
setContextPosition(
const
Item
& aItem) = 0;
162
163
/** \brief Returns the current value of the context item.
164
*
165
* @param aItem an Item representing the current value of the context item.
166
* @return true if the variable has been retrieved successfully, false otherwise.
167
* @throw ZorbaException if an error occured.
168
*/
169
virtual
bool
170
getContextItem(
Item
& aItem)
const
= 0;
171
172
/** \brief Returns the current value of the context item size.
173
*
174
* @param aItem an Item representing the current value of the context item size.
175
* @return true if the variable has been retrieved successfully, false otherwise.
176
* @throw ZorbaException if an error occured.
177
*/
178
virtual
bool
179
getContextSize(
Item
& aItem)
const
= 0;
180
181
/** \brief Returns the current value of the context item position.
182
*
183
* @param aItem an Item representing the current value of the context item position.
184
* @return true if the variable has been retrieved successfully, false otherwise.
185
* @throw ZorbaException if an error occured.
186
*/
187
virtual
bool
188
getContextPosition(
Item
& aItem)
const
= 0;
189
190
/** \brief Defines the value of the current date time that can be accessed by the
191
* fn:current-dateTime() function at the time the query is executed.
192
*
193
* If the current date time has not been set explicitly the value of the date
194
* and time is used at the time the query is created or cloned, respectively.
195
*
196
* @param aDateTimeItem the dateTime Item.
197
* @return true if the variable has been set successfully, false otherwise.
198
* @throw ZorbaException if an error occured (e.g. the given Item is invalid
199
* or not a Item of type dateTime)
200
*/
201
virtual
bool
202
setCurrentDateTime(
const
Item
& aDateTimeItem ) = 0;
203
204
/** \brief Retrieve the dateTime Item used at the time the query is executed
205
* (see setCurrentDateTime()).
206
*
207
* @return Item the dateTime Item used at the time the query is executed.
208
*/
209
virtual
Item
210
getCurrentDateTime( )
const
= 0;
211
212
/** \brief Defines the variable of the implicit timezone to be used when a date, time,
213
* or dateTime value that does not have a timezone is used in a comparison or
214
* arithmetic operation.
215
*
216
* @param aTimezone the implicit timezone as int that should be used.
217
* @return true if the implicit timezone has been set successfully, false otherwise.
218
* @throw ZorbaException if an error occured.
219
*/
220
virtual
bool
221
setImplicitTimezone(
int
aTimezone ) = 0;
222
223
/** \brief Retrieve the implicit timezone used in comparisons or arithmetic operations
224
* of date, time, or dateTime values.
225
*
226
* @return int the implicit timezone. Note that 0 is returned if an error occured
227
* and an DiagnosticHandler is used.
228
* @throw ZorbaException if an error occured.
229
*/
230
virtual
int
231
getImplicitTimezone()
const
= 0;
232
233
/** \brief Defines the value of the default collection that is used when calling the
234
* fn:collection function without a parameter.
235
*
236
* @param aCollectionUri the URI of the collection used by the fn:collection function.
237
* @return true if the default collection has been set successfully, false otherwise.
238
* @throw ZorbaException if an error occured.
239
*/
240
virtual
bool
241
setDefaultCollection(
const
Item
& aCollectionUri ) = 0;
242
243
/** \brief Return the value of the default collection that is used when calling the
244
* fn:collection function without a parameter.
245
*
246
* @return Item the default collection that is set in this dynamic context.
247
* @throw ZorbaException if an error occured.
248
*/
249
virtual
Item
250
getDefaultCollection()
const
= 0;
251
252
/** \brief Sets the locale.
253
*
254
* @param aLang The language to set.
255
* @param aCountry The country to set.
256
*/
257
virtual
void
258
setLocale(
locale::iso639_1::type
aLang,
259
locale::iso3166_1::type
aCountry ) = 0;
260
261
/** \brief Gets the locale.
262
*
263
* @param aLang A pointer to a \c iso639_1::type to receive the language.
264
* If \c null, this is not set.
265
* @param aCountry A pointer to a \c iso3166_1::type to receive the country.
266
* If \c null, this is not set.
267
*/
268
virtual
void
269
getLocale(
locale::iso639_1::type
*aLang,
270
locale::iso3166_1::type
*aCountry )
const
= 0;
271
272
/** \brief Sets the calendar.
273
*
274
* @param aCalendar The calendar to use.
275
*/
276
virtual
void
277
setCalendar(
time::calendar::type
aCalendar ) = 0;
278
279
/** \brief Gets the current calendar.
280
*
281
* @return the current calendar.
282
*/
283
virtual
time::calendar::type
284
getCalendar()
const
= 0;
285
286
/** \brief Add a name-value pair to this context.
287
* The value can be accessed in the evaluate method
288
* of external functions (see ContextualExternalFunction).
289
*
290
* @param aName the name of the parameter to add. If an entry with
291
* the same name already exists, the existing entry is replaced.
292
* @param aValue the value that can be accessed in the evaluate method.
293
* @return returns true if an entry with the same name did not already exist,
294
* false otherwise.
295
*/
296
virtual
bool
297
addExternalFunctionParam(
const
String
& aName,
void
* aValue ) = 0;
298
299
/** \brief Get the value of a pair that was registered using
300
* the addExternalFunctionParam method. This can
301
* be used in the evaluate method
302
* of external functions (see ContextualExternalFunction).
303
*
304
* @param aName the name of the parameter to retrieve
305
* @param aValue the value matching the given name if true is returned.
306
* @return true if an entry with the given name was found,
307
* false otherwise.
308
*/
309
virtual
bool
310
getExternalFunctionParam (
const
String
& aName,
void
*& aValue )
const
= 0;
311
312
/** \brief Add a name-value pair to this context.
313
* The value can be accessed in the evaluate method
314
* of external functions (see ContextualExternalFunction).
315
*
316
* @param aName the name of the parameter to add. If an entry with
317
* the same name already exists, the existing entry is replaced.
318
* @param aParam the parameter to add
319
* @return true if an entry with the same name did not exist already,
320
* false otherwise.
321
*/
322
virtual
bool
323
addExternalFunctionParameter (
const
String
& aName,
ExternalFunctionParameter
* aParam )
const
= 0;
324
325
/** \brief Get the value of a pair that was registered using
326
* the addExternalFunctionParam method. This can
327
* be used in the evaluate method
328
* of external functions (see ContextualExternalFunction).
329
*
330
* @param aName the name of the parameter to retrieve
331
* @return the ExternalFunctionParameter* that was added using
332
* addExternalFunctionParameter, or 0 if no entry with the given
333
* name was found.
334
*/
335
virtual
ExternalFunctionParameter
*
336
getExternalFunctionParameter (
const
String
& aName )
const
= 0;
337
338
/** \brief Returns true if the variable is bound to a value
339
*
340
* @param aNamespace the namespace of the qname of the variable to check
341
* @param aLocalname the localname of the qname of the variable to check
342
*/
343
virtual
bool
344
isBoundExternalVariable(
const
String
& aNamespace,
const
String
& aLocalname)
const
= 0;
345
346
/** \brief Returns true if a context item has been bound to the Dynamic Context
347
*/
348
virtual
bool
349
isBoundContextItem()
const
= 0;
350
351
protected
:
352
/** \brief Destructor
353
*/
354
virtual
~DynamicContext
( ) {}
355
};
356
357
}
/* namespace zorba */
358
359
#endif
360
/* vim:set et sw=2 ts=2: */
external_function_parameter.h
static_context_consts.h
time.h
zorba::DynamicContext::~DynamicContext
virtual ~DynamicContext()
Destructor.
Definition:
dynamic_context.h:354
api_shared_types.h
zorba::locale::iso639_1::type
type
Definition:
locale.h:29
zorba::Item
The Zorba Item interface.
Definition:
item.h:60
zorba::locale::iso3166_1::type
type
Definition:
locale.h:225
xmldatamanager.h
zorba::String
The Zorba string class.
Definition:
zorba_string.h:33
zorba::time::calendar::type
type
Definition:
time.h:30
locale.h
zorba::SmartPtr
Definition:
smart_ptr.h:51
zorba::DynamicContext
Instances of the class DynamicContext contain the information that is available at the time the query...
Definition:
dynamic_context.h:45
zorba::ExternalFunctionParameter
Instances of subclasses of this abstract class may be used as parameters to the DynamicContext::addEx...
Definition:
external_function_parameter.h:33