Package javax.sql
java.sql
 package and, as of the version 1.4 release, is included in the
 Java Platform, Standard Edition (Java SE).
 It remains an essential part of the Java Platform, Enterprise Edition
 (Java EE).
 
 The javax.sql package provides for the following:
 
- The DataSourceinterface as an alternative to theDriverManagerfor establishing a connection with a data source
- Connection pooling and Statement pooling
- Distributed transactions
- 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:
 
- Changes can be made to a data source's properties, which means that it is not necessary to make changes in application code when something about the data source or driver changes.
- Connection  and Statement pooling and distributed transactions are available
 through a DataSourceobject that is implemented to work with the middle-tier infrastructure. Connections made through theDriverManagerdo not have connection and statement pooling or distributed transaction capabilities.
 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 Interface
 (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 and Statement 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 Java EE 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:
- ConnectionPoolDataSource
- PooledConnection
- ConnectionEvent
- ConnectionEventListener
- StatementEvent
- StatementEventListener
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.
 
 If the connection pool manager supports Statement pooling, for
 PreparedStatements, which can be determined by invoking the method
 DatabaseMetaData.supportsStatementPooling,  the
 connection pool manager will register as a StatementEventListener
 object with the new PooledConnection object.  When the
 PreparedStatement is closed or there is an error, the connection
 pool manager (being a listener)
 gets a notification that includes a StatementEvent 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:
- XADataSource
- XAConnection
 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
TheRowSet interface works with various other classes and
 interfaces behind the scenes. These can be grouped into three categories.
 - Event Notification
 - RowSetListener
 A- RowSetobject is a JavaBeans component because it has properties and participates in the JavaBeans event notification mechanism. The- RowSetListenerinterface is implemented by a component that wants to be notified about events that occur to a particular- RowSetobject. Such a component registers itself as a listener with a rowset via the- RowSet.addRowSetListenermethod.- When the - RowSetobject 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- RowSetobject creates an instance of- RowSetEventand passes it to the listener. The listener can use this- RowSetEventobject to find out which rowset had the event.
 
- Metadata
 - RowSetMetaData
 This interface, derived from the- ResultSetMetaDatainterface, provides information about the columns in a- RowSetobject. An application can use- RowSetMetaDatamethods to find out how many columns the rowset contains and what kind of data each column can contain.- The - RowSetMetaDatainterface provides methods for setting the information about columns, but an application would not normally use these methods. When an application calls the- RowSetmethod- execute, the- RowSetobject will contain a new set of rows, and its- RowSetMetaDataobject will have been internally updated to contain information about the new columns.
 
- The Reader/Writer Facility
 ARowSetobject that implements theRowSetInternalinterface can call on theRowSetReaderobject associated with it to populate itself with data. It can also call on theRowSetWriterobject 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- RowSetInternalinterface, a- RowSetobject 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- RowSetInternalmethods behind the scenes to get access to this information. An application does not normally invoke these methods directly.
- RowSetReader
 A disconnected- RowSetobject that has implemented the- RowSetInternalinterface can call on its reader (the- RowSetReaderobject associated with it) to populate it with data. When an application calls the- RowSet.executemethod, 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- RowSetMetaDataobject 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- RowSetobject that has implemented the- RowSetInternalinterface can call on its writer (the- RowSetWriterobject 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
Related Documentation
 The Java Series book published by Addison-Wesley Longman provides detailed
 information about the classes and interfaces in the javax.sql
 package:
 
- “JDBC™API Tutorial and Reference, Third Edition”
- 
ClassDescriptionInterface that defines the methods which are common betweenDataSource,XADataSourceandConnectionPoolDataSource.AnEventobject that provides information about the source of a connection-related event.An object that registers to be notified of events generated by aPooledConnectionobject.A factory forPooledConnectionobjects.A factory for connections to the physical data source that thisDataSourceobject represents.An object that provides hooks for connection pool management.A builder created from aConnectionPoolDataSourceobject, used to establish a connection to the database that thedata sourceobject represents.The interface that adds support to the JDBC API for the JavaBeans component model.AnEventobject generated when an event occurs to aRowSetobject.The interface that aRowSetobject implements in order to present itself to aRowSetReaderorRowSetWriterobject.An interface that must be implemented by a component that wants to be notified when a significant event happens in the life of aRowSetobject.An object that contains information about the columns in aRowSetobject.The facility that a disconnectedRowSetobject calls on to populate itself with rows of data.An object that implements theRowSetWriterinterface, called a writer.AStatementEventis sent to allStatementEventListeners which were registered with aPooledConnection.An object that registers to be notified of events that occur on PreparedStatements that are in the Statement pool.An object that provides support for distributed transactions.A builder created from aXADataSourceobject, used to establish a connection to the database that thedata sourceobject represents.A factory forXAConnectionobjects that is used internally.