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