Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package java.sql

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

See:
Description

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:

- `java.sql` package--the JDBC 2.0 core API
  - JDBC API included in the JDKTM 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 JavaTM 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:

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:
   - 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

## Related Documentation

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

- Getting Started--overviews of the major interfaces
- Chapters on the JDBC API from the online version of The Java Tutorial Continued

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

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-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.