dynamic_context.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus