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: */