The Simons     Component Library

           

---

Exception Class Reference

#include <Exception.h>

Inheritance diagram for Exception:

List of all members.

---

Detailed Description

Exception: the superclass of all exceptions.

Whenever a runtime failure is detected, programs will create an instance of Exception (or of one of its more specfic subclasses) and raise this using throw(). By default, raising an Exception will terminate the program with an Abort signal. However, programs may choose to handle Exceptions using catch() to trap specific kinds of Exception. A fault-tolerant program should be placed inside a try{...} block, followed by one or more catch(ExceptionID ex){...} blocks, in which the specific type of the ExceptionID variable determines which class of Exceptions will be caught by that handler. Exception provides access to the failed object() and the error message() and will report() this message on the standard error stream, giving a backtrace if several Exceptions were chained together. This may be desired when a caught Exception must necessarily throw another one inside the catch() handler.

   	try{
   		VectorID vec = new Vector;
   		ObjectID obj = vec->first();
   	}
   	catch (NoElementsID ex) {
   		ex->report();
   	}
   	catch (NullPointerID ex) {
   		ex->report();
   	}
    

The above example raises a NoElements exception, which is caught by the first catch() handler. The second handler is there to catch a NullPointer exception (but none is raised). This allows different types of Exception to be handled specially, or not at all. Handlers will catch Exceptions of their own type, or of more specific types. Catching a most general ExceptionID at the top level is the normal way to report system failure.

Public Member Functions
	Exception ()
	Construct a default Exception.
virtual	~Exception ()
	Release an unused Exception.
	Exception (ObjectID, StringID)
	Construct an Exception reporting failure in an Object.
virtual ObjectID	clone () const
	Clone a copy of this Exception.
ObjectID	object () const
	Access the failed Object.
StringID	message () const
	Access the error message String.
Void	causedBy (ExceptionID)
	Establish the cause of this Exception.
ExceptionID	cause () const
	Access the cause of this Exception.
Void	report () const
	Report an Exception on the standard error stream.
Void	reportOn (OutputID) const
	Report an Exception on an existing Output stream.
Protected Member Functions
	Exception (const Exception &)
	Copy another Exception.
Protected Attributes
ObjectID	failedObject
	The Object which failed.
StringID	errorMessage
	An error message String.
ExceptionID	priorException
	An Exception that caused this one.

---

Constructor & Destructor Documentation

Exception::Exception (  const Exception &  exception  )  [protected]

Copy another Exception. Required by C++ to ensure that copying an Exception faithfully copies the parent Object. Creates a shallow copy of the argument Exception, which shares its failed object, error message and any prior Exception with this Exception. Parameters: exception  - the Exception to copy. Returns: an Exception, a shallow copy.

Exception::Exception (   )

Construct a default Exception. Initialises the failedObject to null; and the errorMessage to "Default exception". Returns: a default Exception.

Exception::~Exception (   )  [virtual]

Release an unused Exception.

Exception::Exception (  ObjectID  object, StringID  message )

Construct an Exception reporting failure in an Object. Parameters: object  - the Object in which a failure occurred. message  - an error message String.

---

Member Function Documentation

ExceptionID Exception::cause (   )  const [inline]

Access the cause of this Exception. Returns: a prior Exception that caused this one.

Void Exception::causedBy (  ExceptionID  cause  )

Establish the cause of this Exception. If this Exception is raised inside the catch {} block handling a prior Exception, set the prior Exception as the cause of this one. Doing this will allow report() to print an informative backtrace of chained Exceptions. Parameters: cause  - the Exception which caused this Exception.

ObjectID Exception::clone (   )  const [virtual]

Clone a copy of this Exception. Returns: a shallow copy of this Exception. Reimplemented from Object. Reimplemented in DeviceBusy, NoElements, NoResponse, NotFound, NullPointer, OutOfRange, ReadFailure, TypeFailure, Undefined, and WriteFailure.

StringID Exception::message (   )  const [inline]

Access the error message String. Returns: an error message String.

ObjectID Exception::object (   )  const [inline]

Access the failed Object. Returns: an Object.

Void Exception::report (   )  const

Report an Exception on the standard error stream. The default way to report an Exception. Prints a message "ERROR :" followed by the name of the type of the failed object and the text of the error message. If the failed object is null, this indicates a failure in the top-level System. If this Exception was caused by a prior Exception, prints a complete backtrace of the chain of Exceptions on the standard error stream.

Void Exception::reportOn (  OutputID  errorLog  )  const

Report an Exception on an existing Output stream. The normal way for a CGI program to report an Exception on the standard output stream, which must have been opened. Also used to print the complete backtrace of a chain of nested Exceptions. Prints a message "ERROR :" followed by the name of the type of the failed object and the text of the error message. If this Exception was caused by a prior Exception, prints the message: "Caused by " and then calls this method recursively to report the prior Exception. Parameters: errorLog  - the stream opened for reporting the Exception.

---

Member Data Documentation

StringID Exception::errorMessage [protected]

An error message String.

ObjectID Exception::failedObject [protected]

The Object which failed.

ExceptionID Exception::priorException [protected]

An Exception that caused this one.

---

The documentation for this class was generated from the following files:

• Exception.h
• Exception.cc

---