00001 /* 00002 * Copyright 2006-2008 The FLWOR Foundation. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef ZORBA_DYNAMIC_CONTEXT_API_H 00017 #define ZORBA_DYNAMIC_CONTEXT_API_H 00018 00019 #include <time.h> 00020 #include <istream> 00021 #include <memory> 00022 00023 #include <zorba/config.h> 00024 #include <zorba/api_shared_types.h> 00025 #include <zorba/static_context_consts.h> 00026 #include <zorba/xmldatamanager.h> 00027 #include <zorba/external_function_parameter.h> 00028 00029 00030 namespace zorba { 00031 00032 00033 /** \brief Instances of the class DynamicContext contain the information that is available at the 00034 * time the query is executed. 00035 * 00036 * The class contains the information that is defined in the %XQuery 00037 * specification (see http://www.w3.org/TR/xquery/#eval_context). 00038 * 00039 * A dynamic context always belongs to a particular query and, hence, can be retrieved by 00040 * calling getDynamicContext on a compiled query (see XQuery::getDynamicContext()). 00041 * 00042 */ 00043 class ZORBA_DLL_PUBLIC DynamicContext 00044 { 00045 public: 00046 00047 /** 00048 * \brief Defines the external variable identified by aQName and assigns it 00049 * the value of aItem. 00050 * 00051 * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a 00052 * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal 00053 * name, then this method will find the named external variable in the main 00054 * query or in any modules imported directly or indirectly by the query. If it 00055 * is a lexical QName, then it is only possible to resolve the prefix in the 00056 * the context of the main query, hence only external variables in the main 00057 * query or those in directly-imported modules may be bound. 00058 * 00059 * @param aQName the QName that identifies the external variable. 00060 * @param aItem the Item that is used as value for the variable. 00061 * @return true if the variable has been set, false otherwise. 00062 * @throw ZorbaException if an error occured (e.g. the given Item is not valid). 00063 */ 00064 virtual bool 00065 setVariable( 00066 const String& aQName, 00067 const Item& aItem) = 0; 00068 00069 /** 00070 * \brief Defines the external variable identified by aQName and assigns it 00071 * the sequence that is returned by evaluating aIterator. 00072 * 00073 * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a 00074 * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal 00075 * name, then this method will find the named external variable in the main 00076 * query or in any modules imported directly or indirectly by the query. If it 00077 * is a lexical QName, then it is only possible to resolve the prefix in the 00078 * the context of the main query, hence only external variables in the main 00079 * query or those in directly-imported modules may be bound. 00080 * 00081 * @param aQName the QName that identifies the external variable. 00082 * @param aIterator the Iterator producing the sequence that is assigned 00083 * to the variable. 00084 * @return true if the variable has been set successfully, false otherwise. 00085 * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid). 00086 */ 00087 virtual bool 00088 setVariable( 00089 const String& aQName, 00090 const Iterator_t& aIterator) = 0; 00091 00092 /** 00093 * \brief Defines the external variable identified by an expanded QName and 00094 * assigns it the sequence that is returned by evaluating aIterator. 00095 * 00096 * The named external variable may be located in the main query or in any 00097 * modules imported directly or indirectly by the query. 00098 * 00099 * @param aNamespace the namespace URI of the variable's expanded QName 00100 * @param aLocalname the local name of the variable's expanded QName 00101 * @param aIterator the Iterator producing the sequence that is assigned 00102 * to the variable. 00103 * @return true if the variable has been set successfully, false otherwise. 00104 * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid). 00105 */ 00106 virtual bool 00107 setVariable( 00108 const String& aNamespace, 00109 const String& aLocalname, 00110 const Iterator_t& aIterator) = 0; 00111 00112 /** \brief Returns the current value of an external 00113 * variable. Exactly one of the two return values (aItem or 00114 * aIterator) will be non-null; that is, have isNull() == false. 00115 * 00116 * The named external variable may be located in the main query or in any 00117 * modules imported directly or indirectly by the query. 00118 * 00119 * @param aNamespace the namespace URI of the variable's expanded QName 00120 * @param aLocalname the local name of the variable's expanded QName 00121 * @param aItem an Item representing the current (single-item) value of 00122 * the external variable. 00123 * @param aIterator an Iterator representing the current (possibly 00124 * multi-item) value of the external variable. 00125 * @return true if the variable has been retrieved successfully, false otherwise. 00126 * @throw ZorbaException if an error occured. 00127 */ 00128 virtual bool 00129 getVariable( const String& aNamespace, 00130 const String& aLocalname, 00131 Item& aItem, 00132 Iterator_t& aIterator) const = 0; 00133 00134 /** \brief Defines the context item. 00135 * 00136 * @param aItem the Item that is used as value for the context item. 00137 * @return true if the context item was set, false otherwise. 00138 * @throw ZorbaException if an error occured (e.g. the given Item is not valid). 00139 */ 00140 virtual bool 00141 setContextItem ( const Item& aItem ) = 0; 00142 00143 /** \brief Returns the current value of the context item. 00144 * 00145 * @param aItem an Item representing the current value of the context item. 00146 * @return true if the variable has been retrieved successfully, false otherwise. 00147 * @throw ZorbaException if an error occured. 00148 */ 00149 virtual bool 00150 getContextItem( Item& aItem ) const = 0; 00151 00152 /** \brief Defines the value of the current date time that can be accessed by the 00153 * fn:current-dateTime() function at the time the query is executed. 00154 * 00155 * If the current date time has not been set explicitly the value of the date 00156 * and time is used at the time the query is created or cloned, respectively. 00157 * 00158 * @param aDateTimeItem the dateTime Item. 00159 * @return true if the variable has been set successfully, false otherwise. 00160 * @throw ZorbaException if an error occured (e.g. the given Item is invalid 00161 * or not a Item of type dateTime) 00162 */ 00163 virtual bool 00164 setCurrentDateTime( const Item& aDateTimeItem ) = 0; 00165 00166 /** \brief Retrieve the dateTime Item used at the time the query is executed 00167 * (see setCurrentDateTime()). 00168 * 00169 * @return Item the dateTime Item used at the time the query is executed. 00170 */ 00171 virtual Item 00172 getCurrentDateTime( ) const = 0; 00173 00174 /** \brief Defines the variable of the implicit timezone to be used when a date, time, 00175 * or dateTime value that does not have a timezone is used in a comparison or 00176 * arithmetic operation. 00177 * 00178 * @param aTimezone the implicit timezone as int that should be used. 00179 * @return true if the implicit timezone has been set successfully, false otherwise. 00180 * @throw ZorbaException if an error occured. 00181 */ 00182 virtual bool 00183 setImplicitTimezone( int aTimezone ) = 0; 00184 00185 /** \brief Retrieve the implicit timezone used in comparisons or arithmetic operations 00186 * of date, time, or dateTime values. 00187 * 00188 * @return int the implicit timezone. Note that 0 is returned if an error occured 00189 * and an DiagnosticHandler is used. 00190 * @throw ZorbaException if an error occured. 00191 */ 00192 virtual int 00193 getImplicitTimezone() const = 0; 00194 00195 /** \brief Defines the value of the default collection that is used when calling the 00196 * fn:collection function without a parameter. 00197 * 00198 * @param aCollectionUri the URI of the collection used by the fn:collection function. 00199 * @return true if the default collection has been set successfully, false otherwise. 00200 * @throw ZorbaException if an error occured. 00201 */ 00202 virtual bool 00203 setDefaultCollection( const Item& aCollectionUri ) = 0; 00204 00205 /** \brief Return the value of the default collection that is used when calling the 00206 * fn:collection function without a parameter. 00207 * 00208 * @return Item the default collection that is set in this dynamic context. 00209 * @throw ZorbaException if an error occured. 00210 */ 00211 virtual Item 00212 getDefaultCollection() const = 0; 00213 00214 /** \brief Add a name-value pair to this context. 00215 * The value can be accessed in the evaluate method 00216 * of external functions (see ContextualExternalFunction). 00217 * 00218 * @param aName the name of the parameter to add. If an entry with 00219 * the same name already exists, the existing entry is replaced. 00220 * @param aValue the value that can be accessed in the evaluate method. 00221 * @return returns true if an entry with the same name did not already exist, 00222 * false otherwise. 00223 */ 00224 virtual bool 00225 addExternalFunctionParam( const String& aName, void* aValue ) = 0; 00226 00227 /** \brief Get the value of a pair that was registered using 00228 * the addExternalFunctionParam method. This can 00229 * be used in the evaluate method 00230 * of external functions (see ContextualExternalFunction). 00231 * 00232 * @param aName the name of the parameter to retrieve 00233 * @param aValue the value matching the given name if true is returned. 00234 * @return true if an entry with the given name was found, 00235 * false otherwise. 00236 */ 00237 virtual bool 00238 getExternalFunctionParam ( const String& aName, void*& aValue ) const = 0; 00239 00240 /** \brief Add a name-value pair to this context. 00241 * The value can be accessed in the evaluate method 00242 * of external functions (see ContextualExternalFunction). 00243 * 00244 * @param aName the name of the parameter to add. If an entry with 00245 * the same name already exists, the existing entry is replaced. 00246 * @param aParam the parameter to add 00247 * @return true if an entry with the same name did not exist already, 00248 * false otherwise. 00249 */ 00250 virtual bool 00251 addExternalFunctionParameter ( const String& aName, ExternalFunctionParameter* aParam ) = 0; 00252 00253 /** \brief Get the value of a pair that was registered using 00254 * the addExternalFunctionParam method. This can 00255 * be used in the evaluate method 00256 * of external functions (see ContextualExternalFunction). 00257 * 00258 * @param aName the name of the parameter to retrieve 00259 * @return the ExternalFunctionParameter* that was added using 00260 * addExternalFunctionParameter, or 0 if no entry with the given 00261 * name was found. 00262 */ 00263 virtual ExternalFunctionParameter* 00264 getExternalFunctionParameter ( const String& aName ) const = 0; 00265 00266 /** \brief Returns true if the variable is bound to a value 00267 * 00268 * @param aNamespace the namespace of the qname of the variable to check 00269 * @param aLocalname the localname of the qname of the variable to check 00270 */ 00271 virtual bool 00272 isBoundExternalVariable(const String& aNamespace, const String& aLocalname) const = 0; 00273 00274 /** \brief Returns true if a context item has been bound to the Dynamic Context 00275 */ 00276 virtual bool 00277 isBoundContextItem() const = 0; 00278 00279 protected: 00280 /** \brief Destructor 00281 */ 00282 virtual ~DynamicContext( ) {} 00283 }; 00284 00285 } /* namespace zorba */ 00286 00287 #endif 00288 /* vim:set et sw=2 ts=2: */