Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/lang/Exception.hpp

00001 /*
00002 * Exception.hpp
00003 *
00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
00005 *
00006 * Oracle is a registered trademarks of Oracle Corporation and/or its
00007 * affiliates.
00008 *
00009 * This software is the confidential and proprietary information of Oracle
00010 * Corporation. You shall not disclose such confidential and proprietary
00011 * information and shall use it only in accordance with the terms of the
00012 * license agreement you entered into with Oracle.
00013 *
00014 * This notice may not be removed or altered.
00015 */
00016 #ifndef COH_EXCEPTION_HPP
00017 #define COH_EXCEPTION_HPP
00018 
00019 #include "coherence/lang/compatibility.hpp"
00020 
00021 #include "coherence/lang/throwable_spec.hpp"
00022 #include "coherence/lang/MemberView.hpp"
00023 #include "coherence/lang/ObjectArray.hpp"
00024 #include "coherence/lang/String.hpp"
00025 #include "coherence/lang/TypedHandle.hpp"
00026 #include "coherence/lang/TypedHolder.hpp"
00027 
00028 #include <iostream>
00029 #include <stdexcept>
00030 
00031 COH_OPEN_NAMESPACE2(coherence,lang)
00032 
00033 
00034 /**
00035 * Base class for all exceptions used in Coherence.
00036 *
00037 * Exceptions are not thrown directly, but rather via the COH_THROW macro. The
00038 * macro will record the stack trace and throw the managed Exception such that
00039 * it may be caught either via its View type, or as a std::exception derivative.
00040 * Unlike standard C++ exceptions, managed exceptions may be caught by value,
00041 * i.e. not using a const& and still be safely re-thrown
00042 * (via the COH_THROW macro) without risking object slicing. This allows caught
00043 * exceptions to be stored as data member or local variables outside of a
00044 * try/catch block and to be safely re-thrown at a later time.
00045 *
00046 * New exception classes are declared using the throwable_spec<> helper template.
00047 *
00048 * @code
00049 * try
00050 *   {
00051 *   ...
00052 *   COH_THROW (IOException::create("some error"));
00053 *   ...
00054 *   }
00055 * catch (IOException::View vIoe)
00056 *   {
00057 *   std::cerr << vIoe << std::endl;
00058 *   ...
00059 *   }
00060 * catch (Exception::View vEx)
00061 *   {
00062 *   std::cerr << vEx << std::endl;
00063 *   ...
00064 *   COH_THROW (vEx); // re-throw managed exception
00065 *   }
00066 * catch (const std::exception& e)
00067 *   {
00068 *   std::cerr << e.what() << std::endl;
00069 *   throw; // re-throw standard exception
00070 *   }
00071 * @endcode
00072 *
00073 * @see throwable
00074 *
00075 * @author mf 2007.05.05
00076 */
00077 class COH_EXPORT Exception
00078     : public throwable_spec<Exception,
00079         extends<Object, std::exception>,
00080         implements<>,
00081         Object::View>
00082     {
00083     friend class factory<Exception>;
00084 
00085     // ----- constructors ---------------------------------------------------
00086 
00087     protected:
00088         /**
00089         * Create a new Exception object
00090         *
00091         * @param vsMsg    the message of the exception
00092         * @param veCause  the underlying cause of the exception;
00093         *                 can be <tt>NULL</tt>
00094         *
00095         * @return a Handle to the created Exception
00096         */
00097         Exception(String::View vsMsg = String::NULL_STRING,
00098                 Exception::View veCause = NULL);
00099 
00100 
00101     // ----- Exception interface --------------------------------------------
00102 
00103     public:
00104         /**
00105         * Return the name of the exception.
00106         */
00107         virtual String::View getName() const;
00108 
00109         /**
00110         * Returns a human-readable description of the Exception.
00111         *
00112         * Note: The String returned is held for the lifetime of this exception
00113         * to guarantee that the result does not go out of scope. This
00114         * method is used by Exception Handles to support the
00115         * std::exception::what() method.
00116         *
00117         * @return the Exception's description
00118         */
00119         virtual String::View getDescription() const;
00120 
00121         /**
00122         * Set the message associated with this exception.
00123         *
00124         * @param vsMsg  the message to set for this exception
00125         */
00126         virtual void setMessage(String::View vsMsg);
00127 
00128         /**
00129         * Return the message associated with this exception.
00130         *
00131         * @return the message associated with this exception
00132         */
00133         virtual String::View getMessage() const;
00134 
00135         /**
00136         * Return the underlying cause associated with this exception.
00137         * The underlying cause is the exception that caused this exception
00138         * to be thrown.
00139         *
00140         * @return the underlying cause associated with this exception;
00141         *         might be <tt>NULL</tt>
00142         */
00143         virtual Exception::View getCause() const;
00144 
00145         /**
00146         * Set the name of the thread on which this exception was thrown.
00147         *
00148         * @param vsThreadName  the thread name
00149         */
00150         virtual void setThreadName(String::View vsThreadName);
00151 
00152         /**
00153         * Return the name of the thread on which the exception was thrown.
00154         *
00155         * @return the name of the thread on which the exception was thrown.
00156         */
00157         virtual String::View getThreadName() const;
00158 
00159         /**
00160         * Set point at which the exception occurred.
00161         *
00162         * @param vaFrames    an array of StackTraceElements
00163         */
00164         virtual void setStackTrace(ObjectArray::View vaFrames);
00165 
00166         /**
00167         * Return the stack trace for the exception.
00168         *
00169         * @return an array of StackTraceElements.
00170         */
00171         virtual ObjectArray::View getStackTrace() const;
00172 
00173         /**
00174         * Fills the execution stack trace based on the current threads stack
00175         * and the supplied information about the current stack frame.
00176         *
00177         * @param vsFile      the file portion of the first stack frame
00178         * @param nLine       the lone portion of the first stack frame
00179         * @param vsFunction  the function portion of the first stack frame
00180         */
00181         virtual Exception::Handle fillInStackTrace(
00182                 String::View vsFile = String::NULL_STRING, int32_t nLine = 0,
00183                 String::View vsFunction = String::NULL_STRING);
00184 
00185         /**
00186         * Print the stack trace to the supplied stream.
00187         *
00188         * @param out  the stream to print the trace to
00189         */
00190         virtual void printStackTrace(std::ostream& out = std::cerr) const;
00191 
00192         /**
00193         * (Re)throw the exception.
00194         *
00195         * The resulting thrown exception may be caught either by it's View
00196         * type, or its alias type.
00197         */
00198         virtual void raise() const;
00199 
00200 
00201     // ----- Object interface -----------------------------------------------
00202 
00203     public:
00204         /**
00205         * {@inheritDoc}
00206         */
00207         virtual void toStream(std::ostream& out) const;
00208 
00209 
00210     // ----- data members ---------------------------------------------------
00211 
00212     protected:
00213         /**
00214         * The message associated with this exception.
00215         */
00216         MemberView<String> m_vsMessage;
00217 
00218         /**
00219         * The stack at the point the exception was thrown
00220         */
00221         MemberView<ObjectArray> m_vaStackFrames;
00222 
00223         /**
00224         * The name of the thread on which the Exception was thrown;
00225         */
00226         MemberView<String> m_vsThreadName;
00227 
00228         /**
00229         * The cause of the exception
00230         */
00231         MemberView<Exception> m_veCause;
00232 
00233         /**
00234         * The detailed human readable description of this exception.
00235         */
00236         mutable MemberView<String> m_vsDescription;
00237     };
00238 
00239 
00240 // ----- helper macros ------------------------------------------------------
00241 
00242 /**
00243 * @hideinitializer
00244 *
00245 * [re]throw a managed exception.  If the exception is referenced via a Handle
00246 * it's stack trace will be set to the current stack location, otherwise the
00247 * stack related information will unchanged.
00248 *
00249 * @param E  the exception to throw
00250 *
00251 * Usage example:
00252 * @code
00253 * COH_THROW(IOException::create("File Not Found"));
00254 * @endcode
00255 */
00256 #define COH_THROW(E) COH_NO_RETURN_STMT( \
00257     coherence::lang::coh_throw((E), __FILE__, __LINE__, COH_CURRENT_FUNCTION))
00258 
00259 /**
00260 * This macro will take the set of streamable contents and convert them to a
00261 * string which will represent the message of the exception being thrown.
00262 *
00263 * @param E         the name of the exception that will be thrown
00264 * @param CONTENTS  the streamable contents of the message to use when creating
00265 *                  the exception above.
00266 *
00267 * Note: This Macro only supports Exceptions that have a constructor that takes
00268 * a single message parameter.
00269 * Usage example:
00270 * @code
00271 * COH_THROW_STREAM(IOException, "File: " << hsFile << " not found.");
00272 * @endcode
00273 * @see COH_THROW
00274 */
00275 #define COH_THROW_STREAM(E, CONTENTS) \
00276     COH_THROW (E::create(String::View(COH_TO_STRING(CONTENTS))));
00277 
00278 // ----- free functions -----------------------------------------------------
00279 
00280 /**
00281 * This helper method is used by COH_THROW to raise the exception, supplying
00282 * the stack at which it was called.  If the exception is referenced via a
00283 * handle the exception's stack will be set prior to being throw.  The function
00284 * is marked with compiler specific (no return) statements, so that any calls
00285 * to it will suppress the corresponding compiler warnings.
00286 *
00287 * @param ohE         the instance of an exception object to throw
00288 * @param vsFile      the current file
00289 * @param nLine       the current line
00290 * @param vsFunction  the current function
00291 */
00292 COH_EXPORT COH_NO_RETURN_PRE void coh_throw(Exception::Holder ohE,
00293         String::View vsFile, int32_t nLine, String::View vsFunction)
00294             COH_NO_RETURN_POST;
00295 
00296 COH_CLOSE_NAMESPACE2
00297 
00298 #endif // COH_EXCEPTION_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.