Chapter 18. The java.sql Package

Array	Java 1.2
java.sql

Provides an interface to SQL ARRAY objects. Each getArray() method returns a standard Java array of objects of the type returned by getBaseType(). Two getArray() methods support a java.util.Map parameter that can customize the SQL-type-to-Java-object mapping. The contents of the array can also be returned as a ResultSet using the various getResultSet() methods.

Passed To: PreparedStatement.setArray(), SQLOutput.writeArray(), javax.sql.RowSet.setArray()

Returned By: CallableStatement.getArray(), ResultSet.getArray(), SQLInput.readArray()

BatchUpdateException	Java 1.2
java.sql	serializable checked

This exception, which is a subclass of SQLException, is thrown when a batch update operation fails. The exception includes a method, getUpdateCounts(), that returns an array of int values, where the values correspond to the update counts for the successful update operations in the batch.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->SQLException-->BatchUpdateException

Blob	Java 1.2
java.sql

The Blob interface encapsulates a SQL BLOB field. The interface actually contains a pointer to the BLOB within the database, rather than the complete (and potentially very large) object. Data can be retrieved via a java.io.InputStream returned by getInputStream() or as an array of bytes returned by getBytes(). The length() method returns the number of bytes in the BLOB. The position() methods scan the contents of the Blob for a particular content sequence, represented by either another Blob object or a byte array. (The position() methods do not provide the current read-index within the BLOB).

Passed To: Blob.position(), PreparedStatement.setBlob(), SQLOutput.writeBlob(), javax.sql.RowSet.setBlob()

Returned By: CallableStatement.getBlob(), ResultSet.getBlob(), SQLInput.readBlob()

CallableStatement	Java 1.1
java.sql	PJ1.1(opt)

The CallableStatement interface allows programs to access SQL stored procedures within the database. You create a CallableStatement with the prepareCall() method of Connection. Question-mark characters (?) are used as placeholders for input and output values in the syntax that calls stored procedures:

{? = call procedure_name[(?[,?...])]}
{call procedure_name[(?[,?...])]}

Parameters are numbered sequentially starting from 1. Input parameters are set with the same setXXX() methods as in a PreparedStatement. Output parameters must be registered using the registerOutParameter() methods, and may be retrieved after the statement executes using the getXXX() methods, which are identical to those in ResultSet. To execute a statement, you call execute(), which is inherited from PreparedStatement.

Hierarchy: (CallableStatement(PreparedStatement(Statement)))

Returned By: java.sql.Connection.prepareCall()

Clob	Java 1.2
java.sql

The Clob interface encapsulates a SQL CLOB field. The interface actually contains a pointer to the CLOB within the database, rather than the complete character string. Data is retrieved via getAsciiStream(), which returns an InputStream, or via getCharacterStream(), which returns a Reader. The getSubString() method returns a specific substring within the CLOB, while the position() methods search the CLOB for a pattern and return the index of the pattern's first appearance.

Passed To: Clob.position(), PreparedStatement.setClob(), SQLOutput.writeClob(), javax.sql.RowSet.setClob()

Returned By: CallableStatement.getClob(), ResultSet.getClob(), SQLInput.readClob()

Connection	Java 1.1
java.sql	PJ1.1(opt)

The Connection interface represents an individual database connection. The object includes factory methods for Statement, PreparedStatement, and CallableStatement objects and a number of transaction control methods (setAutoCommit(), commit(), rollback(), getAutoCommit(), setTransactionIsolation(), and getTransactionIsolation()). Other methods provide information about the database. The most important of these is getMetaData(), which returns a DatabaseMetaData object. The getWarnings() method returns any warnings pending for this connection.

Connection objects are created with the static DriverManager.getConnection() method.

Returned By: DatabaseMetaData.getConnection(), Driver.connect(), DriverManager.getConnection(), Statement.getConnection(), javax.sql.DataSource.getConnection(), javax.sql.PooledConnection.getConnection(), javax.sql.RowSetInternal.getConnection()

DatabaseMetaData	Java 1.1
java.sql	PJ1.1(opt)

The getMetaData() method of the Connection interface returns a DatabaseMetaData object that encapsulates nonconnection-dependent information about the underlying database. A number of methods return ResultSet objects that should be treated like any other ResultSet.

DatabaseMetaData methods that accept String parameters with names ending in "Pattern" allow for simple wildcard searching. These methods treat the % character as matching any number of characters and the _ character as matching any single character. If these parameters are set to null, pattern matching is not performed.

Returned By: java.sql.Connection.getMetaData()

DataTruncation	Java 1.1
java.sql	serializable checked PJ1.1(opt)

This subclass of SQLWarning is a special warning used when JDBC unexpectedly truncates a data value. It is chained as a warning on read operations and thrown as an exception on write operations.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->SQLException-->SQLWarning-->DataTruncation

