static_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 XQP_STATIC_CONTEXT_API_H
00017 #define XQP_STATIC_CONTEXT_API_H
00018 
00019 #include <zorba/config.h>
00020 #include <zorba/api_shared_types.h>
00021 #include <zorba/zorba_string.h>
00022 #include <zorba/typeident.h>
00023 #include <zorba/static_context_consts.h>
00024 #include <zorba/options.h>  // for compiler hints class
00025 #include <vector>
00026 #include <zorba/function.h>
00027 #include <zorba/annotation.h>
00028 #include <zorba/smart_ptr.h>
00029 
00030 namespace zorba {
00031 
00032   /** \brief Instances of the class StaticContext contain the information that is available
00033    *         at the time the query is compiled.
00034    *
00035    * This class contains the information that is defined in the %XQuery specification
00036    * (see http://www.w3.org/TR/xquery/#static_context).
00037    *
00038    * A StaticContext can be created by calling Zorba::createStaticContext and then be passed
00039    * to the Zorba::compileQuery or XQuery::compile functions.
00040    * If no static context has been passed to any of these functions, a default static context
00041    * is used. It can be accessed by calling XQuery::getStaticContext on a compiled XQuery object.
00042    *
00043    * Note: This class is reference counted. When writing multi-threaded clients,
00044    * it is the responibility of the client code to synchronize assignments to the
00045    * SmartPtr holding this object.
00046    */
00047   class ZORBA_DLL_PUBLIC StaticContext : public SmartObject
00048   {
00049     public:
00050       /** \brief Destructor
00051        */
00052       virtual ~StaticContext() {}
00053 
00054       /** \brief Loads the declarations and definitions of a given XQuery prolog into
00055        *         this static context.
00056        *
00057        * This function compiles the prolog passed as first parameter and loads
00058        * all declarations and definitions into this static context.
00059        *
00060        * The static context extended by this prolog can then be used for creating
00061        * a compiling a new query.
00062        *
00063        * A StaticException is raised if the prolog could not be compiled or
00064        * if the prolog does not contain valid declarations (e.g. duplicate declarations).
00065        */
00066       virtual void
00067       loadProlog(const String&, const Zorba_CompilerHints_t &hints) = 0;
00068 
00069       /** \brief Create a child static context, i.e. a context with the same information,
00070        *         of the given static context.
00071        *
00072        * A child static context carries the same context as it's parent but
00073        * can override any information.
00074        */
00075       virtual StaticContext_t
00076       createChildContext() const = 0;
00077 
00078       /** \brief Add a pair (prefix, URI) to the statically known namespaces that
00079        *         are available during query compilation.
00080        *
00081        *  See http://www.w3.org/TR/xquery/#static_context.
00082        *
00083        *  @param aPrefix the prefix String.
00084        *  @param aURI the URI String.
00085        *  @return true if the pair was added to the set of statically known namespaces,
00086        *          false otherwise.
00087        *  @throw ZorbaException if an error occures.
00088        */
00089       virtual bool
00090       addNamespace( const String& aPrefix, const String& aURI ) = 0;
00091 
00092       /** \brief Get the namespace URI for a given prefix.
00093        *
00094        * @param aPrefix the prefix for which to retrieve the namespace URI.
00095        * @return String the URI for the given prefix or an empty String if no URI
00096        *         could be found for the given prefix and an DiagnosticHandler has been
00097        *         registered.
00098        * @throw ZorbaException if an error occured (e.g. no URI could be found for the given prefix).
00099        */
00100       virtual String
00101       getNamespaceURIByPrefix( const String& aPrefix ) const = 0;
00102 
00103       /** \brief Set the default element and type namespace
00104        *         (see http://www.w3.org/TR/xquery/#static_context)
00105        *
00106        * @param aURI of the default element and type namespace URI.
00107        * @return true if the default element and type namespace URI has been set, false otherwise
00108        *         if an DiagnosticHandler has been registered.
00109        * @throw ZorbaException if an error occured.
00110        */
00111       virtual bool
00112       setDefaultElementAndTypeNamespace( const String& aURI ) = 0;
00113 
00114       /** \brief Get the default element and type namespace URI.
00115        *
00116        * @return String the URI for the default element and type namespace.
00117        * @throw ZorbaException if an error occured.
00118        */
00119       virtual String
00120       getDefaultElementAndTypeNamespace( ) const = 0;
00121 
00122       /** \brief Set the default functionnamespace
00123        *         (see http://www.w3.org/TR/xquery/#static_context)
00124        *
00125        * @param aURI of the default function namespace.
00126        * @return true if the default function namespace URI has been set, false otherwise
00127        *         if an DiagnosticHandler has been registered.
00128        * @throw ZorbaException if an error occured.
00129        */
00130       virtual bool
00131       setDefaultFunctionNamespace( const String& aURI ) = 0;
00132 
00133       /** \brief Get the default function namespace.
00134        *
00135        * @return String the URI of the default function namespace.
00136        *         DiagnosticHandler has been registered.
00137        * @throw ZorbaException if an error occured.
00138        */
00139       virtual String
00140       getDefaultFunctionNamespace( ) const = 0;
00141 
00142       /** \brief Adds a collation URI.
00143        *
00144        * The URI specifies the locale and collation strength of the collation that is added.
00145        * A valid collation URI must begin with %http://www.zorba-xquery.com/collations/.
00146        * This prefix is followed by a collation strength (i.e. PRIMARY, SECONDARY, TERTIARY,
00147        * QUATTERNARY, or IDENTICAL) followed by a '/'.
00148        * After the strength a lower-case two- or three-letter ISO-639 language code must follow.
00149        * The URI may end with an upper-case two-letter ISO-3166.
00150        * For example, %http://www.zorba-xquery.com/collations/PRIMARY/en/US
00151        * specifies an english language with US begin the country..
00152        *
00153        * Internally, ICU is used for comparing strings. For detailed description see
00154        * http://www.icu-project.org/apiref/icu4c/classCollator.html
00155        * and http://www.icu-project.org/apiref/icu4c/classLocale.html
00156        *
00157        * @param aURI the URI of the collation.
00158        * @throw ZorbaException if an error occured (e.g. the URI was not a valid
00159        *        collation URI).
00160        */
00161       virtual void
00162       addCollation( const String& aURI ) = 0;
00163 
00164       /** \brief Set the URI of the default collation.
00165        *         (see http://www.w3.org/TR/xquery/#static_context)
00166        *
00167        * @param aURI URI of the default collation.
00168        * @throw ZorbaException if an error occured (e.g., the URI does not
00169        *        identify a collation among the statically known collations.
00170        */
00171       virtual void
00172       setDefaultCollation( const String& aURI ) = 0;
00173 
00174       /** \brief Get the URI of the default collation
00175        *
00176        * @return String the URI of the default collation.
00177        */
00178       virtual String
00179       getDefaultCollation() const = 0;
00180 
00181       /** \brief Set the XQuery processing mode (version 1.0 or 3.0).
00182        *
00183        *
00184        * @param aMode the XQuery version.
00185        * @return true if the version was set, false otherwise.
00186        */
00187       virtual bool
00188       setXQueryVersion( xquery_version_t aMode ) = 0;
00189 
00190       /** \brief Get the XQuery processing mode (version 1.0 or 3.0).
00191        *
00192        *
00193        * @return xquery_version_t the XQuery version processing mode.
00194        */
00195       virtual xquery_version_t
00196       getXQueryVersion( ) const = 0;
00197 
00198       /** \brief Set the XPath 1.0 compatibility mode.
00199        *         (see http://www.w3.org/TR/xquery/#static_context)
00200        *
00201        * @param aMode the XPath 1.0 compatibility mode.
00202        * @return true if the mode was set, false otherwise.
00203        */
00204       virtual bool
00205       setXPath1_0CompatibMode( xpath1_0compatib_mode_t aMode ) = 0;
00206 
00207       /** \brief Get the XPath 1.0 compatibility mode.
00208        *         (see http://www.w3.org/TR/xquery/#static_context)
00209        *
00210        * @return xpath1_0compatib_mode_t the XPath 1.0 compatibility mode.
00211        */
00212       virtual xpath1_0compatib_mode_t
00213       getXPath1_0CompatibMode( ) const = 0;
00214 
00215       /** \brief Set the construction mode.
00216        *         (see http://www.w3.org/TR/xquery/#static_context)
00217        *
00218        * @param aMode the construction mode.
00219        * @return true if the mode was set, false otherwise.
00220        */
00221       virtual bool
00222       setConstructionMode( construction_mode_t aMode ) = 0;
00223 
00224       /** \brief Get the construction mode.
00225        *         (see http://www.w3.org/TR/xquery/#static_context)
00226        *
00227        * @return construction_mode_t the construction mode.
00228        */
00229       virtual construction_mode_t
00230       getConstructionMode( ) const = 0;
00231 
00232       /** \brief Set the ordering mode.
00233        *         (see http://www.w3.org/TR/xquery/#static_context)
00234        *
00235        * @param aMode the ordering mode.
00236        * @return true if the mode was set, false otherwise.
00237        */
00238       virtual bool
00239       setOrderingMode( ordering_mode_t aMode ) = 0;
00240 
00241       /** \brief Get the ordering mode.
00242        *         (see http://www.w3.org/TR/xquery/#static_context)
00243        *
00244        * @return ordering_mode_t the ordering mode.
00245        */
00246       virtual ordering_mode_t
00247       getOrderingMode( ) const = 0;
00248 
00249       /** \brief Set the default order for the empty sequence.
00250        *         (see http://www.w3.org/TR/xquery/#static_context)
00251        *
00252        * @param aMode the default order for the empty sequence.
00253        * @return true if the mode was set, false otherwise.
00254        */
00255       virtual bool
00256       setDefaultOrderForEmptySequences( order_empty_mode_t aMode ) = 0;
00257 
00258       /** \brief Get the default order for the empty sequence.
00259        *         (see http://www.w3.org/TR/xquery/#static_context)
00260        *
00261        * @return order_empty_mode_t the ordering mode.
00262        */
00263       virtual order_empty_mode_t
00264       getDefaultOrderForEmptySequences( ) const = 0;
00265 
00266       /** \brief Set the boundary space policy.
00267        *         (see http://www.w3.org/TR/xquery/#static_context)
00268        *
00269        * @param aMode the boundary space policy.
00270        * @return true if the mode was set, false otherwise.
00271        */
00272       virtual bool
00273       setBoundarySpacePolicy( boundary_space_mode_t aMode) = 0;
00274 
00275       /** \brief Get the boundary space policy.
00276        *         (see http://www.w3.org/TR/xquery/#static_context)
00277        *
00278        * @return boundary_space_mode_t the boundary space policy.
00279        */
00280       virtual boundary_space_mode_t
00281       getBoundarySpacePolicy( ) const = 0;
00282 
00283       /** \brief Set the copy namespace mode.
00284        *         (see http://www.w3.org/TR/xquery/#static_context)
00285        *
00286        * @param aPreserve the preserve mode.
00287        * @param aInherit the inherit mode.
00288        * @return true if the mode was set, false otherwise.
00289        */
00290       virtual bool
00291       setCopyNamespacesMode( preserve_mode_t aPreserve,
00292                              inherit_mode_t aInherit ) = 0;
00293 
00294       /** \brief Get the copy namespace mode.
00295        *         (see http://www.w3.org/TR/xquery/#static_context)
00296        *
00297        * @return aPreserve the preserve mode.
00298        * @return aInherit the inherit mode.
00299        */
00300       virtual void
00301       getCopyNamespacesMode( preserve_mode_t& aPreserve,
00302                              inherit_mode_t& aInherit ) const = 0;
00303 
00304       /** \brief Set the base URI.
00305        *         (see http://www.w3.org/TR/xquery/#static_context)
00306        *
00307        * @param aBaseURI the base URI as String.
00308        * @return true if the base URI has been set, false otherwise.
00309        */
00310       virtual bool
00311       setBaseURI( const String& aBaseURI ) = 0;
00312 
00313       /** \brief Get the base URI.
00314        *
00315        * @return String the base URI.
00316        */
00317       virtual String
00318       getBaseURI( ) const = 0;
00319 
00320       /** \brief Get the revalidation mode.
00321        *
00322        * @return the revalidation mode.
00323        */
00324       virtual validation_mode_t
00325       getRevalidationMode() const = 0;
00326 
00327       /** \brief Set the revalidation mode.
00328        *
00329        * @param aMode the revalidation mode.
00330        */
00331       virtual void
00332       setRevalidationMode(validation_mode_t aMode) = 0;
00333 
00334       /** \brief Register a module providing access to external functions.
00335        *
00336        * Register a module that provides access to external functions.
00337        * The caller keeps the ownership of the Module and the StatelessExternalFunction
00338        * objects passed to this function.
00339        *
00340        * @param aModule the module object
00341        * @return true if the module has been set, false otherwise.
00342        */
00343       virtual bool
00344       registerModule(ExternalModule* aModule) = 0;
00345 
00346       /**
00347        * \brief Register a URI Mapper which will transform a given URI
00348        * into several alternate potential URIs.
00349        *
00350        * QQQ doc
00351        */
00352       virtual void
00353       registerURIMapper(URIMapper* aMapper) = 0;
00354 
00355       /**
00356        * \brief Register a URL Resolver which will transform a given
00357        * URL into a Resource.
00358        *
00359        * QQQ doc
00360        */
00361       virtual void
00362       registerURLResolver(URLResolver* aResolver) = 0;
00363 
00364       /** \brief Set the type of a statically known document
00365        */
00366       virtual void
00367       setDocumentType(const String& aDocUri, TypeIdentifier_t type) = 0;
00368 
00369       /** \brief Get the type of a statically known document
00370        */
00371       virtual TypeIdentifier_t
00372       getDocumentType(const String& aDocUri) const = 0;
00373 
00374       /** \brief Set the type of a statically known collection
00375        */
00376       virtual void
00377       setCollectionType(const String& aCollectionUri, TypeIdentifier_t type) = 0;
00378 
00379       /** \brief Get the type of a statically known collection
00380        */
00381       virtual TypeIdentifier_t
00382       getCollectionType(const String& aCollectionUri) const = 0;
00383 
00384       /** \brief Check if a function with the given name and arity are registered in the context.
00385        */
00386       virtual bool
00387       containsFunction(const String& aFnNameUri, const String& aFnNameLocal, int arity) const = 0;
00388 
00389       virtual void
00390       findFunctions(const Item& aQName, std::vector<Function_t>& aFunctions) const = 0;
00391 
00392       virtual void
00393       disableFunction(const Function_t& aFunction) = 0;
00394 
00395       virtual void
00396       disableFunction(const Item& aQName, int arity) = 0;
00397 
00398       virtual void
00399       getFunctionAnnotations(const Item& aQName, int arity, std::vector<Annotation_t>& aAnnotations) const = 0;
00400 
00401       /** \brief Set the type of the context item.
00402        */
00403       virtual void
00404       setContextItemStaticType(TypeIdentifier_t type) = 0;
00405 
00406       /** \brief Fetch the type of the context item.
00407        */
00408       virtual TypeIdentifier_t
00409       getContextItemStaticType() const = 0;
00410 
00411       /** \brief Set the output stream that is used by the fn:trace function
00412        *
00413        * Sets the output stream that is used by the fn:trace function to the given output stream.
00414        * The default stream is std::cerr.
00415        *
00416        */
00417       virtual void
00418       setTraceStream(std::ostream&) = 0;
00419 
00420       /** \brief Resets the output stream that is used by the fn:trace function to std::cerr
00421        */
00422       virtual void
00423       resetTraceStream() = 0;
00424 
00425       /** \brief Get an option that was declared using the declare option syntax
00426        *
00427        * @param aQName The QName of the option to get.
00428        * @param aOptionValue The value of the option if found.
00429        * @return true if the option was found, false otherwise.
00430        */
00431       virtual bool
00432       getOption( const Item& aQName, String& aOptionValue) const = 0;
00433 
00434       /** \brief Declare an option (same as using declare option in XQuery)
00435        *
00436        * @param aQName The QName of the option to declare.
00437        * @param aOptionValue The value of the option to declare.
00438        */
00439       virtual void
00440       declareOption( const Item& aQName, const String& aOptionValue) = 0;
00441 
00442       virtual void
00443       setModulePaths( const std::vector<String>& aModulePaths ) = 0;
00444 
00445       virtual void
00446       getModulePaths( std::vector<String>& aModulePaths ) const = 0;
00447 
00448       virtual void
00449       getFullModulePaths( std::vector<String>& aFullModulePaths ) const = 0;
00450 
00451       /** \brief Resolves the given URI against the value of the base-uri
00452        * property from the static context.
00453        *
00454        * @param aRelativeUri The relative URI to be resolved.
00455        */
00456       virtual String
00457       resolve(const String& aRelativeUri) const = 0;
00458 
00459       /** \brief Resolves the given relative URI against the absolute base URI.
00460        *
00461        * @param aRelativeUri The relative URI to be resolved.
00462        * @param aBaseUri The absolute URI against which the resolving is performed.
00463        */
00464       virtual String
00465       resolve(const String& aRelativeUri, const String& aBaseUri) const = 0;
00466 
00467       /** \brief Validates this Item.
00468         *  Note: works only on document and element nodes, otherwise returns false.
00469         * 
00470         * @param rootElement the root of the tree beeing validated
00471         * @param validatedResult the result of the validation
00472         * @param validationMode Validation mode: default value is validate_strict
00473         * @return true if validation is correct, false if validation is disabled, throws errors if validation fails
00474         * @throw ZorbaException if any validation error occured
00475         */
00476       virtual bool
00477       validate(
00478           const Item& rootElement,
00479           Item& validatedResult,
00480           validation_mode_t validationMode = validate_strict
00481         ) const = 0;
00482 
00483       /** \brief Validates this Item while loading the schema for targetNamespace
00484         *  Note: works only on document or element nodes, otherwise returns false.
00485         *
00486         * @param rootElement the root of the tree beeing validated 
00487         * @param validatedResult the result of the validation
00488         * @param targetNamespace the expected namespace of root of the tree beeing validated ???
00489         * @param validationMode Validation mode: default value is validate_strict
00490         * @return true if validation is correct, false if validation is disabled, throws errors if validation fails
00491         * @throw ZorbaException if any validation error occured
00492         */
00493       virtual bool 
00494       validate(
00495           const Item& rootElement,
00496           Item& validatedResult, 
00497           const String& targetNamespace,
00498           validation_mode_t validationMode = validate_strict
00499         ) const = 0;
00500   
00501       /** \brief Validates stringValue as XML simple content, i.e. the text value of attributes or 
00502         * text only element content.
00503         * 
00504         * @param stringValue the value to be validated
00505         * @param typeQName
00506         * @param resultList the result of the validation, a vector of atomic Items
00507         * @return true if validation is correct, false if validation is disabled, throws errors if validation fails
00508         * @throw ZorbaException if any validation error occured
00509         */
00510       virtual bool 
00511       validateSimpleContent(
00512           const String& stringValue,
00513           const Item& typeQName, 
00514           std::vector<Item>& resultList
00515         ) const= 0;
00516 
00517       /** \brief Invokes the XQuery function with the given name and
00518        *  the given parameters.
00519        *
00520        *  Note that the function to be invoked needs to be declared in this static
00521        *  context. In order to declare a function in the static context, the
00522        *  loadProlog method of this class can be used.
00523        *
00524        *  Also note that if the function to be invoked is an updating function,
00525        *  its resulting pending update list is implicitly applied by this function.
00526        *
00527        * @param aQName the name of the function to be invoked
00528        * @param aArgs a vector of ItemSequences. One entry in the vector
00529        *        corresponds to one argument that is passed to the function.
00530        *
00531        * @return The result of the function that is invoked. If the function
00532        *   to be invoked is an updating function, the resulting item sequence
00533        *   is empty.
00534        */
00535       virtual ItemSequence_t
00536       invoke(const Item& aQName,
00537              const std::vector<ItemSequence_t>& aArgs) const = 0;
00538 
00539       /** \brief Returns a CollectionManager responsible for all collections
00540        * which are statically declared in this static context.
00541        *
00542        * The collection manager provides a set of functions for managing
00543        * collections and their contents.
00544        *
00545        * @return The collection manager responsible for managing
00546        *   collections of this context.
00547        *
00548        */
00549      virtual StaticCollectionManager*
00550      getStaticCollectionManager() const = 0;
00551 
00552       /**
00553         * @brief sets the audit event that will be populated during execution
00554         *
00555         * @param anEvent the audit event
00556         */
00557       virtual void
00558       setAuditEvent(audit::Event* anEvent) = 0;
00559 
00560       /**
00561         * @brief gets the audit event that is populated during execution
00562         *
00563         * @return the audit event
00564         */
00565       virtual audit::Event*
00566       getAuditEvent() = 0;
00567 
00568 };
00569 } /* namespace zorba */
00570 #endif
00571 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus