[Top] [Prev] [Next] [Bottom]

## Summary of New Features

NOTE: Some of the material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

This appendix summarizes the new features that have been added to the JDBC API over time. Note that in order to use a feature, you must be using a driver that supports that feature.

### A.1 Overview of JDBC 3.0 API Changes

One of the major changes in the JDBC 3.0 API is that it includes the package `javax.sql` (the JDBC Optional Package) as well as the package `java.sql`. This overview is divided into two sections, the first giving new features introduced in the JDBC 3.0 API for both packages, and the second giving the features introduced in the JDBC 2.0 Optional Package. See the JDBC 3.0 API Specification for more detailed information.

#### A.1.1 Features Introduced in the JDBC 3.0 API

The JDBC 3.0 API introduces new material and changes in these areas:

- Savepoint support

  > Added the `Savepoint` interface, which contains new methods to set a savepoint, to release a savepoint, and to roll back a transaction to a designated savepoint.

- Reuse of prepared statements by connection pools

  > Added the ability for deployers to control how prepared statements are pooled and reused by connections.

- Connection pool configuration

  > Defined a number of properties for the `ConnectionPoolDataSource` interface. These properties can be used to describe how `PooledConnection` objects created by `DataSource` objects should be pooled.

- Retrieval of parameter metadata

  > Added the new interface `ParameterMetaData`, which describes the number, type, and properties of parameters to prepared statements.

- Retrieval of auto-generated keys

  > Added a means of retrieving values from columns containing automatically generated values.

- Ability to have multiple open `ResultSet` objects

  > Added the new method `getMoreResults(int)` that takes an argument that specifies whether `ResultSet` objects returned by a `Statement` should be closed before returning any subsequent `ResultSet` objects.

- Passing parameters to `CallableStatement` objects by name

  > Added methods to allow a string to identify the parameter to be set for a `CallableStatement` object.

- Holdable cursor support

  > Added the ability to specify whether a `ResultSet` object is kept open after a transaction has been committed.

- `BOOLEAN` data type

  > Added the data type `java.sql.Types.BOOLEAN`. `BOOLEAN` is logically equivalent to `BIT`.

- Making internal updates to the data in `Blob` and `Clob` objects

  > Added methods to allow the data contained in `Blob` and `Clob` objects to be altered.

- Retrieving and updating the object referenced by a `Ref` object

  > Added methods to retrieve the object referenced by a `Ref` object. Also added the ability to update a referenced object through the `Ref` object.

- Updating of columns containing `BLOB`, `CLOB`, `ARRAY` and `REF` types

  > Addition of the `updateBlob`, `updateClob`, `updateArray`, and `updateRef` methods to the `ResultSet` interface.

- `DATALINK/URL` data type

  > Added the data type `java.sql.Types.DATALINK`, allowing JDBC drivers to store and retrieve references to external data.

- Transform groups and type mapping

  > Described the effect of transform groups and how this is reflected in the metadata.

- Relationship between the JDBC SPI (Service Provider Interface) and the `Connector` architecture

  > Described the relationship between the JDBC SPI and the connector architecture.

- `DatabaseMetadata` APIs

  > Added metadata for retrieving SQL type hierarchies and various other kinds of information relating to new features.

#### A.1.2 Features Introduced in the JDBC 2.0 Optional Package

The following features, which were introduced in the `javax.sql` package, are now part of the JDBC 3.0 API and are included in the J2SE version 1.4:

- Using a `DataSource` Object to Get a Connection

  Using the JNDI API and the new `DataSource` interface, an application does not need to specify a driver name in its code to make a connection to a data source. It can specify a logical name that has been registered with a JNDI naming service and retrieve a `DataSource` object that will get a connection to the desired data source. This capability makes code more portable and much easier to maintain.

- Connection Pooling

  Connection pooling allows an application to (re)use database connections that have already been established instead of always having to create new connections. Because creating and destroying database connections is expensive, this feature is important for good performance, especially for server applications.

  The JDBC 2.0 Optional Package API provides hooks that allow connection pooling to be implemented on top of the JDBC driver layer. This makes it possible to have a single cache of connections available for all of the JDBC drivers in use.

- Support for Distributed Transactions

  The JDBC 2.0 Optional Package API allows a JDBC driver to support the standard two-phase commit protocol defined in the Java Transaction API (JTA). This means that a transaction may be distributed over multiple servers, which lets developers write enterprise applications using Enterprise JavaBeanstm components that are transactional across multiple DBMS servers.

- Rowsets

  `RowSet` objects are simply containers for tabular data that can be implemented on top of the JDBC API. Rowsets make it possible to pass rows of data across a network, so they are likely to be used extensively in distributed applications. Rowsets may be very lean by being disconnected from a data source, making it possible to display data on a thin client. They also make it possible to use scrolling when the underlying DBMS does not support scrollable result sets. A rowset is a JavaBeanstm component and consequently easy to use in building an application, especially with a development tool.

  Typically, a third party will provide a `RowSet` implementation, and the application programmer just uses it. The API for a `RowSet` implementation is generally very easy to use because most of a rowset's functionality is inherited from the `ResultSet` interface. The more complicated aspects of a rowset take place internally and are invisible to the application programmer. There are currently three Early Access implementations of the `RowSet` interface available from the Java Developer Connection (`http://developer.java.sun.com/developer`).

### A.2 Overview of JDBC 2.0 Core API Changes

The JDBC 2.0 core API includes the JDBC 1.0 API and adds enhancements and new functionality to it. These additions put the Java programming language at the forefront of database computing, providing both universal data access and improved performance.

Applications that use earlier versions of the JDBC API can be run using the Java 2 platform with no problem, in keeping with the goal of backward compatibility. However, an application that takes advantage of the new 2.0 features must be run with a driver that implements those features.

The new features in the JDBC 2.0 core API fall into two broad categories: support for new functionality and support for the SQL99 data types.

1. Support for new functionality
   - scrollable result sets
   - batch updates
   - programmatic inserts, deletes, and updates
   - other
     - performance hints
     - character streams for streams of internationalized Unicode characters
     - full precision for `java.math.BigDecimal` values
     - support for time zones in `Date`, `Time`, and `Timestamp` values

2. Support for advanced data types
   - new SQL data types (SQL99 types)
   - increased support for storing persistent objects in the Java programming language

     In addition to making the retrieval, storage, and manipulation of data more convenient, the new features make JDBC applications more efficient. For example, batch updates can increase performance dramatically. The new interfaces `Blob`, `Clob`, and `Array` allow applications to operate on large amounts of data without having to materialize the data on the client, which can mean a significant savings in transfer time and the amount of memory needed. Also, new methods for setting the fetch size and fetch direction let a programmer fine tune an application for more efficient data retrieval and processing.

### A.3 Summary of New Functionality

The JDBC 2.0 core API adds important new functionality. The following sections briefly explain each new area of functionality and summarize the supporting API.

#### A.3.1 Scrollable Result Sets

Scrollable result sets provide the ability to move the cursor forward and backward to a specified position or to a position relative to the current position. The following interfaces have new methods that support scrollable result sets.

- ResultSet
  - methods for moving the cursor to a particular row or to a relative position (either forward or backward)
  - methods for ascertaining the current position of the cursor
  - constants indicating the scrollability of a result set
- Connection
  - new versions of the methods for creating `Statement`, `PreparedStatement`, and `CallableStatement` objects that make the result sets they produce scrollable
- DatabaseMetaData
  - method indicating whether the DBMS and driver support scrollable result sets

#### A.3.2 Batch Updates

The new batch update facility provides the ability to send multiple updates to the database to be executed as a batch rather than sending each update separately. The following interfaces add methods that support batch updates, and the exception `BatchUpdateException` is new.

- Statement, PreparedStatement, and CallableStatement
  - methods for adding update statements to a batch, clearing all update statements, and executing a batch
- DatabaseMetaData
  - method indicating whether the DBMS and driver support batch updates
- BatchUpdateException
  - exception thrown when an error occurs in a batch update

#### A.3.3 Programmatic Updates

Programmatic updates provide the ability to make updates using the JDBC API rather than SQL statements. The following interfaces have new methods and constants that support programmatic updates.

- ResultSet
  - an `updater` method for updating each data type
  - methods for inserting, deleting, or updating a row
  - methods indicating whether a row was inserted, deleted, or updated
  - method for cancelling a row update
  - constants indicating the updatability of a result set
- DatabaseMetaData
  - methods indicating the visibility of changes to a result set
  - methods indicating whether a result set detects inserts, deletes, or updates
  - method indicating whether the DBMS and driver support updatable result sets

#### A.3.4 Other New Features

The JDBC 2.0 core API provides various other new features, which are summarized in the following list.

- Performance enhancements-new methods that allow a programmer to fine tune the retrieval of rows from the database. These methods provide the ability to specify (1) the number of result set rows fetched from the database when more rows are needed and (2) the direction in which rows are fetched from the database.
  - `ResultSet` methods for getting and setting the current fetch size and fetch direction
  - `Statement`, `PreparedStatement`, and `CallableStatement` methods for getting and setting the default fetch size and default fetch direction that result sets generated by executing a query will have when they are first created
- Character streams-new methods that allow character data to be retrieved or sent to the database as a stream of internationalized Unicode characters. These methods replace the deprecated `getUnicodeStream` and `setUnicodeStream` methods.
  - `ResultSet.getCharacterStream`
  - `CallableStatement.getCharacterStream`
  - `PreparedStatement.setCharacterStream`
- Full precision for `java.math.BigDecimal` values-new versions of themethods that retrieve a`java.math.BigDecimal` value with full precision. Unlike the deprecated versions they replace, these new versions do not take a specified precision.
  - `ResultSet.getBigDecimal`
  - `CallableStatement.getBigDecimal`
- Support for time zones-methods with new versions that take a `Calendar` object as a parameter, which allows the driver to use a specified time zone rather than the default when calculating a value for a date, time, or timestamp
  - `ResultSet.getDate`
  - `ResultSet.getTime`
  - `ResultSet.getTimestamp`
  - `CallableStatement.getDate`
  - `CallableStatement.getTime`
  - `CallableStatement.getTimestamp`
  - `PreparedStatement.setDate`
  - `PreparedStatement.setTime`
  - `PreparedStatement.setTimestamp`

### A.4 Support for Advanced Data Types

The JDBC 2.0 core API adds support for using advanced data types, making it as easy to use them as it is to use simple data types. This support includes the ability to store, retrieve, and update even the new SQL data types that are essentially objects, blurring the distinction between object databases and relational databases. The next four sections ("What Are the SQL99 Data Types?" on page 145, "Summary of Support for the SQL99 Data Types" on page 146, "Mapping of the SQL99 Types" on page 148, and "SQL Locators" on page 149) describe how the JDBC 2.0 core API provides support for these advanced data types.

In addition to being able to store objects defined in SQL as values in a database table, programmers writing Java applications can also store objects defined in the Java programming language as values in a database table. The section "Support for Storing Java Objects" on page 149 describes this capability.

Note that a driver is not required to implement functionality that its DBMS does not support, so not all drivers necessarily implement the functionality described here. `DatabaseMetaData` methods such as `getTypeInfo`, `getColumns`, and `getUDTs` may be called to get information about which data types a driver supports.

#### A.4.1 What Are the SQL99 Data Types?

This section briefly describes the new SQL99 data types. Their mapping to types in the Java programming language is described in section A.4.3 on page 148.

The SQL99 data types can be categorized as follows:

- New built-in types-types for storing large objects. These are in addition to the standard built-in data types, such as `CHAR`, `FLOAT`, `DATE`, and so on.
  - `BLOB` (Binary Large Object)
  - `CLOB` (Character Large Object)
- Constructed types-types based on a given base type
  - `REF(`structured type`)`-a reference to the specified SQL structured type
  - `ARRAY[n]`-an array of `n` elements that are all one data type
- User-defined types (UDTs)-new types created with the SQL commandþ`CREATE TYPE`
  - Distinct type-a new type based on the representation of a single built-in type
  - Structured type-a new type containing multiple attributes, each of which may be either a built-in or a user-defined data type
- Locator types-types that are logical pointers to data that resides on the database server
  - `LOCATOR(structured type)`
  - `LOCATOR(array)`
  - `LOCATOR(blob)`
  - `LOCATOR(clob)`

#### A.4.2 Summary of Support for the SQL99 Data Types

The JDBC 2.0 core API supports the SQL 99 data types by means of the following new interfaces, methods, and fields.

- New interfaces for the new data types. The SQL99 types are mapped by the following JDBC 2.0 core API interfaces:
  - `java.sql.Array`
  - `java.sql.Blob`
  - `java.sql.Clob`
  - `java.sql.Ref`
  - `java.sql.Struct`
- Interfaces that support customizing the mapping of UDTs (SQL structured and distinct types) into classes in the Java programming language
  - `SQLData`
  - `SQLInput`
  - `SQLOutput`
- Methods added to existing interfaces in order to retrieve, store, and update the SQL99 types
  - new `getter` methods in the `ResultSet` interface`` to retrieve SQL99 type column values from a result set
  - new `getter` methods in the `CallableStatement` interface`` to retrieve SQL99 type values in output parameters
  - new `setter` methods in the `PreparedStatement` interface to set a SQL99 type column value
  - new `updater` methods in the `ResultSet` interface`` to update values programmatically
- Methods in the `DatabaseMetaData` and `ResultSetMetaData` interfaces for getting metadata about the SQL99 data types
- Fields (constants) added to the class `java.sql.Types` to support new data types and persistent storage
  - `DISTINCT`
  - `STRUCT`
  - `ARRAY`
  - `BLOB`
  - `CLOB`
  - `REF`
  - `JAVA_OBJECT`

#### A.4.3 Mapping of the SQL99 Types

The JDBC API does not try to replicate the SQL99 types exactly; rather, its goal is to map them to types in the Java programming language so that they retain their functionality and are convenient to use. For example, SQL99 has what are called locator types, which are used on a client to designate data that is stored on a database server. Locators can be very useful for dealing with data that is large because they allow the data to be manipulated without having to be materialized on the client machine. SQL99 includes locators for the types `ARRAY`, `BLOB`, `CLOB` and structured types. The JDBC API does not include locators for these types directly (and not at all for structured types) but rather provides interfaces that are implemented such that the driver and DBMS use the appropriate locators behind the scenes. The result is that a developer using the JDBC API to access an SQL `ARRAY`, `BLOB`, or `CLOB` value need not even be aware of locators.

The following SQL99 types are mapped to interfaces in the Java programming language:

- `ARRAY`-mapped to `java.sql.Array`
- `BLOB`-mapped to `java.sql.Blob`
- `CLOB`-mapped to `java.sql.Clob`
- `REF`-mapped to `java.sql.Ref`

- an SQL structured type-mapped to `java.sql.Struct`

Distinct types are not mapped to an interface because they are based on a single built-in type and thus can simply be mapped to the standard mapping for that built-in type. For example, the following is an SQL statement that creates the new type `MONEY`.

>     CREATE TYPE MONEY AS NUMERIC(10, 2)

This new UDT is based on the data type `NUMERIC`, which maps to `java.math.BigDecimal`, so the type `MONEY` maps to `java.math.BigDecimal`. This means that a value of type `MONEY` would be retrieved with the method `getBigDecimal`, stored with the method `setBigDecimal`, and updated with the method `updateBigDecimal`.

#### A.4.4 SQL Locators

An SQL `LOCATOR` is a logical pointer to data that resides on a database server. It typically refers to data that is too large to materialize on the client, such as images or audio. Locators exist only in a client environment, and their existence is transient. A standard implementation will use locators internally for instances of the `Blob`, `Clob`, and `Array` interfaces. This means that `Blob`, `Clob`, and `Array` objects contain a locator that points to the data on the server rather than containing the data itself. Programmers operating on `Blob`, `Clob`, and `Array` instances are actually operating on the database objects they represent. This ability to operate on large database objects without bringing their data to the client is a major plus in performance.

Note that the JDBC API does not call for using the SQL `LOCATOR(`structured type`)`. In a standard implementation, a `Struct` object contains the data of the structured type that it maps and is not implemented internally as a locator, as are `Blob`, `Clob`, and `Array` objects.

#### A.4.5 Support for Storing Java Objects

The JDBC API has always supported persistent storage of objects defined in the Java programming language through the methods `getObject` and `setObject`. But, of course, persistent storage of Java objects does not actually occur unless a DBMS also supports it. Up to this point, support was limited, but a new generation of DBMSs that recognize Java objects as a data type is emerging. In these DBMSs, termed Java relational DBMSs, an instance of a Java class can be stored as a column value in a database table.

[Top] [Prev] [Next] [Bottom]

Copyright © 2001, Sun Microsystems, Inc. All rights reserved.