Provides the API for data source access and manipulation of tabular data as JavaBeans.
This package was originally developed as a supplement to `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 in the JDBC for CDC/FP Optional Package provides for the following:

1. The `DataSource` interface as an alternative to the `DriverManager` for establishing a connection with a data source
2. Rowsets

Applications use the `DataSource` and `RowSet` APIs directly.

## 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` mechanism has been removed.

These are the main advantages of using a `DataSource` object to make a connection in the CDC environment:

- The properties are configured using setter methods not via a cryptic URL.
- The overhead of using the DriverManager can be avoided.

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.

It is possible to use a `DataSource` object directly to create a connection. An application can create an instance of a `DataSource`, set the neccessary properties and create a `Connection` object. The following code fragment demonstrates:

> `// create an instance of the vendors data source
> VendorDataSource vds = new VendorDataSource();
> `

> `// now set the properties
> vds.setServerName("dbServer.acct");
> vds.setPortNumber(1234);
> `

> `// get a connection
> Connection conn = vds.getConnection(user, pass);
> `

The properties that are needed to connect using a particular `DataSource` will depend on the implementation. The JDBC 3.0 API Specification lists the properties that every driver must support. (see Package Specification below)

See the DataSource documentation for further information.

## Rowsets

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

1. Event Notification
   - `RowSetListener`
     A `RowSet` object is a JavaBeansTM component because it has properties and participates in the JavaBeans event notification mechanism. The `RowSetListener` interface is implemented by a component that wants to be notified about events that occur to a particular `RowSet` object. Such a component registers itself as a listener with a rowset via the `RowSet.addRowSetListener` method.

     When the `RowSet` object changes one of its rows, changes all of it rows, or moves its cursor, it also notifies each listener that is registered with it. The listener reacts by carrying out its implementation of the notification method called on it.

   - `RowSetEvent`
     As part of its internal notification process, a `RowSet` object creates an instance of `RowSetEvent` and passes it to the listener. The listener can use this `RowSetEvent` object to find out which rowset had the event.

2. Metadata
   - `RowSetMetaData`
     This interface, derived from the `ResultSetMetaData` interface, provides information about the columns in a `RowSet` object. An application can use `RowSetMetaData` methods to find out how many columns the rowset contains and what kind of data each column can contain.

     The `RowSetMetaData` interface provides methods for setting the information about columns, but an application would not normally use these methods. When an application calls the `RowSet` method `execute`, the `RowSet` object will contain a new set of rows, and its `RowSetMetaData` object will have been internally updated to contain information about the new columns.

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.
   - `RowSetInternal`
     By implementing the `RowSetInternal` interface, a `RowSet` object gets access to its internal state and is able to call on its reader and writer. A rowset keeps track of the values in its current rows and of the values that immediately preceded the current ones, referred to as the original values. A rowset also keeps track of (1) the parameters that have been set for its command and (2) the connection that was passed to it, if any. A rowset uses the `RowSetInternal` methods behind the scenes to get access to this information. An application does not normally invoke these methods directly.

   - `RowSetReader`
     A disconnected `RowSet` object that has implemented the `RowSetInternal` interface can call on its reader (the `RowSetReader` object associated with it) to populate it with data. When an application calls the `RowSet.execute` method, that method calls on the rowset's reader to do much of the work. Implementations can vary widely, but generally a reader makes a connection to the data source, reads data from the data source and populates the rowset with it, and closes the connection. A reader may also update the `RowSetMetaData` object for its rowset. The rowset's internal state is also updated, either by the reader or directly by the method `RowSet.execute`.
   - `RowSetWriter`
     A disconnected `RowSet` object that has implemented the `RowSetInternal` interface can call on its writer (the `RowSetWriter` object associated with it) to write changes back to the underlying data source. Implementations may vary widely, but generally, a writer will do the following:

     - Make a connection to the data source
     - Check to see whether there is a conflict, that is, whether a value that has been changed in the rowset has also been changed in the data source
     - Write the new values to the data source if there is no conflict
     - Close the connection

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

- Specification of the JDBC 3.0 API

## Related Documentation

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

- JDBCTM API Tutorial and Reference, Second Edition: Universal Data Access for the Java 2 Platform

## Related specifications

The JDBC RowSet Implementations - JSR-114 is seeking to standardize the RowSet Implementations for use with all JDBC APIs.

- JDBC RowSet Implementations