DynamicContext.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 API_DYNAMIC_CONTEXT_H
17 #define API_DYNAMIC_CONTEXT_H
18 
19 /** \brief Instances of the class DynamicContext contain the information that is available at the
20  * time the query is executed.
21  *
22  * The class contains the information that is defined in the %XQuery
23  * specification (see http://www.w3.org/TR/xquery/#eval_context).
24  *
25  * A dynamic context always belongs to a particular query and, hence, can be retrieved by
26  * calling getDynamicContext on a compiled query (see XQuery::getDynamicContext()).
27  *
28  */
30 {
31 private:
32  zorba::DynamicContext* theContext;
33 public:
34 
35  DynamicContext():theContext(0) {}
36  DynamicContext(const DynamicContext& aCtx):theContext(aCtx.theContext) {}
37  DynamicContext(zorba::DynamicContext* aCtx):theContext(aCtx) {}
38 
39  bool getContextItem (Item& aItem);
40 
41  /** \brief Retrieve the dateTime Item used at the time the query is executed
42  * (see setCurrentDateTime()).
43  *
44  * @return Item the dateTime Item used at the time the query is executed.
45  */
47 
48  /** \brief Return the value of the default collection that is used when calling the
49  * fn:collection function without a parameter.
50  *
51  * @return Item the default collection that is set in this dynamic context.
52  * @throw ZorbaException if an error occured.
53  */
55 
56  /** \brief Retrieve the implicit timezone used in comparisons or arithmetic operations
57  * of date, time, or dateTime values.
58  *
59  * @return int the implicit timezone. Note that 0 is returned if an error occured
60  * and an DiagnosticHandler is used.
61  * @throw ZorbaException if an error occured.
62  */
63  int getImplicitTimezone ();
64 
65  /** \brief Returns the current value of an external
66  * variable. Exactly one of the two return values (aItem or
67  * aIterator) will be non-null; that is, have isNull() == false.
68  *
69  * The named external variable may be located in the main query or in any
70  * modules imported directly or indirectly by the query.
71  *
72  * @param aNamespace the namespace URI of the variable's expanded QName
73  * @param aLocalname the local name of the variable's expanded QName
74  * @param aItem an Item representing the current (single-item) value of
75  * the external variable.
76  * @param aIterator an Iterator representing the current (possibly
77  * multi-item) value of the external variable.
78  * @return true if the variable has been retrieved successfully, false otherwise.
79  * @throw ZorbaException if an error occured.
80  */
81  bool getVariable (const std::string& aNamespace, const std::string& aLocalname, Item& aItem, Iterator& aIterator);
82 
83  /** \brief Defines the context item.
84  *
85  * @param aItem the Item that is used as value for the context item.
86  * @return true if the context item was set, false otherwise.
87  * @throw ZorbaException if an error occured (e.g. the given Item is not valid).
88  */
89  bool setContextItem (Item& aItem);
90 
91  /** \brief Defines the value of the current date time that can be accessed by the
92  * fn:current-dateTime() function at the time the query is executed.
93  *
94  * If the current date time has not been set explicitly the value of the date
95  * and time is used at the time the query is created or cloned, respectively.
96  *
97  * @param aDateTimeItem the dateTime Item.
98  * @return true if the variable has been set successfully, false otherwise.
99  * @throw ZorbaException if an error occured (e.g. the given Item is invalid
100  * or not a Item of type dateTime)
101  */
102  bool setCurrentDateTime (Item& aDateTimeItem);
103 
104  /** \brief Defines the value of the default collection that is used when calling the
105  * fn:collection function without a parameter.
106  *
107  * @param aCollectionUri the URI of the collection used by the fn:collection function.
108  * @return true if the default collection has been set successfully, false otherwise.
109  * @throw ZorbaException if an error occured.
110  */
111  bool setDefaultCollection (Item& aCollectionUri);
112 
113  /** \brief Defines the variable of the implicit timezone to be used when a date, time,
114  * or dateTime value that does not have a timezone is used in a comparison or
115  * arithmetic operation.
116  *
117  * @param aTimezone the implicit timezone as int that should be used.
118  * @return true if the implicit timezone has been set successfully, false otherwise.
119  * @throw ZorbaException if an error occured.
120  */
121  bool setImplicitTimezone (int aTimezone);
122 
123  /**
124  * \brief Defines the external variable identified by an expanded QName and
125  * assigns it the sequence that is returned by evaluating aIterator.
126  *
127  * The named external variable may be located in the main query or in any
128  * modules imported directly or indirectly by the query.
129  *
130  * @param aNamespace the namespace URI of the variable's expanded QName
131  * @param aLocalname the local name of the variable's expanded QName
132  * @param aIter the Iterator producing the sequence that is assigned
133  * to the variable.
134  * @return true if the variable has been set successfully, false otherwise.
135  * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid).
136  */
137  bool setVariable (const std::string& aNamespace, const std::string& aLocalname, Iterator& aIter);
138 
139  /**
140  * \brief Defines the external variable identified by aQName and assigns it
141  * the value of aItem.
142  *
143  * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a
144  * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal
145  * name, then this method will find the named external variable in the main
146  * query or in any modules imported directly or indirectly by the query. If it
147  * is a lexical QName, then it is only possible to resolve the prefix in the
148  * the context of the main query, hence only external variables in the main
149  * query or those in directly-imported modules may be bound.
150  *
151  * @param aQName the QName that identifies the external variable.
152  * @param aItem the Item that is used as value for the variable.
153  * @return true if the variable has been set, false otherwise.
154  * @throw ZorbaException if an error occured (e.g. the given Item is not valid).
155  */
156  bool setVariable (const std::string& aQName, Item& aItem);
157 
158  /**
159  * \brief Defines the external variable identified by aQName and assigns it
160  * the sequence that is returned by evaluating aIterator.
161  *
162  * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a
163  * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal
164  * name, then this method will find the named external variable in the main
165  * query or in any modules imported directly or indirectly by the query. If it
166  * is a lexical QName, then it is only possible to resolve the prefix in the
167  * the context of the main query, hence only external variables in the main
168  * query or those in directly-imported modules may be bound.
169  *
170  * @param aQName the QName that identifies the external variable.
171  * @param aIterator the Iterator producing the sequence that is assigned
172  * to the variable.
173  * @return true if the variable has been set successfully, false otherwise.
174  * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid).
175  */
176  bool setVariable (const std::string& aQName, Iterator& aIterator);
177 
178 };
179 
180 #endif
blog comments powered by Disqus