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 #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: */
blog comments powered by Disqus