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 00017 #ifndef ZORBA_USER_EXCEPTION_API_H 00018 #define ZORBA_USER_EXCEPTION_API_H 00019 00020 #include <vector> 00021 00022 #include <zorba/api_shared_types.h> 00023 #include <zorba/error.h> 00024 #include <zorba/xquery_exception.h> 00025 00026 namespace zorba { 00027 00028 namespace serialization { 00029 class Archiver; 00030 } 00031 00032 /////////////////////////////////////////////////////////////////////////////// 00033 00034 class UserException; 00035 00036 namespace internal { 00037 00038 typedef std::vector<Item> error_object_type; 00039 00040 /** 00041 * \internal 00042 * Makes a UserException. 00043 * This function should not be called directly. 00044 * Instead, the \c USER_EXCEPTION macro should be used. 00045 * 00046 * @param raise_file The C++ source-code file name whence the exception was 00047 * raised. 00048 * @param raise_line The C++ source-code line number whence the exception was 00049 * raised. 00050 * @param ns The error's namespace. 00051 * @param prefix The error's prefix. 00052 * @param localname The error's local-name. 00053 * @param description The error description. 00054 * @param loc The XQuery source-code location. 00055 * @param error_object The error object, if any. 00056 * @return Returns a new UserException. 00057 */ 00058 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_4CC_EL_EOT_X 00059 make_user_exception( char const *raise_file, 00060 ZorbaException::line_type raise_line, 00061 char const *ns, char const *prefix, char const *localname, 00062 char const *description, diagnostic::location const &loc, 00063 error_object_type *error_object = 0 ); 00064 00065 /** 00066 * \internal 00067 * Makes a UserException. 00068 * This function should not be called directly. 00069 * Instead, the \c USER_EXCEPTION macro should be used. 00070 * 00071 * @param raise_file The C++ source-code file name whence the exception was 00072 * raised. 00073 * @param raise_line The C++ source-code line number whence the exception was 00074 * raised. 00075 * @param error The error. 00076 * @param description The error description. 00077 * @param loc The XQuery source-code location. 00078 * @param error_object The error object, if any. 00079 * @return Returns a new UserException. 00080 */ 00081 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_CC_EL_EOT_X 00082 make_user_exception( char const *raise_file, 00083 ZorbaException::line_type raise_line, 00084 Error const &error, char const *description, 00085 diagnostic::location const &loc, 00086 error_object_type *error_object = 0 ); 00087 00088 } // namespace internal 00089 00090 /////////////////////////////////////////////////////////////////////////////// 00091 00092 /** 00093 * A %UserException is-an XQueryException for errors raised via 00094 * <code>fn:error()</code>. 00095 */ 00096 class ZORBA_DLL_PUBLIC UserException : public XQueryException { 00097 public: 00098 typedef internal::error_object_type error_object_type; 00099 00100 /** 00101 * Copy-constructs a %UserException. 00102 * 00103 * @param from The %UserException to copy from. 00104 */ 00105 UserException( UserException const &from ); 00106 00107 /** 00108 * Destroys this %UserException. 00109 */ 00110 ~UserException() throw(); 00111 00112 /** 00113 * Assigns this %UserException from another. 00114 * 00115 * @param from The %UserException to assign from. 00116 * @return Returns \c *this. 00117 */ 00118 UserException& operator=( UserException const &from ); 00119 00120 /** 00121 * Gets the error object associated with this exception. 00122 * 00123 * @return Returns said error object. 00124 */ 00125 error_object_type const& error_object() const throw() { 00126 return error_object_; 00127 } 00128 00129 // inherited 00130 void polymorphic_throw() const; 00131 00132 protected: 00133 // inherited 00134 std::unique_ptr<ZorbaException> clone() const; 00135 00136 private: 00137 error_object_type error_object_; 00138 00139 /** 00140 * Constructs a %UserException. 00141 * 00142 * @param ns The namespace of the error. 00143 * @param prefix The prefix of the error. 00144 * @param locaname The local-name of the error. 00145 * @param raise_file The source-code file name whence the exception was 00146 * raised. 00147 * @param raise_line The source-code line number whence the exception was 00148 * raised. 00149 * @param description The error description. 00150 * @param error_object The error object. 00151 */ 00152 UserException( char const *ns, char const *prefix, char const *localname, 00153 char const *raise_file, line_type raise_line, 00154 char const *description, error_object_type *error_object ); 00155 00156 /** 00157 * Constructs a %UserException. 00158 * 00159 * @param error The error. 00160 * @param raise_file The source-code file name whence the exception was 00161 * raised. 00162 * @param raise_line The source-code line number whence the exception was 00163 * raised. 00164 * @param description The error description. 00165 * @param error_object The error object. 00166 */ 00167 UserException( Error const &error, 00168 char const *raise_file, line_type raise_line, 00169 char const *description, error_object_type *error_object ); 00170 00171 friend UserException internal::make_user_exception( 00172 char const*, line_type, char const*, char const*, char const*, char const*, 00173 internal::diagnostic::location const&, error_object_type* 00174 ); 00175 00176 friend UserException internal::make_user_exception( 00177 char const*, line_type, Error const&, char const*, 00178 internal::diagnostic::location const&, error_object_type* 00179 ); 00180 00181 // for plan serialization 00182 UserException( serialization::Archiver& ); 00183 friend void serialization::operator&( serialization::Archiver&, 00184 ZorbaException*& ); 00185 }; 00186 00187 /** 00188 * Creates a UserException. 00189 * \hideinitializer 00190 */ 00191 #define USER_EXCEPTION(...) \ 00192 ::zorba::internal::make_user_exception( __FILE__, __LINE__, __VA_ARGS__ ) 00193 00194 /** 00195 * Creates a default UserException. 00196 * \hideinitializer 00197 */ 00198 #define DEFAULT_USER_EXCEPTION() \ 00199 ::zorba::internal::make_user_exception( __FILE__, __LINE__ ) 00200 00201 /////////////////////////////////////////////////////////////////////////////// 00202 00203 namespace internal { 00204 00205 /** 00206 * \internal 00207 * Makes a UserException. 00208 * This provides for the: 00209 * \code 00210 * fn:error() 00211 * \endcode 00212 * XQuery function. 00213 * This function should not be called directly. 00214 * Instead, the \c DEFAULT_USER_EXCEPTION macro should be used. 00215 * 00216 * @param raise_file The C++ source-code file name whence the exception was 00217 * raised. 00218 * @param raise_line The C++ source-code line number whence the exception was 00219 * raised. 00220 */ 00221 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_X 00222 make_user_exception( char const *raise_file, 00223 ZorbaException::line_type raise_line ); 00224 00225 /** 00226 * \internal 00227 * Makes a UserException. 00228 * This provides for the: 00229 * \code 00230 * fn:error($error as xs:QName) 00231 * \endcode 00232 * XQuery function. 00233 * This function should not be called directly. 00234 * Instead, the \c USER_EXCEPTION macro should be used. 00235 * 00236 * @param raise_file The C++ source-code file name whence the exception was 00237 * raised. 00238 * @param raise_line The C++ source-code line number whence the exception was 00239 * raised. 00240 * @param error The error code expressed as a QName. 00241 */ 00242 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_X 00243 make_user_exception( char const *raise_file, 00244 ZorbaException::line_type raise_line, 00245 Item const &error ); 00246 00247 /** 00248 * \internal 00249 * Makes a UserException. 00250 * This provides for the: 00251 * \code 00252 * fn:error($error as xs:QName) 00253 * \endcode 00254 * XQuery function. 00255 * This function should not be called directly. 00256 * Instead, the \c USER_EXCEPTION macro should be used. 00257 * 00258 * @param raise_file The C++ source-code file name whence the exception was 00259 * raised. 00260 * @param raise_line The C++ source-code line number whence the exception was 00261 * raised. 00262 * @param error The error code expressed as a QName. 00263 */ 00264 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_X 00265 make_user_exception( char const *raise_file, 00266 ZorbaException::line_type raise_line, 00267 Error const &error ); 00268 00269 /** 00270 * \internal 00271 * Makes a UserException. 00272 * This provides for the: 00273 * \code 00274 * fn:error($error as xs:QName, 00275 * $description as xs:string) 00276 * \endcode 00277 * XQuery function. 00278 * This function should not be called directly. 00279 * Instead, the \c USER_EXCEPTION macro should be used. 00280 * 00281 * @param raise_file The C++ source-code file name whence the exception was 00282 * raised. 00283 * @param raise_line The C++ source-code line number whence the exception was 00284 * raised. 00285 * @param error The error code expressed as a QName. 00286 * @param description The error description. 00287 */ 00288 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_S_X 00289 make_user_exception( char const *raise_file, 00290 ZorbaException::line_type raise_line, 00291 Item const &error, String const &description ); 00292 00293 /** 00294 * \internal 00295 * Makes a UserException. 00296 * This provides for the: 00297 * \code 00298 * fn:error($error as xs:QName, 00299 * $description as xs:string, 00300 * $error-object as item()*) 00301 * \endcode 00302 * XQuery function. 00303 * This function should not be called directly. 00304 * Instead, the \c USER_EXCEPTION macro should be used. 00305 * 00306 * @param raise_file The C++ source-code file name whence the exception was 00307 * raised. 00308 * @param raise_line The C++ source-code line number whence the exception was 00309 * raised. 00310 * @param error The error code expressed as a QName. 00311 * @param description The error description. 00312 * @param error_object The error object. 00313 */ 00314 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_S_IS_X 00315 make_user_exception( char const *raise_file, 00316 ZorbaException::line_type raise_line, 00317 Item const &error, String const &description, 00318 ItemSequence_t const &error_object ); 00319 00320 /** 00321 * \internal 00322 * Makes a UserException. 00323 * This provides for the: 00324 * \code 00325 * fn:error($error as xs:QName, 00326 * $description as xs:string, 00327 * $error-object as item()*) 00328 * \endcode 00329 * XQuery function. 00330 * This function should not be called directly. 00331 * Instead, the \c USER_EXCEPTION macro should be used. 00332 * 00333 * @param raise_file The C++ source-code file name whence the exception was 00334 * raised. 00335 * @param raise_line The C++ source-code line number whence the exception was 00336 * raised. 00337 * @param error The error code expressed as a QName. 00338 * @param description The error description. 00339 * @param error_object The error object. 00340 */ 00341 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_S_IS_X 00342 make_user_exception( char const *raise_file, 00343 ZorbaException::line_type raise_line, 00344 Error const &error, String const &description, 00345 ItemSequence_t const &error_object ); 00346 00347 /** 00348 * \internal 00349 * Makes a UserException. 00350 * This provides for the: 00351 * \code 00352 * fn:error($error as xs:QName, 00353 * $description as xs:string, 00354 * $error-object as item()*) 00355 * \endcode 00356 * XQuery function. 00357 * This function should not be called directly. 00358 * Instead, the \c USER_EXCEPTION macro should be used. 00359 * 00360 * @param raise_file The C++ source-code file name whence the exception was 00361 * raised. 00362 * @param raise_line The C++ source-code line number whence the exception was 00363 * raised. 00364 * @param error The error code expressed as a QName. 00365 * @param description The error description. 00366 * @param error_object The error object. 00367 */ 00368 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_S_EOT_X 00369 make_user_exception( char const *raise_file, 00370 ZorbaException::line_type raise_line, 00371 Error const &error, String const &description, 00372 error_object_type *error_object = 0 ); 00373 00374 /////////////////////////////////////////////////////////////////////////////// 00375 00376 } // namespace internal 00377 } // namespace zorba 00378 #endif /* ZORBA_USER_EXCEPTION_API_H */ 00379 /* vim:set et sw=2 ts=2: */