Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

Exception Class Reference

#include <coherence/lang/Exception.hpp>

Inherits Object.

Inherited by IOException, ClassNotFoundException, CloneNotSupportedException, InterruptedException, and RuntimeException.

List of all members.


Detailed Description

Base class for all exceptions used in Coherence.

Exceptions are not thrown directly, but rather via the COH_THROW macro. The macro will record the stack trace and throw the managed Exception such that it may be caught either via its View type, or as a std::exception derivative. Unlike standard C++ exceptions, managed exceptions may be caught by value, i.e. not using a const& and still be safely re-thrown (via the COH_THROW macro) without risking object slicing. This allows caught exceptions to be stored as data member or local variables outside of a try/catch block and to be safely re-thrown at a later time.

New exception classes are declared using the throwable_spec<> helper template.

 try
   {
   ...
   COH_THROW (IOException::create("some error"));
   ...
   }
 catch (IOException::View vIoe)
   {
   std::cerr << vIoe << std::endl;
   ...
   }
 catch (Exception::View vEx)
   {
   std::cerr << vEx << std::endl;
   ...
   COH_THROW (vEx); // re-throw managed exception
   }
 catch (const std::exception& e)
   {
   std::cerr << e.what() << std::endl;
   throw; // re-throw standard exception
   }

See also:
throwable
Author:
mf 2007.05.05

Public Types

typedef spec::Handle Handle
 Exception Handle definition.
typedef spec::View View
 Exception View definition.
typedef spec::Holder Holder
 Exception Holder definition.

Public Member Functions

virtual String::View getName () const
 Return the name of the exception.
virtual String::View getDescription () const
 Returns a human-readable description of the Exception.
virtual void setMessage (String::View vsMsg)
 Set the message associated with this exception.
virtual String::View getMessage () const
 Return the message associated with this exception.
virtual Exception::View getCause () const
 Return the underlying cause associated with this exception.
virtual void setThreadName (String::View vsThreadName)
 Set the name of the thread on which this exception was thrown.
virtual String::View getThreadName () const
 Return the name of the thread on which the exception was thrown.
virtual void setStackTrace (ObjectArray::View vaFrames)
 Set point at which the exception occurred.
virtual ObjectArray::View getStackTrace () const
 Return the stack trace for the exception.
virtual Exception::Handle fillInStackTrace (String::View vsFile=String::null_string, int32_t nLine=0, String::View vsFunction=String::null_string)
 Fills the execution stack trace based on the current threads stack and the supplied information about the current stack frame.
virtual void printStackTrace (std::ostream &out=std::cerr) const
 Print the stack trace to the supplied stream.
virtual void raise () const
 (Re)throw the exception.
virtual void toStream (std::ostream &out) const
 Output a human-readable description of this Object to the given stream.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.

 Object::View vKey   = ...
 Object::View vValue = ...
 std::cout << vKey << " = " << vValue << std::endl;

 String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);

Parameters:
out the stream used to output the description


Protected Member Functions

 Exception (String::View vsMsg=String::null_string, Exception::View veCause=NULL)
 Create a new Exception object.

Protected Attributes

MemberView< Stringm_vsMessage
 The message associated with this exception.
MemberView< ObjectArraym_vaStackFrames
 The stack at the point the exception was thrown.
MemberView< Stringm_vsThreadName
 The name of the thread on which the Exception was thrown;.
MemberView< Exceptionm_veCause
 The cause of the exception.
MemberView< Stringm_vsDescription
 The detailed human readable description of this exception.

Constructor & Destructor Documentation

Exception ( String::View  vsMsg = String::null_string,
Exception::View  veCause = NULL 
) [protected]

Create a new Exception object.

Parameters:
vsMsg the message of the exception
veCause the underlying cause of the exception; can be NULL
Returns:
a Handle to the created Exception


Member Function Documentation

virtual String::View getDescription (  )  const [virtual]

Returns a human-readable description of the Exception.

Note: The String returned is held for the lifetime of this exception to guarantee that the result does not go out of scope. This method is used by Exception Handles to support the std::exception::what() method.

Returns:
the Exception's description

virtual void setMessage ( String::View  vsMsg  )  [virtual]

Set the message associated with this exception.

Parameters:
vsMsg the message to set for this exception

virtual String::View getMessage (  )  const [virtual]

Return the message associated with this exception.

Returns:
the message associated with this exception

virtual Exception::View getCause (  )  const [virtual]

Return the underlying cause associated with this exception.

The underlying cause is the exception that caused this exception to be thrown.

Returns:
the underlying cause associated with this exception; might be NULL

virtual void setThreadName ( String::View  vsThreadName  )  [virtual]

Set the name of the thread on which this exception was thrown.

Parameters:
vsThreadName the thread name

virtual String::View getThreadName (  )  const [virtual]

Return the name of the thread on which the exception was thrown.

Returns:
the name of the thread on which the exception was thrown.

virtual void setStackTrace ( ObjectArray::View  vaFrames  )  [virtual]

Set point at which the exception occurred.

Parameters:
vaFrames an array of StackTraceElements

virtual ObjectArray::View getStackTrace (  )  const [virtual]

Return the stack trace for the exception.

Returns:
an array of StackTraceElements.

Reimplemented in PortableException.

virtual Exception::Handle fillInStackTrace ( String::View  vsFile = String::null_string,
int32_t  nLine = 0,
String::View  vsFunction = String::null_string 
) [virtual]

Fills the execution stack trace based on the current threads stack and the supplied information about the current stack frame.

Parameters:
vsFile the file portion of the first stack frame
nLine the lone portion of the first stack frame
vsFunction the function portion of the first stack frame

virtual void printStackTrace ( std::ostream &  out = std::cerr  )  const [virtual]

Print the stack trace to the supplied stream.

Parameters:
out the stream to print the trace to

virtual void raise (  )  const [virtual]

(Re)throw the exception.

The resulting thrown exception may be caught either by it's View type, or its alias type.


The documentation for this class was generated from the following file:
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.