StaticContext.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef API_STATIC_CONTEXT_H
17 #define API_STATIC_CONTEXT_H
18 
19 #include <zorba/static_context_consts.h>
20 
22 {
23 public:
24  typedef enum {
27  } PreserveMode;
28 
29  typedef enum {
32  } InheritMode;
33 
34  typedef enum {
38 
39  typedef enum {
43 
44  typedef enum {
48 
49  typedef enum {
52  } OrderingMode;
53 
54  typedef enum {
59 
60  typedef enum {
64 
65 }; // ZorbaConstants
66 
67  /** \brief Instances of the class StaticContext contain the information that is available
68  * at the time the query is compiled.
69  *
70  * This class contains the information that is defined in the %XQuery specification
71  * (see http://www.w3.org/TR/xquery/#static_context).
72  *
73  * A StaticContext can be created by calling Zorba::createStaticContext and then be passed
74  * to the Zorba::compileQuery or XQuery::compile functions.
75  * If no static context has been passed to any of these functions, a default static context
76  * is used. It can be accessed by calling XQuery::getStaticContext on a compiled XQuery object.
77  *
78  */
80 {
81 friend class Zorba;
82 friend class XQuery;
83 
84 private:
85  zorba::StaticContext_t theStaticContext;
86 public:
87 
88  StaticContext(const StaticContext& aStaticContext);
89  StaticContext(zorba::StaticContext_t aStaticContext);
90 
91  /** \brief Adds a collation URI.
92  *
93  * The URI specifies the locale and collation strength of the collation that is added.
94  * A valid collation URI must begin with %http://www.zorba-xquery.com/collations/.
95  * This prefix is followed by a collation strength (i.e. PRIMARY, SECONDARY, TERTIARY,
96  * QUATTERNARY, or IDENTICAL) followed by a '/'.
97  * After the strength a lower-case two- or three-letter ISO-639 language code must follow.
98  * The URI may end with an upper-case two-letter ISO-3166.
99  * For example, %http://www.zorba-xquery.com/collations/PRIMARY/en/US
100  * specifies an english language with US begin the country..
101  *
102  * Internally, ICU is used for comparing strings. For detailed description see
103  * http://www.icu-project.org/apiref/icu4c/classCollator.html
104  * and http://www.icu-project.org/apiref/icu4c/classLocale.html
105  *
106  * @param aURI the URI of the collation.
107  * @throw ZorbaException if an error occured (e.g. the URI was not a valid
108  * collation URI).
109  */
110  void addColation(const std::string& aURI);
111 
112  /** \brief Add a pair (prefix, URI) to the statically known namespaces that
113  * are available during query compilation.
114  *
115  * See http://www.w3.org/TR/xquery/#static_context.
116  *
117  * @param aPrefix the prefix String.
118  * @param aURI the URI String.
119  * @return true if the pair was added to the set of statically known namespaces,
120  * false otherwise.
121  * @throw ZorbaException if an error occures.
122  */
123  bool addNamespace(const std::string& aPrefix,
124  const std::string& aURI);
125 
126  /** \brief Check if a function with the given name and arity are registered in the context.
127  */
128  bool containsFunction(const std::string &aFnNameUri,
129  const std::string &aFnNameLocal,
130  int arity) const;
131 
132  /** \brief Create a child static context, i.e. a context with the same information,
133  * of the given static context.
134  *
135  * A child static context carries the same context as it's parent but
136  * can override any information.
137  */
139 
140  /** \brief Declare an option (same as using declare option in XQuery)
141  *
142  * @param aQName The QName of the option to declare.
143  * @param aOptionVal The value of the option to declare.
144  */
145  void declareOption(const Item &aQName,
146  const std::string &aOptionVal);
147 
148  void disableFunction(const Item &aQName, int arity);
149 
150  /** \brief Get the base URI.
151  *
152  * @return String the base URI.
153  */
154  std::string getBaseURI () const;
155 
156  /** \brief Get the boundary space policy.
157  * (see http://www.w3.org/TR/xquery/#static_context)
158  *
159  * @return boundary_space_mode_t the boundary space policy.
160  */
162 
163  /** \brief Get the construction mode.
164  * (see http://www.w3.org/TR/xquery/#static_context)
165  *
166  * @return construction_mode_t the construction mode.
167  */
169 
170  /** \brief Get the copy namespace mode for Preserve.
171  * (see http://www.w3.org/TR/xquery/#static_context)
172  *
173  * @return aPreserve the preserve mode.
174  */
176 
177  /** \brief Get the copy namespace mode for Preserve.
178  * (see http://www.w3.org/TR/xquery/#static_context)
179  *
180  * @return aInherit the inherit mode.
181  */
183 
184  /** \brief Get the default order for the empty sequence.
185  * (see http://www.w3.org/TR/xquery/#static_context)
186  *
187  * @return order_empty_mode_t the ordering mode.
188  */
190 
191  /** \brief Get the ordering mode.
192  * (see http://www.w3.org/TR/xquery/#static_context)
193  *
194  * @return ordering_mode_t the ordering mode.
195  */
197 
198  /** \brief Get the revalidation mode.
199  *
200  * @return the revalidation mode.
201  */
203 
204  /** \brief Get the XPath 1.0 compatibility mode.
205  * (see http://www.w3.org/TR/xquery/#static_context)
206  *
207  * @return xpath1_0compatib_mode_t the XPath 1.0 compatibility mode.
208  */
210 
211  /** \brief Get the URI of the default collation
212  *
213  * @return String the URI of the default collation.
214  */
215  std::string getDefaultCollation () const;
216 
217  /** \brief Get the default element and type namespace URI.
218  *
219  * @return String the URI for the default element and type namespace.
220  * @throw ZorbaException if an error occured.
221  */
222  std::string getDefaultElementAndTypeNamespace () const;
223 
224  /** \brief Get the default function namespace.
225  *
226  * @return String the URI of the default function namespace.
227  * DiagnosticHandler has been registered.
228  * @throw ZorbaException if an error occured.
229  */
230  std::string getDefaultFunctionNamespace () const;
231 
232  /**
233  * \brief Get the list of all namespace bindings (prefix, uri)
234  * declared in this and its parent static contexts.
235  */
236  std::vector< std::pair< std::string, std::string > > getNamespaceBindings ();
237 
238  /** \brief Get the namespace URI for a given prefix.
239  *
240  * @param aPrefix the prefix for which to retrieve the namespace URI.
241  * @return String the URI for the given prefix or an empty String if no URI
242  * could be found for the given prefix and an DiagnosticHandler has been
243  * registered.
244  * @throw ZorbaException if an error occured (e.g. no URI could be found for the given prefix).
245  *
246  * @deprecated This function is deprecated. Use getNamespaceBindings instead.
247  */
248  std::string getNamespaceURIByPrefix(const std::string &aPrefix) const;
249 
250  /** \brief Get an option that was declared using the declare option syntax
251  *
252  * @param aQName The QName of the option to get.
253  * @param aOptionValue The value of the option if found.
254  * @return true if the option was found, false otherwise.
255  */
256  bool getOption(const Item &aQName, std::string &aOptionValue) const;
257 
258  /** \brief Loads the declarations and definitions of a given XQuery prolog into
259  * this static context.
260  *
261  * This function compiles the prolog passed as first parameter and loads
262  * all declarations and definitions into this static context.
263  *
264  * The static context extended by this prolog can then be used for creating
265  * a compiling a new query.
266  *
267  * A StaticException is raised if the prolog could not be compiled or
268  * if the prolog does not contain valid declarations (e.g. duplicate declarations).
269  */
270  void loadProlog (const std::string & aProlog, const CompilerHints &hints);
271 
272  /** \brief Returns a CollectionManager responsible for all collections
273  * which are statically declared in this static context.
274  *
275  * The collection manager provides a set of functions for managing
276  * collections and their contents.
277  *
278  * @return The collection manager responsible for managing
279  * collections of this context.
280  *
281  */
283 
284  /** \brief Returns the QName of all external variables within the
285  * static context
286  *
287  * @param vars iterator to store the results.
288  * @throw ZorbaException if an error occured.
289  */
290  void getExternalVariables(Iterator& vars) const;
291 
292  /** \brief Get the type of a statically known collection
293  */
294  TypeIdentifier getCollectionType(const std::string &aCollectionUri);
295 
296  /** \brief Get the type of a statically known document
297  */
298  TypeIdentifier getDocumentType(const std::string &aDocUri);
299 
300  /** \brief Fetch the type of the context item.
301  */
303 
304  /** \brief Set the type of the context item.
305  */
306  void setContextItemStaticType(const TypeIdentifier &aType);
307 
308  /** \brief Resets the output stream that is used by the fn:trace function to std::cerr
309  */
310  void resetTraceStream ();
311 
312  /** \brief Set the base URI.
313  * (see http://www.w3.org/TR/xquery/#static_context)
314  *
315  * @param aBaseURI the base URI as String.
316  * @return true if the base URI has been set, false otherwise.
317  */
318  bool setBaseURI (const std::string &aBaseURI);
319 
320  /** \brief Set the boundary space policy.
321  * (see http://www.w3.org/TR/xquery/#static_context)
322  *
323  * @param aMode the boundary space policy.
324  * @return true if the mode was set, false otherwise.
325  */
327 
328  /** \brief Set the construction mode.
329  * (see http://www.w3.org/TR/xquery/#static_context)
330  *
331  * @param aMode the construction mode.
332  * @return true if the mode was set, false otherwise.
333  */
335 
336  /** \brief Set the copy namespace mode.
337  * (see http://www.w3.org/TR/xquery/#static_context)
338  *
339  * @param aPreserve the preserve mode.
340  * @param aInherit the inherit mode.
341  * @return true if the mode was set, false otherwise.
342  */
344 
345  /** \brief Set the default order for the empty sequence.
346  * (see http://www.w3.org/TR/xquery/#static_context)
347  *
348  * @param aMode the default order for the empty sequence.
349  * @return true if the mode was set, false otherwise.
350  */
352 
353  /** \brief Set the ordering mode.
354  * (see http://www.w3.org/TR/xquery/#static_context)
355  *
356  * @param aMode the ordering mode.
357  * @return true if the mode was set, false otherwise.
358  */
360 
361  /** \brief Set the revalidation mode.
362  *
363  * @param aMode the revalidation mode.
364  */
366 
367  /**
368  * @brief Set the URI lookup path (list of filesystem directories) for this
369  * static context.
370  *
371  * Queries which resolve URIs (for instance, importing modules or schemas)
372  * will look in these directories.
373  */
374  void setURIPath(std::vector< std::string > &aURIPath );
375 
376  /**
377  * @brief Set the library lookup path (list of filesystem directories) for
378  * this static context.
379  *
380  * Queries which import modules that have external function
381  * implementations will look for the implementation of those functions
382  * (shared libraries) in these directories.
383  */
384  void setLIBPath(std::vector< std::string > &aLIBPath );
385 
386  /**
387  * @brief Set the URI and library lookup paths (lists of filesystem
388  * directories) for this static context. Note that calling this method
389  * will override any values previously passed to StaticContext::setURIPath()
390  * and StaticContext::setLibPath().
391  * @deprecated Use StaticContext::setURIPath() and StaticContext::setLibPath().
392  *
393  * Convenience method which adds the listed directories to both the
394  * URI path and Library path for this static context.
395  */
396  void setModulePath(std::vector< std::string > &aModulePath );
397 
398  /** \brief Set the XPath 1.0 compatibility mode.
399  * (see http://www.w3.org/TR/xquery/#static_context)
400  *
401  * @param aMode the XPath 1.0 compatibility mode.
402  * @return true if the mode was set, false otherwise.
403  */
405 
406  /** \brief Set the URI of the default collation.
407  * (see http://www.w3.org/TR/xquery/#static_context)
408  *
409  * @param aURI URI of the default collation.
410  * @throw ZorbaException if an error occured (e.g., the URI does not
411  * identify a collation among the statically known collations.
412  */
413  void setDefaultCollation (const std::string &aURI);
414 
415  /** \brief Set the default element and type namespace
416  * (see http://www.w3.org/TR/xquery/#static_context)
417  *
418  * @param aURI of the default element and type namespace URI.
419  * @return true if the default element and type namespace URI has been set, false otherwise
420  * if an DiagnosticHandler has been registered.
421  * @throw ZorbaException if an error occured.
422  */
423  bool setDefaultElementAndTypeNamespace (const std::string &aURI);
424 
425  /** \brief Set the default functionnamespace
426  * (see http://www.w3.org/TR/xquery/#static_context)
427  *
428  * @param aURI of the default function namespace.
429  * @return true if the default function namespace URI has been set, false otherwise
430  * if an DiagnosticHandler has been registered.
431  * @throw ZorbaException if an error occured.
432  */
433  bool setDefaultFunctionNamespace (const std::string &aURI);
434 
435  /** \brief Destroy this object from memory
436  */
437  void destroy();
438 }; // class StaticContext
439 
440 #endif