Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

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

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.