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
Item getCurrentDateTime()
Retrieve the dateTime Item used at the time the query is executed (see setCurrentDateTime()).
DynamicContext(zorba::DynamicContext *aCtx)
bool getContextItem(Item &aItem)
bool setVariable(const std::string &aNamespace, const std::string &aLocalname, Iterator &aIter)
Defines the external variable identified by an expanded QName and assigns it the sequence that is ret...
Item getDefaultCollection()
Return the value of the default collection that is used when calling the fn:collection function witho...
The Zorba Item interface.
Definition: Item.h:39
DynamicContext(const DynamicContext &aCtx)
bool setContextItem(Item &aItem)
Defines the context item.
int getImplicitTimezone()
Retrieve the implicit timezone used in comparisons or arithmetic operations of date, time, or dateTime values.
bool setCurrentDateTime(Item &aDateTimeItem)
Defines the value of the current date time that can be accessed by the fn:current-dateTime() function...
Interface for an Iterator over an instance of the XML Data Model (i.e., a sequence of items)...
Definition: Iterator.h:32
Instances of the class DynamicContext contain the information that is available at the time the query...
bool setImplicitTimezone(int aTimezone)
Defines the variable of the implicit timezone to be used when a date, time, or dateTime value that do...
bool setDefaultCollection(Item &aCollectionUri)
Defines the value of the default collection that is used when calling the fn:collection function with...
bool getVariable(const std::string &aNamespace, const std::string &aLocalname, Item &aItem, Iterator &aIterator)
Returns the current value of an external variable.