Provides the API for accessing and processing data in a data source using the JavaTM 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 JavaTM 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 JavaTM 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 JDBCTM 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 JDBCTM 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:

What the java.sql Package Contains

The java.sql package contains API for the following:

New Features in the JDBC 2.0 Core API

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:
  1. Defining the SQL structured type or DISTINCT type in SQL
  2. Defining the class in the Java programming language to which the SQL UDT will be mapped. This class must implement the SQLData interface.
  3. Making an entry in a Connection object's type map that contains two things:

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 {@link java.util.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 {@link 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

Related Documentation

For overviews of the basic interfaces and a tutorial, please see: