Java 2 Platform SE v1.3.1: Package java.sql

Interface Summary

Array The mapping in the Java programming language for the SQL type ARRAY.

Blob The representation (mapping) in the Java^TM programming language of an SQL BLOB value.

CallableStatement The interface used to execute SQL stored procedures.

Clob The mapping in the Java^TM programming language for the SQL CLOB type.

Connection A connection (session) with a specific database.

DatabaseMetaData Comprehensive information about the database as a whole.

Driver The interface that every driver class must implement.

PreparedStatement An object that represents a precompiled SQL statement.

Ref The mapping in the Java programming language of an SQL REF value, which is a reference to an SQL structured type value in the database.

ResultSet A table of data representing a database result set, which is usually generated by executing a statement that queries the database.

ResultSetMetaData An object that can be used to get information about the types and properties of the columns in a ResultSet object.

SQLData The interface used for the custom mapping of SQL user-defined types.

SQLInput An input stream that contains a stream of values representing an instance of an SQL structured or distinct type.

SQLOutput The output stream for writing the attributes of a user-defined type back to the database.

Statement The object used for executing a static SQL statement and obtaining the results produced by it.

Struct The standard mapping in the Java programming language for an SQL structured type.

Class Summary

Date A thin wrapper around a millisecond value that allows JDBC to identify this as a SQL DATE.

DriverManager The basic service for managing a set of JDBC drivers.
NOTE: The DataSource interface, new in the JDBC 2.0 API, provides another way to connect to a data source.

DriverPropertyInfo Driver properties for making a connection.

SQLPermission The permission for which the SecurityManager will check when code that is running in an applet calls one of the setLogWriter methods.

Time A thin wrapper around java.util.Date that allows JDBC to identify this as a SQL TIME value.

Timestamp A thin wrapper around java.util.Date that allows the JDBC API to identify this as an SQL TIMESTAMP value.

Types The class that defines the constants that are used to identify generic SQL types, called JDBC types.

Exception Summary

BatchUpdateException An exception thrown when an error occurs during a batch update operation.

DataTruncation An exception that reports a DataTruncation warning (on reads) or throws a DataTruncation exception (on writes) when JDBC unexpectedly truncates a data value.

SQLException An exception that provides information on a database access error or other errors.

SQLWarning An exception that provides information on database access warnings.

Package java.sql Description

Provides the API for accessing and processing data in a data source using the Java^TM programming language. This API includes a framework whereby different drivers can be installed dynamically to access different data sources.

The java.sql package, referred to as the JDBC 2.0 core API, had many new features added in the Java^TM 2 SDK, Standard Edition, version 1.2 release. New methods, fields, constructors, and exceptions in the JDBC 2.0 API are marked "Since 1.2" in the javadoc comments.

The class SQLPermission was added in the Java^TM 2 SDK, Standard Edition, version 1.3 release. This class is used to prevent unauthorized access to the logging stream associated with the DriverManager, which may contain information such as table names, column data, and so on.

What Is in the JDBC^TM 2.0 API

NOTE: Code that uses API marked "Since 1.2" must be run using a JDBC technology driver that implements the JDBC 2.0 core API. Check your driver documentation to be sure that it implements the particular features you want to use.

The JDBC^TM 2.0 API includes the complete JDBC API, which includes both core and Optional Package API, and provides industrial-strength database computing capabilities. It is not, however, limited to SQL databases; the JDBC2.0 API makes it possible to access data from virtually any data source with a tabular format.

The JDBC 2.0 API includes two packages:

java.sql package--the JDBC 2.0 core API
- JDBC API included in the JDK^TM 1.1 release (previously called JDBC 1.2). This API is compatible with any driver that uses JDBC technology.
- JDBC API included in the Java 2 SDK, Standard Edition, version 1.2 (called the JDBC 2.0 core API). This API includes the JDBC 1.2 API and adds many new features.
javax.sql package--the JDBC 2.0 Optional Package API. This package extends the functionality of the JDBC API from a client-side API to a server-side API, and it is an essential part of Java^TM 2 SDK, Enterprise Edition technology.
Being an Optional Package, it is not included in the Java 2 Platform SDK, Standard Edition, version 1.2, but it is readily available from various sources.
- Information about the JDBC 2.0 Optional Package API is available from the JDBC web page. The javax.sql package may also be downloaded from this web site.
- Driver vendors may include the javax.sql package with their products.
- The Java 2 SDK, Enterprise Edition, includes many Optional Package APIs, including the JDBC 2.0 Optional Package.

What the `java.sql` Package Contains

The java.sql package contains API for the following:

Making a connection with a data source
- DriverManager class
- Driver interface
- DriverPropertyInfo class
- Connection interface
Sending SQL statements to a database
- Statement interface for sending basic SQL statements
- PreparedStatement interface for sending prepared statements or basic SQL statements (derived from Statement)
- CallableStatement interface for calling database stored procedures (derived from PreparedStatement)
Retrieving and updating the results of a query
- ResultSet interface
Mapping an SQL value to the standard mapping in the Java programming language
- Array interface
- Blob interface
- Clob interface
- Date class
- Ref interface
- Struct interface
- Time class
- Timestamp class
- Types class
Custom mapping an SQL user-defined type to a class in the Java programming language
- SQLData interface
- SQLInput interface
- SQLOutput interface
Providing information about the database and the columns of a ResultSet object
- DatabaseMetaData interface
- ResultSetMetaData interface
Throwing exceptions
- SQLException thrown by most methods when there is a problem accessing data and by some methods for other reasons
- SQLWarning thrown to indicate a warning
- DataTruncation thrown to indicate that data may have been truncated
- BatchUpdateException thrown to indicate that not all commands in a batch update executed successfully
Providing security
- SQLPermission interface

New Features in the JDBC 2.0 Core API

Scrollable result sets--using new methods in the ResultSet interface that allow the cursor to be moved to a particular row or to a position relative to its current position
Batch updates
Programmatic updates--using ResultSet.updateXXX methods
New data types--interfaces mapping the SQL3 data types
Custom mapping of user-defined types (UDTs)
Miscellaneous features, including performance hints, the use of character streams, full precision for java.math.BigDecimal values, additional security, and support for time zones in date, time, and timestamp values.

Custom Mapping of UDTs

New features in the JDBC 2.0 core API make it possible to map a user-defined type (UDT) defined in SQL to a class in the Java programming language. An SQL structured type or an SQL DISTINCT type are the UDTs that may be custom mapped. The following three steps set up a custom mapping:

Defining the SQL structured type or DISTINCT type in SQL
Defining the class in the Java programming language to which the SQL UDT will be mapped. This class must implement the SQLData interface.
Making an entry in a Connection object's type map that contains two things:
- the fully-qualified SQL name of the UDT and the
- the Class object for the class to which the UDT is to be mapped

When these are in place for a UDT, calling the methods ResultSet.getObject or CallableStatement.getObject on that UDT will automatically retrieve the custom mapping for it.

Type Maps

A newly-created JDBC 2.0 Connection object has an initially-empty type map associated with it. A user may enter a custom mapping for a UDT in this type map. When a UDT is retrieved from a data source with the method ResultSet.getObject, the getObject method will check the connection's type map to see if there is an entry for that UDT. If so, the getObject method will map the UDT to the class indicated. If there is no entry, the UDT will be mapped using the standard mapping.

A user may create a new type map, which is a Map object, make an entry in it, and pass it to the java.sql methods that can perform custom mapping. In this case, the method will use the given type map instead of the one associated with the connection.

For example, the following code fragment specifies that the SQL type ATHLETES will be mapped to the class Athletes in the Java programming language. The code fragment retrieves the type map for the Connection object con, inserts the entry into it, and then sets the type map with the new entry as the connection's type map.

	java.util.Map map = con.getTypeMap();
	map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
	con.setTypeMap(map);

Classes Used for Custom Mapping

The class to which an SQL UDT is mapped in a custom mapping must implement the SQLData interface. Typically, this class will define a field for each attribute of an SQL structured type or a single field for an SQL DISTINCT type. When the UDT is retrieved from a data source with the ResultSet.getObject method, it will be mapped as an instance of this class. A programmer can operate on this class instance just as on any other object in the Java programming language and then store any changes made to it by calling the PreparedStatement.setObject method, which will map it back to the SQL type.

It is expected that the implementation of the class for a custom mapping will be done by a tool. In a typical implementation, the programmer would simply supply the name of the SQL UDT, the name of the class to which it is being mapped, and the names of the fields to which each of the attributes of the UDT is to be mapped. The tool will use this information to implement the SQLData.readSQL and SQLData.writeSQL methods. The readSQL method calls the appropriate SQLInput.readXXX methods to read each attribute from an SQLInput object, and the writeSQL method calls SQLOutput.writeXXX methods to write each attribute back to the data source via an SQLOutput object.

An application programmer will not normally call SQLData methods directly, and the SQLInput and SQLOutput methods are called internally by SQLData methods, not by application code.

Package Specification

Specification of the JDBC 2.0 Core API

Package java.sql