The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
This page covers the following topics:
When JDBC encounters an error during an interaction with a data source, it throws an instance of SQLException
as opposed to Exception
. (A data source in this context represents the database to which a Connection
object is connected.) The SQLException
instance contains the following information that can help you determine the cause of the error:
A description of the error. Retrieve the String
object that contains this description by calling the method SQLException.getMessage
.
A SQLState code. These codes and their respective meanings have been standardized by ISO/ANSI and Open Group (X/Open), although some codes have been reserved for database vendors to define for themselves. This String
object consists of five alphanumeric characters. Retrieve this code by calling the method SQLException.getSQLState
.
An error code. This is an integer value identifying the error that caused the SQLException
instance to be thrown. Its value and meaning are implementation-specific and might be the actual error code returned by the underlying data source. Retrieve the error by calling the method SQLException.getErrorCode
.
A cause. A SQLException
instance might have a causal relationship, which consists of one or more Throwable
objects that caused the SQLException
instance to be thrown. To navigate this chain of causes, recursively call the method SQLException.getCause
until a null
value is returned.
A reference to any chained exceptions. If more than one error occurs, the exceptions are referenced through this chain. Retrieve these exceptions by calling the method SQLException.getNextException
on the exception that was thrown.
The following method,
JDBCTutorialUtilities.printSQLException
, outputs the SQLState, error code, error description, and cause (if there is one) contained in the SQLException
as well as any other exception chained to it:
public static void printSQLException(SQLException ex) { for (Throwable e : ex) { if (e instanceof SQLException) { if (ignoreSQLException( ((SQLException)e). getSQLState()) == false) { e.printStackTrace(System.err); System.err.println("SQLState: " + ((SQLException)e).getSQLState()); System.err.println("Error Code: " + ((SQLException)e).getErrorCode()); System.err.println("Message: " + e.getMessage()); Throwable t = ex.getCause(); while(t != null) { System.out.println("Cause: " + t); t = t.getCause(); } } } } }
For example, if you call the method CoffeesTable.dropTable
with Java DB as your DBMS, the table COFFEES
does not exist, and you remove the call to JDBCTutorialUtilities.ignoreSQLException
, the output will be similar to the following:
SQLState: 42Y55 Error Code: 30000 Message: 'DROP TABLE' cannot be performed on 'TESTDB.COFFEES' because it does not exist.
Instead of printing SQLException
information, you could instead first retrieve the SQLState
then process the SQLException
accordingly. For example, the method JDBCTutorialUtilities.ignoreSQLException
returns true
if the SQLState
is equal to code 42Y55
(and you are using Java DB as your DBMS), which causes JDBCTutorialUtilities.printSQLException
to ignore the SQLException
:
public static boolean ignoreSQLException(String sqlState) { if (sqlState == null) { System.out.println("The SQL state is not defined!"); return false; } // X0Y32: Jar file already exists in schema if (sqlState.equalsIgnoreCase("X0Y32")) return true; // 42Y55: Table already exists in schema if (sqlState.equalsIgnoreCase("42Y55")) return true; return false; }
SQLWarning
objects are a subclass of SQLException
that deal with database access warnings. Warnings do not stop the execution of an application, as exceptions do; they simply alert the user that something did not happen as planned. For example, a warning might let you know that a privilege you attempted to revoke was not revoked. Or a warning might tell you that an error occurred during a requested disconnection.
A warning can be reported on a Connection
object, a Statement
object (including PreparedStatement
and CallableStatement
objects), or a ResultSet
object. Each of these classes has a getWarnings
method, which you must invoke in order to see the first warning reported on the calling object. If getWarnings
returns a warning, you can call the SQLWarning
method getNextWarning
on it to get any additional warnings. Executing a statement automatically clears the warnings from a previous statement, so they do not build up. This means, however, that if you want to retrieve warnings reported on a statement, you must do so before you execute another statement.
The following methods from
JDBCTutorialUtilities.java
illustrate how to get complete information about any warnings reported on Statement
or ResultSet
objects:
public static void getWarningsFromResultSet(ResultSet rs) throws SQLException { JDBCTutorialUtilities.printWarnings(rs.getWarnings()); } public static void getWarningsFromStatement(Statement stmt) throws SQLException { JDBCTutorialUtilities.printWarnings(stmt.getWarnings()); } public static void printWarnings(SQLWarning warning) throws SQLException { if (warning != null) { System.out.println("\n---Warning---\n"); while (warning != null) { System.out.println("Message: " + warning.getMessage()); System.out.println("SQLState: " + warning.getSQLState()); System.out.print("Vendor error code: "); System.out.println(warning.getErrorCode()); System.out.println(""); warning = warning.getNextWarning(); } }
The most common warning is a DataTruncation
warning, a subclass of SQLWarning
. All DataTruncation
objects have a SQLState of 01004
, indicating that there was a problem with reading or writing data. DataTruncation
methods let you find out in which column or parameter data was truncated, whether the truncation was on a read or write operation, how many bytes should have been transferred, and how many bytes were actually transferred.
Your JDBC driver might throw a subclass of SQLException
that corresponds to a common SQLState or a common error state that is not associated with a specific SQLState class value. This enables you to write more portable error-handling code. These exceptions are subclasses of one of the following classes:
SQLNonTransientException
SQLTransientException
SQLRecoverableException
See the latest Javadoc of the java.sql
package or the documentation of your JDBC driver for more information about these subclasses.
The following subclasses of SQLException
can also be thrown:
BatchUpdateException
is thrown when an error occurs during a batch update operation. In addition to the information provided by SQLException
, BatchUpdateException
provides the update counts for all statements that were executed before the error occurred.SQLClientInfoException
is thrown when one or more client information properties could not be set on a Connection. In addition to the information provided by SQLException
, SQLClientInfoException
provides a list of client information properties that were not set.