function.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_FUNCTION_API_H
00017 #define ZORBA_FUNCTION_API_H
00018 
00019 #include <cstddef>
00020 #include <vector>
00021 
00022 #include <zorba/config.h>
00023 #include <zorba/api_shared_types.h>
00024 #include <zorba/smart_ptr.h>
00025 
00026 namespace zorba {
00027 
00028 class ItemSequence;
00029 
00030 
00031 /**************************************************************************//**
00032   The Function class represents a function that is callable from XQuery code,
00033   and it gives access to the various properties that are specified in the 
00034   declaration of the function within a Prolog.
00035 
00036   Instances of Function are returned by the StaticContext::findFunctions() 
00037   method. To be mopre precise, StaticContext::findFunctions() returns smart
00038   pointers to Function objects. These smart pointers must be destroyed before
00039   the StaticContext object they were obtained from is destroyed.
00040 
00041   Note: Builtin functions are not declared in the Prolog, but the same kind of
00042   properties exist for them as well. So, the Function class works for builtin
00043   functions as well.
00044 *******************************************************************************/
00045 class ZORBA_DLL_PUBLIC Function : public SmartObject
00046 {
00047  public:
00048   /** \brief Destructor
00049    */
00050   virtual ~Function() {}
00051 
00052   /**
00053    * @return True if the function is sequential; false otherwise.
00054    */  
00055   virtual bool
00056   isSequential() const = 0;
00057 
00058   /**
00059    * @return True if the function is updating; false otherwise.
00060    */  
00061   virtual bool
00062   isUpdating() const = 0;
00063 
00064   /**
00065    * @return True if the function is private; false otherwise.
00066    */  
00067   virtual bool
00068   isPrivate() const = 0;
00069 
00070   /**
00071    * @return True if the function is deterministic; false otherwise.
00072    */  
00073   virtual bool
00074   isDeterministic() const = 0;
00075 
00076   /**
00077    *
00078    */
00079   virtual void
00080   getAnnotations(std::vector<Annotation_t>& annotations) const = 0;
00081 
00082   /**
00083    * @return The expanded QName of the function
00084    */
00085   virtual Item
00086   getQName() const = 0;
00087 
00088   /**
00089    * @return The namespace URI of the function QName
00090    */
00091   virtual String
00092   getURI() const = 0;
00093 
00094   /**
00095    * @return The local name of the function QName
00096    */
00097   virtual String
00098   getLocalName() const = 0;
00099 
00100   /**
00101    * @return The arity of the function. If the function is variadic (which is
00102    *         possible only for builtin functions), the result of this method 
00103    *         is non-deterministic.
00104    */
00105   virtual size_t
00106   getArity() const = 0;
00107 
00108   /**
00109    * @return True if the function is variadic; false otherwise
00110    */
00111   virtual bool
00112   isVariadic() const = 0;
00113 
00114   /**
00115    * @return True if the function is an external one; false otherwise
00116    */
00117   virtual bool
00118   isExternal() const = 0;
00119 
00120   /**
00121    * @return True if the function implementation is written in XQuery (or
00122    *         equivalently, it is a non-external function with a Prolog 
00123    *         declaration); false otherwise
00124    */
00125   virtual bool
00126   isXQuery() const = 0;
00127 
00128   /**
00129    * @return True if the function is a builtin one (not declared in any prolog);
00130    *         false otherwise
00131    */
00132   virtual bool
00133   isBuiltin() const = 0;
00134 };
00135 
00136 
00137 /**************************************************************************//**
00138   The ExternalFunction class serves as the base of subclasses that represent
00139   the implementation/body of external functions.
00140 
00141   Instances of ExternalFunction must provide an evaluate method that serves 
00142   as the implementation of the function. During its evaluation, an external 
00143   function may or may not need to access the static and/or dynamic context of 
00144   the invoking XQuery module. If the function implementation does need to 
00145   access either context, the function is referred to as "contextual"; otherwise,
00146   it is "non-contextual".
00147 *******************************************************************************/
00148 class ZORBA_DLL_PUBLIC ExternalFunction
00149 {
00150 public:
00151   typedef std::vector<ItemSequence*> Arguments_t;
00152 
00153  public:
00154   virtual ~ExternalFunction() {}
00155 
00156   /**
00157    * @return The namespace URI of the function QName
00158    */
00159   virtual String
00160   getURI() const = 0;
00161 
00162   /**
00163    * @return The local name of the function QName
00164    */
00165   virtual String
00166   getLocalName() const = 0;
00167 
00168   /**
00169    * @return True if the external function is contextual; false otherwise.
00170    */
00171   virtual bool
00172   isContextual() const = 0;
00173 };
00174 
00175 
00176 /**************************************************************************//**
00177   The NonContextualExternalFunction class serves as the base of subclasses that
00178   represent the implementation of non contextual external functions.
00179 
00180   For each external function, an application must provide a concrete subclass
00181   of this class and "store" an instance of the subclass inside an ExternalModule
00182   object, as described <a href="../../zorba/html/external_functions.html">
00183   here</a>.
00184 *******************************************************************************/
00185 class ZORBA_DLL_PUBLIC NonContextualExternalFunction : public ExternalFunction
00186 {
00187  public:
00188   virtual ~NonContextualExternalFunction() {}
00189 
00190   virtual ItemSequence_t
00191   evaluate(const Arguments_t&) const = 0;
00192 
00193   bool
00194   isContextual() const { return false; }
00195 };
00196 
00197 
00198 /**************************************************************************//**
00199   The ContextualExternalFunction class serves as the base of subclasses that
00200   represent the implementation of contextual external functions. 
00201 
00202   For each external function, an application must provide a concrete subclass
00203   of this class and "store" an instance of the subclass inside an ExternalModule
00204   object, as described <a href="../../zorba/html/external_functions.html">
00205   here</a>.
00206 *******************************************************************************/
00207 class ZORBA_DLL_PUBLIC ContextualExternalFunction : public ExternalFunction
00208 {
00209  public:
00210   virtual ~ContextualExternalFunction() {}
00211 
00212   virtual ItemSequence_t
00213   evaluate(
00214       const Arguments_t&,
00215       const StaticContext*,
00216       const DynamicContext*) const = 0;
00217   
00218   bool
00219   isContextual() const { return true; }
00220 };
00221 
00222 
00223 } /* namespace zorba */
00224 #endif
00225 
00226 /*
00227  * Local variables:
00228  * mode: c++
00229  * End:
00230  */
00231 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus