Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# 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.