JavaTM 2 Platform
Std. Ed. v1.3

Package java.sql

Provides the API for accessing and processing data in a data source using the JavaTM programming language.


Interface Summary
Array The mapping in the Java programming language for the SQL type ARRAY.
Blob The representation (mapping) in the JavaTM programming language of an SQL BLOB value.
CallableStatement The interface used to execute SQL stored procedures.
Clob The mapping in the JavaTM 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 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 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"));

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

Related Documentation

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

JavaTM 2 Platform
Std. Ed. v1.3

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.