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: */