XQuery.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_XQUERY_H
17 #define API_XQUERY_H
18 
19 /**
20  * \brief This class is the representation of an %XQuery in the %Zorba engine.
21  *
22  * To compile and execute an XQuery, an instance of this class must be created.
23  * This is done by using either the createQuery or compileQuery methods of the
24  * Zorba class.
25  *
26  */
27 class XQuery
28 {
29 private:
30  zorba::XQuery_t theQuery;
31  bool closed;
32 
33 public:
34  XQuery():closed(false) {}
35  XQuery(const XQuery& aXQuery) : theQuery(aXQuery.theQuery), closed(aXQuery.closed) {}
36  XQuery(zorba::XQuery_t aQuery) : theQuery(aQuery), closed(false) {}
37 
38  /**
39  * \brief Execute the query. The query can be executed with this function.
40  * The query only has a result if it's a non-updating query.
41  *
42  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
43  * not been compiled or is not updating)
44  */
45  std::string execute();
46 
47  /**
48  * \brief Print the execution plan of this query to a given string.
49  *
50  * @return A String with the output.
51  * @throw ZorbaException if the query has been closed or is not compiled.
52  */
53  std::string printPlanAsXML();
54 
55  /**
56  * \brief Print the execution plan of this query to a given string.
57  *
58  * @return A String with the output.
59  * @throw ZorbaException if the query has been closed or is not compiled.
60  */
61  std::string printPlanAsDOT();
62 
63  /**
64  * \brief Compile a query given as a String.
65  *
66  * @param aQuery the query String to compile.
67  * @throw ZorbaException if the query has been closed, is already compiled, or
68  * an error occurs while compiling the query.
69  */
70  void compile (const std::string &aQuery);
71 
72  /**
73  * \brief Compile a query given as a String, using a given static context and
74  * compiler hints.
75  *
76  * @param aQuery the query String to compile.
77  * @param aStaticContext the static context.
78  * @throw ZorbaException if the query has been closed, is already compiled, or
79  * an error occurs while compiling the query.
80  */
81  void compile (const std::string &aQuery, StaticContext &aStaticContext);
82 #ifdef SWIGPYTHON
83  /**
84  * \brief Serialize the query result as SAX events and call the callbacks
85  * of the SAX2_ContentHandler that is given as input
86  *
87  * @param contentHandlerProxy the content handler on which SAX callbacks are called.
88  */
89  void executeSAX(SAX2ContentHandlerProxy* contentHandlerProxy);
90 #endif
91 
92  /** /brief deletes this object from memory
93  */
94  void destroy();
95 
96  /**
97  * \brief Get an iterator for the result of the query. Allows an application
98  * to lazily execute the query, retrieving the result one item at a time.
99  *
100  * @return Iterator iterator over the result sequence.
101  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
102  * not been compiled).
103  */
104  Iterator iterator();
105 
106  /**
107  * \brief Get the dynamic context of this query.
108  *
109  * This function returns the dynamic context that belongs to this query and
110  * is used during query execution. The context can be used, for example, to
111  * set values of external variables, the default collation, or the current
112  * datetime. It is only available if the query has been compiled, otherwise
113  * an error is reported. Moreover, the context must not be modified during the
114  * execution of a query (i.e. if a Iterator is opened). The lifetime of the
115  * context returned by this function is restricted by the lifetime of the
116  * according query object.
117  *
118  * @throw SystemException if the query has not been compiled or is closed.
119  * @return DynamicContext of this query.
120  */
122 
123  /**
124  * \brief Get the static context of this query.
125  *
126  * This function returns the static context that belongs to this query. The
127  * static context is only available if the query has been compiled, otherwise
128  * an error is reported. The context has all the components and values that
129  * were set in the static context that was passed when creating the query and
130  * those that were set in the prolog of the query. Note that after compilation
131  * of the query the static context is a read only structure. Moreover, the
132  * lifetime of the context returned by this function is restricted by the
133  * lifetime of the corresponding query object.
134  *
135  * @throw SystemException if the query has not been compiled or is closed.
136  * @return StaticContext of this query.
137  */
139 
140  /** \brief Returns a CollectionManager responsible for all collections
141  * which are statically declared in the static context of this query
142  * (main module) or any transitively imported library module.
143  *
144  * The collection manager provides a set of functions for managing
145  * collections and their contents.
146  *
147  * @return The collection manager responsible for managing
148  * collections of this query.
149  *
150  */
152 
153  /** \brief Returns the QName of all external variables
154  *
155  * @param vars iterator to store the results.
156  * @throw ZorbaException if an error occured.
157  */
158  void getExternalVariables(Iterator& vars) const;
159 
160  /** \brief Execute the query and write the result to the given output stream.
161  * The query only has a result if it's a non-updating query.
162  *
163  * @param stream The output stream on which the result is written.
164  */
165  void execute( ZorbaIOStream & stream );
166 
167  /** \brief Execute the query and write the result to the given output stream.
168  * The query only has a result if it's a non-updating query.
169  *
170  * @param stream The output stream on which the result is written.
171  * @param serOptions The serialization options for this Query result
172  */
173  void execute( ZorbaIOStream & stream, SerializationOptions & serOptions );
174 
175  /**
176  * \brief Execute the query. The query can be executed with this function.
177  * The query only has a result if it's a non-updating query.
178  *
179  * @param serOptions The serialization options for this Query result
180  * @throw ZorbaException if an error occurs (e.g. the query is closed or has
181  * not been compiled or is not updating)
182  */
183  std::string execute( SerializationOptions & serOptions );
184 
185 }; // class XQuery
186 
187 #endif