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: XQuery()34 XQuery():closed(false) {} XQuery(const XQuery & aXQuery)35 XQuery(const XQuery& aXQuery) : theQuery(aXQuery.theQuery), closed(aXQuery.closed) {} XQuery(zorba::XQuery_t aQuery)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 */ 121 DynamicContext getDynamicContext(); 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 */ 138 StaticContext getStaticContext(); 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 */ 151 StaticCollectionManager getStaticCollectionManager(); 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