TerraLib Common Runtime → Exception

The class Exception is designed to declare objects to be thrown by TerraLib when something goes wrong.

What is an Exception?

It can be an error during a processing function: like out-of-memory, wrong path, wrong calculus;
It can be triggered by a missed value or pointer;
It can be triggered by a parameter out of range.

TerraLib Exception class is a subclass of std::exception. All TerraLib exception classes are subclasses of te::common::Exception. For instance: te::gm::Exception, te::rst::Exception and te::dt::Exception are subclasses of te::common::Exception.

Design

The Exception class diagrama is showned below:

The LoggedException is a specialized class that makes automatic logging of the exception message. You must assure that a LoggedException is never thrown in an statically initialized code because the logger may not be ready for logging.

The CompoundException allows one to concatenate several exceptions.

Please, consult the module documentation guide to know if you can wait for more specific exceptions for a given module.

Extensibility

Each TerraLib module can have its own subclass of Exception. There is a pair of macros that can be used to introduce new exception classes: TE_DECLARE_EXCEPTION_CLASS and TE_DEFINE_EXCEPTION_CLASS.

From Theory to Practice

The TE_DECLARE_EXCEPTION_CLASS can be used to create a .h file with the new exception class declaration.

// TerraLib
#include "../common/Exception.h"
#include "Config.h"
 
 
namespace te
{
  namespace dt
  {
    TE_DECLARE_EXCEPTION_CLASS(TEDATATYPEEXPORT, Exception, te::common::Exception)
 
  } // end namespace dt
}   // end namespace te

The TE_DEFINE_EXCEPTION_CLASS can be used to create the excpetion class implemention in a source file (.cpp).

// TerraLib
#include "Exception.h"
 
namespace te
{
  namespace dt
  {
    TE_DEFINE_EXCEPTION_CLASS(Exception, te::common::Exception, "te::dt::Exception")
 
  } // end namespace dt
}   // end namespace te