dtl


RootException

Category: exceptions Component type: type

Description

RootException is the base class of all exceptions in the DTL. An exception of this type stores strings representing which method the exception was thrown in, a message describing what error occurred, and what actual exception type was thrown. The call to the constructor initializes these strings. The user can extract a stringified message with all of this information from the exception using the standard what() method. Subclasses may also pass in a stringified representation of their type name as the third argument to the constructor (see below).

Definition

Defined in the RootException.h header file.

Example: Trivial case of throwing and catching a RootException

void IWillThrow()
{
   vector<int> v(5); // create a vector of 5 elements
   try
   {
   for (int i = 0; i <= 5; i++){
      v.at(i) = i; // v.at(5) will throw std::invalid_argument exception
   }
   catch (invalid_argument &ex)
   {
      // for a method SomeClass::foo(), method string would be "SomeClass:foo()"
      // for a global function as used here, just use its name
      throw RootException("IWillThrow()", ex.what());
   }
};

int main()
{
   try
   {
       // call our method which throws
       IWillThrow();
   }
   catch (RootException &ex)
   {
       // can also say: cout << ex << endl;
       // operator<<() for RootExceptions just streams out what()
       cout << ex.what() << endl;
   }
   return 0; // won't reach here ... exception thrown above
}

Model of

Standard C++ library exception.

Public base classes

std::exception

Members

Member Where defined Description
RootException() RootException Default constructor. Sets method and message fields to empty strings and exception type string to "RootException".
RootException(const string &meth, const string &err, const string &excType = "RootException") RootException Constructor which takes a specific method, error string, and stringified exception type to initialize itself.
virtual const char* what() const throw() RootException Overrides behavior in std::exception. Returns a C string describing the exception, including the method it was thrown in, the error message describing why it was thrown, and what type of exception was thrown. Subclasses do and may override what() based on their needs. See Note [1].
virtual const TCHAR* twhat() const throw() RootException Returns a pointer to a TCHAR describing the exception, including the method it was thrown in, the error message describing why it was thrown, and what type of exception was thrown. Subclasses do and may override twhat() based on their needs. See Note [1]. This is useful for returning unicode error messages. See Unicode documentation.
friend wostream &operator<<(wostream &o, const RootException &ex) RootException Note that this is a friend function, and not a member. Streams out ex.twhat() to o. As twhat() is virtual, the appropriate version of that method will be called for ex.
friend ostream &operator<<(ostream &o, const RootException &ex) RootException Note that this is a friend function, and not a member. Streams out ex.what() to o. As what() is virtual, the appropriate version of that method will be called for ex.

Notes

[1] A RootException contains a protected string member named whatbuf. This seemingly extra member is needed as the std::exception does not contain a portable, mutable way to access its own member that is used to hold the error message. This effects the implementation of the what() method as the exception needs a way to build its own error string, possibly partly based on what the superclass exception does in its work. An example of how to implement what() for a subclass of RootException can be found in the DBException class:

// DBException::what() ... DBException derives from RootException
virtual const char *what() const throw()
{
   string rootWhat = RootException::what(); // let RootException build up the common part of the error string
   ostringstream o;
   o << rootWhat;

   // stream out ODBC errors to the what() string
   if (sqlErrors.size() > 0)
   {
      o << "SQL Errors: " << endl;

      for (size_t i = 0; i < sqlErrors.size(); i++)
      {
         o << "(" << i << ") " << sqlErrors[i] << endl;
      }

   }

   // this gymnastics is needed so result isn't destroyed
   // paste these two lines into all what() code
   whatbuf = o.str();
   return whatbuf.c_str();
}

See also

DBException, ETIException, ValidityException, VariantException.


[DTL Home]

Copyright © 2002, Michael Gradman and Corwin Joy.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Corwin Joy and Michael Gradman make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

This site written using the ORB. [The ORB]

1