Package javax.sql

Provides the API for server side data source access and processing from the JavaTM programming language.

See:
          Description

Interface Summary
ConnectionEventListener A ConnectionEventListener is an object that registers to receive events generated by a PooledConnection.
ConnectionPoolDataSource A ConnectionPoolDataSource object is a factory for PooledConnection objects.
DataSource A DataSource object is a factory for Connection objects.
PooledConnection A PooledConnection object is a connection object that provides hooks for connection pool management.
RowSet The RowSet interface adds support to the JDBC API for the JavaBeans(TM) component model.
RowSetInternal A rowset object presents itself to a reader or writer as an instance of RowSetInternal.
RowSetListener The RowSetListener interface is implemented by a component that wants to be notified when a significant event happens in the life of a RowSet
RowSetMetaData The RowSetMetaData interface extends ResultSetMetaData with methods that allow a metadata object to be initialized.
RowSetReader An object implementing the RowSetReader interface may be registered with a RowSet object that supports the reader/writer paradigm.
RowSetWriter An object that implements the RowSetWriter interface may be registered with a RowSet object that supports the reader/writer paradigm.
XAConnection An XAConnection object provides support for distributed transactions.
XADataSource A factory for XAConnection objects.
 

Class Summary
ConnectionEvent The ConnectionEvent class provides information about the source of a connection related event.
RowSetEvent A RowSetEvent is generated when something important happens in the life of a rowset, like when a column value changes.
 

Package javax.sql Description

Provides the API for server side data source access and processing from the JavaTM programming language. This package supplements the java.sql package and, as of the version 1.4 release, is included in the JavaTM 2 SDK, Standard Edition. It remains an essential part of the Java 2 SDK, Enterprise Edition (J2EETM).

The javax.sql package provides for the following:

  1. The DataSource interface as an alternative to the DriverManager for establishing a connection with a data source
  2. Connection pooling
  3. Distributed transactions
  4. Rowsets

Applications use the DataSource and RowSet APIs directly, but the connection pooling and distributed transaction APIs are used internally by the middle-tier infrastructure.

Using a DataSource Object to Make a Connection

The javax.sql package provides the preferred way to make a connection with a data source. The DriverManager class, the original mechanism, is still valid, and code using it will continue to run. However, the newer DataSource mechanism is preferred because it offers many advantages over the DriverManager mechanism.

These are the main advantages of using a DataSource object to make a connection:

Driver vendors provide DataSource implementations. A particular DataSource object represents a particular physical data source, and each connection the DataSource object creates is a connection to that physical data source.

A logical name for the data source is registered with a naming service that uses the Java Naming and Directory InterfaceTM (JNDI) API, usually by a system administrator or someone performing the duties of a system administrator. An application can retrieve the DataSource object it wants by doing a lookup on the logical name that has been registered for it. The application can then use the DataSource object to create a connection to the physical data source it represents.

A DataSource object can be implemented to work with the middle tier infrastructure so that the connections it produces will be pooled for reuse. An application that uses such a DataSource implementation will automatically get a connection that participates in connection pooling. A DataSource object can also be implemented to work with the middle tier infrastructure so that the connections it produces can be used for distributed transactions without any special coding.

Connection Pooling

Connections made via a DataSource object that is implemented to work with a middle tier connection pool manager will participate in connection pooling. This can improve performance dramatically because creating new connections is very expensive. Connection pooling allows a connection to be used and reused, thus cutting down substantially on the number of new connections that need to be created.

Connection pooling is totally transparent. It is done automatically in the middle tier of a J2EE configuration, so from an application's viewpoint, no change in code is required. An application simply uses the DataSource.getConnection method to get the pooled connection and uses it the same way it uses any Connection object.

The classes and interfaces used for connection pooling are:

The connection pool manager, a facility in the middle tier of a three-tier architecture, uses these classes and interfaces behind the scenes. When a ConnectionPoolDataSource object is called on to create a PooledConnection object, the connection pool manager will register as a ConnectionEventListener object with the new PooledConnection object. When the connection is closed or there is an error, the connection pool manager (being a listener) gets a notification that includes a ConnectionEvent object.

Distributed Transactions

As with pooled connections, connections made via a DataSource object that is implemented to work with the middle tier infrastructure may participate in distributed transactions. This gives an application the ability to involve data sources on multiple servers in a single transaction.

The classes and interfaces used for distributed transactions are:

These interfaces are used by the transaction manager; an application does not use them directly.

The XAConnection interface is derived from the PooledConnection interface, so what applies to a pooled connection also applies to a connection that is part of a distributed transaction. A transaction manager in the middle tier handles everything transparently. The only change in application code is that an application cannot do anything that would interfere with the transaction manager's handling of the transaction. Specifically, an application cannot call the methods Connection.commit or Connection.rollback, and it cannot set the connection to be in auto-commit mode (that is, it cannot call Connection.setAutoCommit(true)).

An application does not need to do anything special to participate in a distributed transaction. It simply creates connections to the data sources it wants to use via the DataSource.getConnection method, just as it normally does. The transaction manager manages the transaction behind the scenes. The XADataSource interface creates XAConnection objects, and each XAConnection object creates an XAResource object that the transaction manager uses to manage the connection.

Rowsets

The RowSet interface works with various other classes and interfaces behind the scenes. These can be grouped into three categories.
  1. Event Notification

  2. Metadata
  3. The Reader/Writer Facility
    A RowSet object that implements the RowSetInternal interface can call on the RowSetReader object associated with it to populate itself with data. It can also call on the RowSetWriter object associated with it to write any changes to its rows back to the data source from which it originally got the rows. A rowset that remains connected to its data source does not need to use a reader and writer because it can simply operate on the data source directly.

The RowSet interface may be implemented in any number of ways, and anyone may write an implementation. Developers are encouraged to use their imaginations in coming up with new ways to use rowsets.

Package Specification

Related Documentation

The Java Series book published by Addison-Wesley Longman provides detailed information about the classes and interfaces in the javax.sql package: