<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!--Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. This code is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 along with this work; if not, write to the Free Software Foundation,Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USAor visit www.oracle.com if you need additional information or have anyquestions.--> </head>   <body bgcolor="white"> Provides the API for server side data source access and processing fromthe Java<sup><font size=-2>TM</font></sup> programming language.This package supplements the <code>java.sql</code>package and, as of the version 1.4 release, is included in the Java Platform, Standard Edition(Java SE<sup><font size=-2>TM</sup></font>).It remains an essential part of the Java Platform, Enterprise Edition(Java EE<sup><font size=-2>TM</sup></font>).<P>The <code>javax.sql</code> package provides for the following:<OL>  <LI>The <code>DataSource</code> interface as an alternative to the       <code>DriverManager</code> for establishing a       connection with a data source  <LI>Connection pooling and Statement pooling  <LI>Distributed transactions  <LI>Rowsets</OL><P>Applications use the <code>DataSource</code> and <code>RowSet</code>APIs directly, but the connection pooling and distributed transactionAPIs are used internally by the middle-tier infrastructure. <H2>Using a <code>DataSource</code> Object to Make a Connection</H2> The <code>javax.sql</code> package provides the preferredway to make a connection with a data source.  The <code>DriverManager</code>class, the original mechanism, is still valid, and code using it willcontinue to run.  However, the newer <code>DataSource</code> mechanismis preferred because it offers many advantages over the <code>DriverManager</code> mechanism.<P>These are the main advantages of using a <code>DataSource</code> object to make a connection:<UL>    <LI>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.  <LI>Connection  and Statement pooling and distributed transactions are available      through a <code>DataSource</code> object that is      implemented to work with the middle-tier infrastructure.      Connections made through the <code>DriverManager</code>      do not have connection and statement pooling or distributed transaction      capabilities.</UL><P>Driver vendors provide <code>DataSource</code> implementations. Aparticular <code>DataSource</code> object represents a particularphysical data source, and each connection the <code>DataSource</code> objectcreates is a connection to that physical data source. <P>A logical name for the data source is registered with a naming service thatuses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>  (JNDI) API, usually by a system administrator or someone performing the duties of a system administrator. An application can retrieve the<code>DataSource</code> object it wants by doing a lookup on the logicalname that has been registered for it.  The application can then use the <code>DataSource</code> object to create a connection to the physical datasource it represents.<P>A <code>DataSource</code> object can be implemented to work with the middle tier infrastructure so that the connections it produces will bepooled for reuse. An application that uses such a <code>DataSource</code> implementation will automatically get a connection that participates inconnection pooling.  A <code>DataSource</code> object can also be implemented to work with the middle tier infrastructure so that the connections it produces can beused for distributed transactions without any special coding. <H2>Connection Pooling and Statement Pooling</H2> Connections made via a <code>DataSource</code>object that is implemented to work with a middle tier connection pool managerwill participate in connection pooling.  This can improve performancedramatically 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.<P>Connection pooling is totally transparent.  It is done automaticallyin the middle tier of a Java EE configuration, so from an application's viewpoint, no change in code is required. An application simply usesthe <code>DataSource.getConnection</code> method to get the pooledconnection and uses it the same way it uses any <code>Connection</code>object.<P>The classes and interfaces used for connection pooling are:<UL>  <LI><code>ConnectionPoolDataSource</code>  <LI><code>PooledConnection</code>  <LI><code>ConnectionEvent</code>  <LI><code>ConnectionEventListener</code>   <LI><code>StatementEvent</code>  <LI><code>StatementEventListener</code></UL>The connection pool manager, a facility in the middle tier ofa three-tier architecture, uses these classes and interfacesbehind the scenes.  When a <code>ConnectionPoolDataSource</code> objectis called on to create a <code>PooledConnection</code> object, theconnection pool manager will register as a <code>ConnectionEventListener</code>object with the new <code>PooledConnection</code> object.  When the connectionis closed or there is an error, the connection pool manager (being a listener)gets a notification that includes a <code>ConnectionEvent</code> object.<p>If the connection pool manager supports <code>Statement</code> pooling, for<code>PreparedStatements</code>, which can be determined by invoking the method <code>DatabaseMetaData.supportsStatementPooling</code>,  theconnection pool manager will register as a <code>StatementEventListener</code>object with the new <code>PooledConnection</code> object.  When the <code>PreparedStatement</code> is closed or there is an error, the connection pool manager (being a listener)gets a notification that includes a <code>StatementEvent</code> object.<p> <H2>Distributed Transactions</H2> As with pooled connections, connections made via a <code>DataSource</code>object that is implemented to work with the middle tier infrastructuremay participate in distributed transactions.  This gives an applicationthe ability to involve data sources on multiple servers in a singletransaction.<P>The classes and interfaces used for distributed transactions are:<UL>  <LI><code>XADataSource</code>  <LI><code>XAConnection</code></UL>These interfaces are used by the transaction manager; an application doesnot use them directly.<P>The <code>XAConnection</code> interface is derived from the<code>PooledConnection</code> interface, so what applies to a pooled connectionalso 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 anythingthat would interfere with the transaction manager's handling of the transaction.Specifically, an application cannot call the methods <code>Connection.commit</code> or <code>Connection.rollback</code>, and it cannot set the connection to be in auto-commit mode (that is, it cannot call <code>Connection.setAutoCommit(true)</code>).  <P>An application does not need to do anything special to participate in adistributed transaction.It simply creates connections to the data sources it wants to use viathe <code>DataSource.getConnection</code> method, just as it normally does.The transaction manager manages the transaction behind the scenes.  The<code>XADataSource</code> interface creates <code>XAConnection</code> objects, andeach <code>XAConnection</code> object creates an <code>XAResource</code> object that the transaction manager uses to manage the connection.  <H2>Rowsets</H2>The <code>RowSet</code> interface works with various other classes andinterfaces behind the scenes. These can be grouped into three categories.<OL><LI>Event Notification <UL>  <LI><code>RowSetListener</code><br>A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>component because it has properties and participates in the JavaBeansevent notification mechanism. The <code>RowSetListener</code> interface is implemented by a component that wants to be notified about events that occur to a particular <code>RowSet</code> object.  Such a component registersitself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>method.<P>When the <code>RowSet</code> object changes one of its rows, changes all ofit 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.<P>  <LI><code>RowSetEvent</code><br>As part of its internal notification process, a <code>RowSet</code> objectcreates an instance of <code>RowSetEvent</code> and passes it to the listener.The listener can use this <code>RowSetEvent</code> object to find out which rowsethad the event.</UL><P><LI>Metadata <UL>  <LI><code>RowSetMetaData</code><br>This interface, derived from the<code>ResultSetMetaData</code> interface, provides information aboutthe columns in a <code>RowSet</code> object.  An application can use<code>RowSetMetaData</code> methods to find out how many columns therowset contains and what kind of data each column can contain.<P>The <code>RowSetMetaData</code> interface provides methods forsetting the information about columns, but an application would notnormally use these methods.  When an application calls the <code>RowSet</code> method <code>execute</code>, the <code>RowSet</code> object will containa new set of rows, and its <code>RowSetMetaData</code> object will have beeninternally updated to contain information about the new columns.<P></UL><LI>The Reader/Writer Facility<br>A <code>RowSet</code> object that implements the <code>RowSetInternal</code>interface can call on the <code>RowSetReader</code> object associated with itto populate itself with data.  It can also call on the <code>RowSetWriter</code>object associated with it to write any changes to its rows back to thedata 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. <UL>  <LI><code>RowSetInternal</code><br>By implementing the <code>RowSetInternal</code> interface, a <code>RowSet</code> object gets access toits internal state and is able to call on its reader and writer. A rowsetkeeps track of the values in its current rows and of the values that immediatelypreceded the current ones, referred to as the <i>original</i> values.  A rowsetalso 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 <code>RowSetInternal</code> methods behind the scenes to get access tothis information.  An application does not normally invoke these methods directly.<P>  <LI><code>RowSetReader</code><br>A disconnected <code>RowSet</code> object that has implemented the <code>RowSetInternal</code> interface can call on its reader (the <code>RowSetReader</code> object associated with it) to populate it with data.  When an application calls the <code>RowSet.execute</code> method, that method calls on the rowset's reader to do much of the work. Implementationscan 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 closesthe connection. A reader may also update the <code>RowSetMetaData</code> objectfor its rowset.  The rowset's internal state is also updated, either by thereader or directly by the method <code>RowSet.execute</code>.    <LI><code>RowSetWriter</code><br>A disconnected <code>RowSet</code> object that has implemented the <code>RowSetInternal</code> interface can call on its writer (the <code>RowSetWriter</code> object associated with it) to write changesback to the underlying data source.  Implementations may vary widely, butgenerally, a writer will do the following: <P><UL>  <LI>Make a connection to the data source   <LI>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  <LI>Write the new values to the data source if there is no conflict   <LI>Close the connection</UL>  </UL></OL><P>The <code>RowSet</code> interface may be implemented in any number ofways, and anyone may write an implementation. Developers are encouraged to use their imaginations in coming up with new ways to use rowsets.<P><B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a JDBC technology driver that implements the JDBC 4.0 API.You must check your driver documentation to be sure that it implementsthe particular features you want to use.<P> <h2>Package Specification</h2> <ul>  <li><a href="http://java.sun.com/products/jdbc/download.html">Specification of the       JDBC 4.0 API</a></ul> <h2>Related Documentation</h2> The Java Series book published by Addison-Wesley Longman provides detailedinformation about the classes and interfaces in the <code>javax.sql</code>package:  <ul>  <li><a href="http://java.sun.com/docs/books/jdbc"><i>JDBC<sup><font size=-2>TM</font></sup>      API Tutorial and Reference, Third Edition:</i></a></ul><P>@since 1.4</body></html>