Handling Errors (Java Enterprise in a Nutshell)

2.7. Handling Errors

Any JDBC object that encounters an error serious enough to halt execution throws a SQLException. For example, database connection errors, malformed SQL statements, and insufficient database privileges all throw SQLException objects.

The SQLException class extends the normal java.lang.Exception class and defines an additional method called getNextException(). This allows JDBC classes to chain a series of SQLException objects together. SQLException also defines the getSQLState() and getErrorCode() methods to provide additional information about an error. The value returned by getSQLState() is one of the ANSI-92 SQL state codes; these codes are listed in Chapter 8, "SQL Reference". getErrorCode() returns a vendor-specific error code.

An extremely conscientious application might have a catch block that looks something like this:

try {
  // Actual database code
} 
catch (SQLException e) {
  while(e != null) { 
    System.out.println("\nSQL Exception:");
    System.out.println(e.getMessage());
    System.out.println("ANSI-92 SQL State: " + e.getSQLState());
    System.out.println("Vendor Error Code: " + e.getErrorCode());
    e = e.getNextException();
  } 
}

2.7.1. SQL Warnings

JDBC classes also have the option of generating (but not throwing) a SQLWarning exception when something is not quite right, but at the same time, not sufficiently serious to warrant halting the entire program. For example, attempting to set a transaction isolation mode that is not supported by the underlying database might generate a warning rather than an exception. Remember, exactly what qualifies as a warning condition varies by database.

SQLWarning encapsulates the same information as SQLException and is used in a similar fashion. However, unlike SQLException objects, which are caught in try/catch blocks, warnings are retrieved using the getWarnings() methods of the Connection, Statement, ResultSet, CallableStatement, and PreparedStatement interfaces. SQLWarning implements the getMessage(), getSQLState(), and getErrorCode() methods in the same manner as SQLException.

If you are debugging an application, and you want to be aware of every little thing that goes wrong within the database, you might use a printWarnings() method like this one:

void printWarnings(SQLWarning warn) {
  while (warn != null) {
    System.out.println("\nSQL Warning:");
    System.out.println(warn.getMessage());
    System.out.println("ANSI-92 SQL State: " + warn.getSQLState());
    System.out.println("Vendor Error Code: " + warn.getErrorCode());
    warn = warn.getNextWarning();
  }
}

Then you could use the printWarnings() method as follows:

// Database initialization code here
ResultSet rs = stmt.executeQuery("SELECT * FROM CUSTOMERS");
printWarnings(stmt.getWarnings());
printWarnings(rs.getWarnings());
// Rest of database code