Date	Java 1.1
java.sql	cloneable serializable comparable PJ1.1(opt)

A wrapper around the java.util.Date class that adjusts the time value (milliseconds since January 1, 1970 0:00:00 GMT) to conform to the SQL DATE specification. The DATE type only deals with the day, month, and year, so the hours, minutes, seconds, and milliseconds are set to 00:00:00.00 in the current time zone. The Date class also includes a static valueOf() method that decodes the JDBC Date escape syntax yyyy-mm-dd into a Date value.

Hierarchy: Object-->java.util.Date(Serializable,Cloneable,Comparable)-->java.sql.Date

Passed To: PreparedStatement.setDate(), ResultSet.updateDate(), SQLOutput.writeDate(), javax.sql.RowSet.setDate()

Returned By: CallableStatement.getDate(), java.sql.Date.valueOf(), ResultSet.getDate(), SQLInput.readDate()

Driver	Java 1.1
java.sql	PJ1.1(opt)

Every JDBC driver must implement the Driver interface. Most programmers never need to deal with this interface, except when using the DriverManager.registerDriver() method, which is generally not recommended. The better way to register a driver is to load the driver by calling Class.forName() on the driver class, which automatically registers the driver as well.

Passed To: DriverManager.{deregisterDriver(), registerDriver()}

Returned By: DriverManager.getDriver()

DriverManager	Java 1.1
java.sql	PJ1.1(opt)

The DriverManager class is responsible for loading JDBC drivers and creating Connection objects. It starts by loading all the drivers specified in the jdbc.drivers system property. Individual drivers can also be loaded by calling Class.forName() with the driver class name.

Programs use the static DriverManager.getConnection() method to create individual database connections. The driver manager creates the Connection using the appropriate driver, based on the JDBC URL specified in the call to getConnection().

DriverPropertyInfo	Java 1.1
java.sql	PJ1.1(opt)

The DriverPropertyInfo class contains the properties required to create a new database connection using a particular driver. It is returned by the getDriverProperties() method of Driver. This class is useful only for programmers who need to interact directly with the driver in a dynamic manner.

Returned By: Driver.getPropertyInfo()

PreparedStatement	Java 1.1
java.sql	PJ1.1(opt)

The PreparedStatement interface allows programs to precompile SQL statements for increased performance. You obtain a PreparedStatement object with the prepareStatement() method of Connection. Parameters in the statement are denoted by ? characters in the SQL string and indexed from 1 to n. Individual parameter values are set using the setXXX() methods, while the clearParameters() method clears all the parameters. Note that some JDBC drivers do not implement setObject() properly when dealing with null field types. Once all parameters have been set, the statement is executed using execute(), executeQuery(), or executeUpdate(). Unlike with the Statement object, the execution methods take no parameters.

Hierarchy: (PreparedStatement(Statement))

Implementations: CallableStatement

Returned By: java.sql.Connection.prepareStatement()

Ref	Java 1.2
java.sql

The Ref interface provides a pointer to a structured data type within the database. The getBaseType() method returns the name of the underlying type.

Passed To: PreparedStatement.setRef(), SQLOutput.writeRef(), javax.sql.RowSet.setRef()

Returned By: CallableStatement.getRef(), ResultSet.getRef(), SQLInput.readRef()

ResultSet	Java 1.1
java.sql	PJ1.1(opt)

The ResultSet interface represents a database result set, allowing programs to access the data in the result set. ResultSet objects are usually generated by the execute(), executeUpdate(), and executeQuery() methods of Statement and PreparedStatement. They are also returned by certain metadata methods.

The JDBC 1.0 ResultSet allows you to scroll navigate through the data once from beginning to end, iterating through rows using the next() method and retrieving individual fields using the getXXX() methods. The getMetaData() method returns a ResultSetMetaData object that describes the structure of the underlying data.

