dtl

Exceptions in the Database Template Library: An Overview

The Database Template Library (DTL) attempts to be robust in the services it provides. To be robust, a piece of software must maintain uncorrputed data structures and recover to resume normal execution if possible in the face of errors. Errors must be reported in a clear manner and allow the user to track down exactly what went wrong in the running of the program. In addition, the user should have some control over what kind of behavior will take place if an error is encountered. DTL addresses these issues by providing:

Code written in an exception-safe manner to where atomicity and consistency are maintained wherever possible.
A clear and easy to understand exception hierarchy which describes the various kinds of problems that can occur during execution. This allows for easier debugging as you know exactly what code threw and get a clear idea of the problem. Exception classes in DTL inherit from a base called RootException and describe specific common cases in DTL:
DBException: describes problems that occur either at the API level or the ODBC/database level dealing with reading or writing to the database, either in IndexedDBView, DBView, or DBStmts (or their iterators).

ETIException: gives an error message about what went wrong with the extended type information provided for SQL <---> C type mappings, usually unrecognized types.

ValidityException: describes errors thrown from ValidatedObject's (specifically for DBConnection and DBStmt objects), indicating the object has hit an invalid state and cannot be recovered without a call to the virtual method ValidatedObject::revalidate().

VariantException: thrown for errors that occur with variant objects such as variant_row, variant_fields, and IOHandlers (handlers are implemented as variant objects). If we can't find a member such as a function name or cast properly, then we throw this exception.
All DTL iterator classes (DB_iterator and its subclasses) support a notion of handlers. Each iterator maintains its own state based on the operations it performs similar to the C++ standard library's iostreams. They have good(), bad(), and fail() methods plus the other methods which are defined in std::ios_base. DTL's notion of handlers is similar to C++'s concept of new_handler that is invoked when the memory manager fails to allocate memory on operator new(). DTL has handlers known as IOHandlers, which are function objects that the user can set using DB_iterator::set_io_handler() and will be invoked when an exception is thrown by code executed by that iterator. The handler decides what actions to take based on the state of the iterator and tells the caller whether to suppress the error or to re-throw the exception. DTL also provides two pre-defined handlers for common cases: AlwaysThrowsHandler (which always just tells the code to re-throw and does nothing else) and LoggingHandler (which logs exceptions to a vector with useful information that can aid the user in tracking down the problem, always telling the caller to ignore the error). IOHandlers give the user more control over what they want to do with exceptions.
The notion of transactions over a range. In other words, the ability to insert or update multiple rows and roll the entire operation back if it is not completely successful. This is a must for both exception safety purposes and to provide proper support for the notion of database transactions.

More information and examples on the above items can be found in the "Exception Safety in DTL" document.

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.