Oracle Coherence for C++ API
Release 3.7.1.0
E22845-01

Exception Class Reference

#include <coherence/lang/Exception.hpp>

Inherits Object.

Inherited by IOException, ClassNotFoundException, CloneNotSupportedException, InterruptedException, NoSuchMethodException, 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< String > m_vsMessage

The message associated with this exception.

MemberView< ObjectArray > m_vaStackFrames

The stack at the point the exception was thrown.

MemberView< String > m_vsThreadName

The name of the thread on which the Exception was thrown;.

MemberView< Exception > m_veCause

The cause of the exception.

MemberView< String > m_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:

coherence/lang/Exception.hpp