JDBC 2.0 introduces a number of new features: complete scrolling capabilities (the previous(), first(), last(), and related methods), direct updating of data via the updateXXX() methods, and insertion of new data rows using the insertRow() method. Since there are relatively few JDBC 2.0-compliant drivers (currently available as of this book's print date), you may want to avoid the JDBC 2.0 methods for the time being.

Implementations: javax.sql.RowSet

Returned By: Too many methods to list.

ResultSetMetaData	Java 1.1
java.sql	PJ1.1(opt)

This interface provides metainformation about the data underlying a particular ResultSet. In particular, you can get information about the columns of the ResultSet with getColumnCount(), getColumnLabel(), and getColumnTypeName().

Implementations: javax.sql.RowSetMetaData

Returned By: PreparedStatement.getMetaData(), ResultSet.getMetaData()

SQLData	Java 1.2
java.sql

Allows custom mapping of user-defined SQL types. This interface is generally implemented by a development tool or driver vendor and is never called by the programmer directly.

Passed To: SQLOutput.writeObject()

SQLException	Java 1.1
java.sql	serializable checked PJ1.1(opt)

A SQLException object is thrown by any JDBC method that encounters an error. SQLException extends the java.lang.Exception class and adds a vendor-specific error code and an XOPEN SQL state code. SQLException objects can be chained together. The next exception in the chain is retrieved via getNextException(), which returns null if there are no more exceptions available. The setNextException() method adds an exception to the end of the chain.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->SQLException

Subclasses: BatchUpdateException, SQLWarning

Passed To: SQLException.setNextException(), javax.sql.ConnectionEvent.ConnectionEvent()

Returned By: SQLException.getNextException(), javax.sql.ConnectionEvent.getSQLException()

Thrown By: Too many methods to list.

SQLInput	Java 1.2
java.sql

Represents an input stream for a user-defined SQL type. SQLInput is used by the driver and is never called by the programmer directly.

Passed To: SQLData.readSQL()

SQLOutput	Java 1.2
java.sql

Represents an output stream for a user-defined SQL type. SQLOutput is used by the driver and is never called by the programmer directly.

Passed To: SQLData.writeSQL()

SQLWarning	Java 1.1
java.sql	serializable checked PJ1.1(opt)

Represents a nonfatal warning condition. Warnings are silently chained to the object whose method produced them. You can retrieve warnings with the getWarnings() method implemented by most JDBC classes.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->SQLException-->SQLWarning

Subclasses: DataTruncation

Passed To: SQLWarning.setNextWarning()

Returned By: java.sql.Connection.getWarnings(), ResultSet.getWarnings(), SQLWarning.getNextWarning(), Statement.getWarnings()

Statement	Java 1.1
java.sql	PJ1.1(opt)

The Statement interface executes SQL statements. Statement objects are returned by the createStatement() method of Connection. The execute(), executeUpdate(), and executeQuery() methods each take a Stringparameter that contains a SQL statement. execute() returns a boolean value that indicates whether a ResultSet is available. The ResultSet can then be retrieved with getResultSet(). executeUpdate() returns an update count and is used for INSERT, UPDATE, DELETE, and other data manipulation statements. executeQuery() is used for SELECTstatements, so it returns a ResultSet. There can be only one ResultSet active per query; the current ResultSet is closed when a new SQL statement of any kind is executed.

Implementations: PreparedStatement

Returned By: java.sql.Connection.createStatement(), ResultSet.getStatement()

Struct	Java 1.2
java.sql

The Struct interface provides a mapping for an SQL structured type. The getAttributes() method returns an array of objects representing each attribute in the structured type. Custom type maps can be specified by including a java.util.Map attribute.

Passed To: SQLOutput.writeStruct()

Time	Java 1.1
java.sql	cloneable serializable comparable PJ1.1(opt)

A wrapper around the java.util.Date class that adjusts the time value (milliseconds since January 1, 1970 0:00:00 GMT) to conform to the SQL TIME specification. The TIME type only deals with the time of day, so the date components are set to January 1, 1970 and should not be altered. The Time class also includes a static valueOf() method that decodes the JDBC Time escape syntax hh:mm:ss into a Time value.

Hierarchy: Object-->java.util.Date(Serializable,Cloneable,Comparable)-->Time

Passed To: PreparedStatement.setTime(), ResultSet.updateTime(), SQLOutput.writeTime(), javax.sql.RowSet.setTime()

Returned By: CallableStatement.getTime(), ResultSet.getTime(), SQLInput.readTime(), Time.valueOf()

Timestamp	Java 1.1
java.sql	cloneable serializable comparable PJ1.1(opt)

Extends the java.util.Date class to function as an SQL TIMESTAMP value by adding a nanoseconds component. The getTime() method returns the time in milliseconds since January 1, 1970 00:00:00 GMT to the latest integral second. To include fractional seconds, divide the value returned by getNanos() by 1 million and add this to the result returned by getTime(). This allows accurate comparisons with java.util.Date objects. The valueOf() method parses a String in the format yyyy-mm-ddhh:mm:ss.fffffffff into a Timestamp.

Hierarchy: Object-->java.util.Date(Serializable,Cloneable,Comparable)-->Timestamp

Passed To: PreparedStatement.setTimestamp(), ResultSet.updateTimestamp(), SQLOutput.writeTimestamp(), Timestamp.{after(), before(), equals()}, javax.sql.RowSet.setTimestamp()

Returned By: CallableStatement.getTimestamp(), ResultSet.getTimestamp(), SQLInput.readTimestamp(), Timestamp.valueOf()

Types	Java 1.1
java.sql	PJ1.1(opt)

The Types class defines a set of integer constants that represent SQL data types. The type names and constant values are the ones specified in the XOPEN specification.