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 00028 00029 namespace zorba { 00030 00031 00032 /** \brief Instances of the class DynamicContext contain the information that is available at the 00033 * time the query is executed. 00034 * 00035 * The class contains the information that is defined in the %XQuery 00036 * specification (see http://www.w3.org/TR/xquery/#eval_context). 00037 * 00038 * A dynamic context always belongs to a particular query and, hence, can be retrieved by 00039 * calling getDynamicContext on a compiled query (see XQuery::getDynamicContext()). 00040 * 00041 */ 00042 class ZORBA_DLL_PUBLIC DynamicContext 00043 { 00044 public: 00045 /** 00046 * \brief Defines the external variable identified by aQName and assigns it 00047 * the value of aItem. 00048 * 00049 * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a 00050 * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal 00051 * name, then this method will find the named external variable in the main 00052 * query or in any modules imported directly or indirectly by the query. If it 00053 * is a lexical QName, then it is only possible to resolve the prefix in the 00054 * the context of the main query, hence only external variables in the main 00055 * query or those in directly-imported modules may be bound. 00056 * 00057 * @param aQName the QName that identifies the external variable. 00058 * @param aItem the Item that is used as value for the variable. 00059 * @return true if the variable has been set, false otherwise. 00060 * @throw ZorbaException if an error occured (e.g. the given Item is not valid). 00061 */ 00062 virtual bool 00063 setVariable( 00064 const String& aQName, 00065 const Item& aItem) = 0; 00066 00067 /** 00068 * \brief Defines the external variable identified by aQName and assigns it 00069 * the sequence that is returned by evaluating aIterator. 00070 * 00071 * aQName may be in one of two forms: A lexical QName (eg. "ns:foo"), or a 00072 * James Clark-style universal name (eg. "{nsuri}:foo"). If it is a universal 00073 * name, then this method will find the named external variable in the main 00074 * query or in any modules imported directly or indirectly by the query. If it 00075 * is a lexical QName, then it is only possible to resolve the prefix in the 00076 * the context of the main query, hence only external variables in the main 00077 * query or those in directly-imported modules may be bound. 00078 * 00079 * @param aQName the QName that identifies the external variable. 00080 * @param aIterator the Iterator producing the sequence that is assigned 00081 * to the variable. 00082 * @return true if the variable has been set successfully, false otherwise. 00083 * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid). 00084 */ 00085 virtual bool 00086 setVariable( 00087 const String& aQName, 00088 const Iterator_t& aIterator) = 0; 00089 00090 /** 00091 * \brief Defines the external variable identified by an expanded QName and 00092 * assigns it the sequence that is returned by evaluating aIterator. 00093 * 00094 * The named external variable may be located in the main query or in any 00095 * modules imported directly or indirectly by the query. 00096 * 00097 * @param aNamespace the namespace URI of the variable's expanded QName 00098 * @param aLocalname the local name of the variable's expanded QName 00099 * @param aIterator the Iterator producing the sequence that is assigned 00100 * to the variable. 00101 * @return true if the variable has been set successfully, false otherwise. 00102 * @throw ZorbaException if an error occured (e.g. the given Iterator is not valid). 00103 */ 00104 virtual bool 00105 setVariable( 00106 const String& aNamespace, 00107 const String& aLocalname, 00108 const Iterator_t& aIterator) = 0; 00109 00110 /** \brief Returns the current value of an external 00111 * variable. Exactly one of the two return values (aItem or 00112 * aIterator) will be non-null; that is, have isNull() == false. 00113 * 00114 * The named external variable may be located in the main query or in any 00115 * modules imported directly or indirectly by the query. 00116 * 00117 * @param aNamespace the namespace URI of the variable's expanded QName 00118 * @param aLocalname the local name of the variable's expanded QName 00119 * @param aItem an Item representing the current (single-item) value of 00120 * the external variable. 00121 * @param aIterator an Iterator representing the current (possibly 00122 * multi-item) value of the external variable. 00123 * @return true if the variable has been retrieved successfully, false otherwise. 00124 * @throw ZorbaException if an error occured. 00125 */ 00126 virtual bool 00127 getVariable( const String& aNamespace, 00128 const String& aLocalname, 00129 Item& aItem, 00130 Iterator_t& aIterator) const = 0; 00131 00132 /** \brief Defines the context item. 00133 * 00134 * @param aItem the Item that is used as value for the context item. 00135 * @return true if the context item was set, false otherwise. 00136 * @throw ZorbaException if an error occured (e.g. the given Item is not valid). 00137 */ 00138 virtual bool 00139 setContextItem ( const Item& aItem ) = 0; 00140 00141 /** \brief Returns the current value of the context item. 00142 * 00143 * @param aItem an Item representing the current value of the context item. 00144 * @return true if the variable has been retrieved successfully, false otherwise. 00145 * @throw ZorbaException if an error occured. 00146 */ 00147 virtual bool 00148 getContextItem( Item& aItem ) const = 0; 00149 00150 /** \brief Defines the value of the current date time that can be accessed by the 00151 * fn:current-dateTime() function at the time the query is executed. 00152 * 00153 * If the current date time has not been set explicitly the value of the date 00154 * and time is used at the time the query is created or cloned, respectively. 00155 * 00156 * @param aDateTimeItem the dateTime Item. 00157 * @return true if the variable has been set successfully, false otherwise. 00158 * @throw ZorbaException if an error occured (e.g. the given Item is invalid 00159 * or not a Item of type dateTime) 00160 */ 00161 virtual bool 00162 setCurrentDateTime( const Item& aDateTimeItem ) = 0; 00163 00164 /** \brief Retrieve the dateTime Item used at the time the query is executed 00165 * (see setCurrentDateTime()). 00166 * 00167 * @return Item the dateTime Item used at the time the query is executed. 00168 */ 00169 virtual Item 00170 getCurrentDateTime( ) const = 0; 00171 00172 /** \brief Defines the variable of the implicit timezone to be used when a date, time, 00173 * or dateTime value that does not have a timezone is used in a comparison or 00174 * arithmetic operation. 00175 * 00176 * @param aTimezone the implicit timezone as int that should be used. 00177 * @return true if the implicit timezone has been set successfully, false otherwise. 00178 * @throw ZorbaException if an error occured. 00179 */ 00180 virtual bool 00181 setImplicitTimezone( int aTimezone ) = 0; 00182 00183 /** \brief Retrieve the implicit timezone used in comparisons or arithmetic operations 00184 * of date, time, or dateTime values. 00185 * 00186 * @return int the implicit timezone. Note that 0 is returned if an error occured 00187 * and an DiagnosticHandler is used. 00188 * @throw ZorbaException if an error occured. 00189 */ 00190 virtual int 00191 getImplicitTimezone() const = 0; 00192 00193 /** \brief Defines the value of the default collection that is used when calling the 00194 * fn:collection function without a parameter. 00195 * 00196 * @param aCollectionUri the URI of the collection used by the fn:collection function. 00197 * @return true if the default collection has been set successfully, false otherwise. 00198 * @throw ZorbaException if an error occured. 00199 */ 00200 virtual bool 00201 setDefaultCollection( const Item& aCollectionUri ) = 0; 00202 00203 /** \brief Return the value of the default collection that is used when calling the 00204 * fn:collection function without a parameter. 00205 * 00206 * @return Item the default collection that is set in this dynamic context. 00207 * @throw ZorbaException if an error occured. 00208 */ 00209 virtual Item 00210 getDefaultCollection() const = 0; 00211 00212 /** \brief Add a name-value pair the this context. 00213 * The value can be accessed in the evaluate method 00214 * of external functions (see NonePureStatelessExternalFunction). 00215 * 00216 * @param aName the name of the parameter to add 00217 * @param aValue the value that can be accessed in the evaluate method. 00218 * @return returns true if an entry with the same name did not already exist, 00219 * false otherwise. 00220 */ 00221 virtual bool 00222 addExternalFunctionParam( const String& aName, void* aValue ) = 0; 00223 00224 /** \brief Get the value of a pair that was registered using 00225 * the addExternalFunctionParam method. This can 00226 * be used in the evaluate method 00227 * of external functions (see NonePureStatelessExternalFunction). 00228 * 00229 * @param aName the name of the parameter to retrieve 00230 * @param aValue the value matching the given name if true is returned. 00231 * @return returns true if an entry with the given name was found, 00232 * false otherwise. 00233 */ 00234 virtual bool 00235 getExternalFunctionParam ( const String& aName, void*& aValue ) const = 0; 00236 00237 protected: 00238 /** \brief Destructor 00239 */ 00240 virtual ~DynamicContext( ) {} 00241 }; 00242 00243 } /* namespace zorba */ 00244 00245 #endif 00246 /* vim:set et sw=2 ts=2: */