user_exception.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus