The JDBC API has been factored into two complementary components. The first component is API that is core to the Java platform (the core JDBC 2.1 API) and comprises the updated contents of the java’s package. This document contains the specification for the core JDBC 2.1 API. The second component, termed the JDBC 2.0 Optional Package API, comprises the contents of a new package, javax.sql, which as its name implies will be delivered as an optional package to the Java platform (formerly Java Standard Extension). The JDBC 2.0 Optional Package API is described in a separate document. The java.sql package contains all of the additions that have been made to the existing interfaces and classes, in addition to a few new classes and interfaces. The new jav-ax.sql package has been introduced to contain the parts of the JDBC API which are closely related to other pieces of the Java platform that are themselves Optional Packages. Such as the Java Naming and Directory Interface (JNDI), and the Java Transaction Service (JTS).
In addition, some advanced features that are easily separable from the core JDBC API, such as connection pooling and row sets, have also been added to javax.sql. Putting these advanced facilities into an optional package instead of into core will help keep the core JDBC API small and focused. Since optional packages are downloadable, it will always be possible to deploy an application which uses the features in the JDBC Optional Package that will “run any-where,” since if an optional package isn’t installed on a client machine; it can be downloaded along with the application that uses it.
Changes to Classes and Interfaces
The list below contains all of the JDBC 2.1 API core classes and interfaces. Interfaces and classes that are new are listed in bold type. All of the interfaces and classes present in the JDBC 1.0 API are also present in the core JDBC 2.1 API, however, some of the JDBC 1.0 technology interfaces have gained additional methods. The interfaces that contain new methods are listed in italics and those that have not changed are in normal type.
java.sql.Array
java.sql.BatchUpdateException
java.sql.Blob
java.sql.CallableStatement
java.sql.Clob
java.sql.Connection
JDBC 2.1 Core API
java.sql.DatabaseMetaData
java.sql.DataTruncation
java.sql.Date
java.sql.Driver
java.sql.DriverManager
java.sql.DriverPropertyInfo
java.sql.PreparedStatement
java.sql.Ref
java.sql.ResultSet
java.sql.ResultSetMetaData
java.sql.SQLData
java.sql.SQLException
java.sql.SQLInput
java.sql.SQLOutput
java.sql.SQLWarning
java.sql.Statement
java.sql.Struct
java.sql.Time
java.sql.Timestamp
java.sql.Types
The separate core JDBC 2.1 API documentation contains the Java programming language definitions of the java.sql interfaces and classes listed above. The figure below shows the more important core interfaces and their relationships. The important relationships between interfaces have not changed with the introduction of the new JDBC API.
The list below contains the classes and interfaces that comprise the javax.sql pack-age.
A detailed specification of these new types is contained in a separate document.
javax.sql.ConnectionEvent
javax.sql.ConnectionEventListener
javax.sql.ConnectionPoolDataSurce
javax.sql.DataSource
javax.sql.PooledConnection
javax.sql.RowSet
javax.sql.RowSetEvent
javax.sql.RowSetInternal
javax.sql.RowSetListener
javax.sql.RowSetMetaData
javax.sql.RowSetReader
javax.sql.RowSetWriter
javax.sql.XAConnection
javax.sql.XADataSource
Modified
Connection
DriverManager
PreparedStatement
Statement Result Set
Data types: Date, Time,
Timestamp, Numeric, Callable Statement
Commit, abort
create Statement
GetXXX
Subclass
Subclass
ExecuteQuery
Prepare Statement
GetXXX
Get Connection
Prepare Call setXXX
getMoreResults
execute
built-in Java types, etc.
executeQuery
Result Set Enhancements
This chapter discusses the new functionality that has been added to result sets. The goal of the enhancements is to add two new basic capabilities to result sets: scrolling and updatability. Several methods have also been added to enable a JDBC driver to deliver improved performance when processing results. A variety of examples are included to illustrate the new features.
Scrolling
A result set created by executing a statement may support the ability to move backward (last-to-first) through its contents, as well as forward (first-to-last). Result sets that support this capability are called scrollable result sets. Result sets that are scrollable also support relative and absolute positioning. Absolute positioning is the ability to move directly to a row by specifying its absolute position in the result set, while relative positioning gives the ability to move to a row by specifying a position that is relative to the current row. The definition of absolute and relative positioning in the JDBC API is modeled on the X/Open SQL CLI specification.
Result Set types
The JDBC 1.0 API provided one result set type forward-only. The JDBC 2.1 core API provides three result set types: forward-only, scroll-insensitive, and scroll-sensitive. As their names suggest, the new result set types support scrolling, but they differ in their ability to make changes visible while they are open.
A scroll-insensitive result set is generally not sensitive to changes that are made while it is open. A scroll-insensitive result set provides a static view of the underlying data it contains. The membership, order, and column values of rows in a scroll-insensitive result set are typically fixed when the result set is created. On the other hand, a scroll-sensitive result set is sensitive to changes that are made while it is open, and provides a ‘dynamic’ view of the underlying data. For example, when using a scroll-sensitive result set, changes in the underlying column values of rows are visible. The membership and ordering of rows in the result set may be fixed—this is implementation defined.
Concurrency types
An application may choose from two different concurrency types for a result set: read only and updatable. A result set that uses read-only concurrency does not allow updates of its contents. This can increase the overall level of concurrency between transactions, since any number of read-only locks may be held on a data item simultaneously.
A result set that is updatable allows updates and may use database write locks to me - date access to the same data item by different transactions. Since only a single write lock may be held at a time on a data item, this can reduce concurrency. Alternatively, an optimistic concurrency control scheme may be used if it is thought that conflicting accesses to data will be rare. Optimistic concurrency control implementations typically compare rows either by value or by a version number to determine if an update conflict has occurred.
Performance
Two performance hints may be given to a JDBC 2.1 technology-enabled driver to make access to result set data more efficient. Specifically, the number of rows to be fetched from the database each time more rows are needed can be specified, and a direction for processing the rows—forward, reverse, or unknown—can be given as well. These values can be changed for an individual result set at any time. A JDBC driver may ignore a performance hint if it chooses.
Creating a result set
The example below illustrates creation of a result set that is forward-only and uses read only concurrency. No performance hints are given by the example, so the driver is free to do whatever it thinks will result in the best performance. The transaction isolation level for the connection is not specified, so the default transaction isolation level of the underlying database is used for the result set that is created. Note that this code is just written using the JDBC 1.0 API, and that it produces the same type of result set that would have been produced by the JDBC 1.0 API.
