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>
28 #include <zorba/xmldatamanager.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  */
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: */
virtual ~DynamicContext()
Destructor.
The Zorba Item interface.
Definition: item.h:60
The Zorba string class.
Definition: zorba_string.h:33
Instances of the class DynamicContext contain the information that is available at the time the query...
Instances of subclasses of this abstract class may be used as parameters to the DynamicContext::addEx...