The SQLException class and its subtypes provide information about errors and warnings that occur while a data source is being accessed.
Unlike most of JDBC, which is defined by interfaces, the exception support is provided in classes. The base class for exceptions that occur while running JDBC applications is SQLException. Every method of the JDBC API is declared as being able to throw SQLExceptions. SQLException is an extension of java.lang.Exception and provides additional information related to failures that happen in a database context. Specifically, the following information is available from an SQLException:
ExceptionExample is a program that properly handles catching an (expected in this case) SQLException and dumping all the information that it provides.
As noted, SQLException objects are thrown when errors occur. This is correct, but is not the complete picture. In practice, the native JDBC driver rarely throws actual SQLExceptions. It throws instances of its own SQLException subclasses. This allows you to determine more information about what has actually failed as is shown below.
DB2Exception objects are not thrown directly either. This base class is used to hold functionality that is common to all JDBC exceptions. There are two subclasses of this class that are be the standard exceptions that JDBC throws. These subclasses are DB2DBException.java and DB2JDBCException.java. DB2DBExceptions are exceptions that are reported to you that have come directly from the database. DB2JDBCExceptions are thrown when the JDBC driver finds problems on its own. Splitting the exception class hierarchy in this manner allows you to handle the two types of exceptions differently.
As stated, DB2DBExceptions are exceptions that come directly from the database. These are encountered when the JDBC driver make a call to the CLI and gets back an SQLERROR return code. The CLI function SQLError is called to get the message text, SQLState, and vendor code in these cases. The replacement text for the SQLMessage is also retrieved and returned to you. The DatabaseException class causes an error that the database recognizes and reports to the JDBC driver to build the exception object for.
DB2JDBCExceptions are generated for error conditions that come from the JDBC driver itself. The functionality of this exception class is fundamentally different; the JDBC driver itself handles message language translation of exception and other issues that the operating system and database handle for exceptions originating within the database. Wherever possible, the JDBC driver adheres to the SQLStates of the database. The vendor code for exceptions that the JDBC driver throws is always -99999. DB2DBExceptions that are recognized and returned by the CLI layer often also have the -99999 error code. The JDBCException class causes an error that the JDBC driver recognizes and builds the exception for itself. When run during development of the release, the following output was created. Notice that the top of the stack contains DB2JDBCException. This is an indication that the error is being reported from the JDBC driver prior to ever making the request to the database.