1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2<html> 3<head> 4<!-- 5Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 7 8This code is free software; you can redistribute it and/or modify it 9under the terms of the GNU General Public License version 2 only, as 10published by the Free Software Foundation. Oracle designates this 11particular file as subject to the "Classpath" exception as provided 12by Oracle in the LICENSE file that accompanied this code. 13 14This code is distributed in the hope that it will be useful, but WITHOUT 15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 17version 2 for more details (a copy is included in the LICENSE file that 18accompanied this code). 19 20You should have received a copy of the GNU General Public License version 212 along with this work; if not, write to the Free Software Foundation, 22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 23 24Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 25or visit www.oracle.com if you need additional information or have any 26questions. 27--> 28 29</head> 30 31 32 33<body bgcolor="white"> 34 35Provides the API for server side data source access and processing from 36the Java<sup><font size=-2>TM</font></sup> programming language. 37This package supplements the <code>java.sql</code> 38package and, as of the version 1.4 release, is included in the 39Java Platform, Standard Edition 40(Java SE<sup><font size=-2>TM</sup></font>). 41It remains an essential part of the Java Platform, Enterprise Edition 42(Java EE<sup><font size=-2>TM</sup></font>). 43<P> 44The <code>javax.sql</code> package provides for the following: 45<OL> 46 <LI>The <code>DataSource</code> interface as an alternative to the 47 <code>DriverManager</code> for establishing a 48 connection with a data source 49 <LI>Connection pooling and Statement pooling 50 <LI>Distributed transactions 51 <LI>Rowsets 52</OL> 53<P> 54Applications use the <code>DataSource</code> and <code>RowSet</code> 55APIs directly, but the connection pooling and distributed transaction 56APIs are used internally by the middle-tier infrastructure. 57 58<H2>Using a <code>DataSource</code> Object to Make a Connection</H2> 59 60The <code>javax.sql</code> package provides the preferred 61way to make a connection with a data source. The <code>DriverManager</code> 62class, the original mechanism, is still valid, and code using it will 63continue to run. However, the newer <code>DataSource</code> mechanism 64is preferred because it offers many advantages over the 65<code>DriverManager</code> mechanism. 66<P> 67These are the main advantages of using a <code>DataSource</code> object to 68make a connection: 69<UL> 70 71 <LI>Changes can be made to a data source's properties, which means 72 that it is not necessary to make changes in application code when 73 something about the data source or driver changes. 74 <LI>Connection and Statement pooling and distributed transactions are available 75 through a <code>DataSource</code> object that is 76 implemented to work with the middle-tier infrastructure. 77 Connections made through the <code>DriverManager</code> 78 do not have connection and statement pooling or distributed transaction 79 capabilities. 80</UL> 81<P> 82Driver vendors provide <code>DataSource</code> implementations. A 83particular <code>DataSource</code> object represents a particular 84physical data source, and each connection the <code>DataSource</code> object 85creates is a connection to that physical data source. 86<P> 87A logical name for the data source is registered with a naming service that 88uses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup> 89(JNDI) API, usually by a system administrator or someone performing the 90duties of a system administrator. An application can retrieve the 91<code>DataSource</code> object it wants by doing a lookup on the logical 92name that has been registered for it. The application can then use the 93<code>DataSource</code> object to create a connection to the physical data 94source it represents. 95<P> 96A <code>DataSource</code> object can be implemented to work with the 97middle tier infrastructure so that the connections it produces will be 98pooled for reuse. An application that uses such a <code>DataSource</code> 99implementation will automatically get a connection that participates in 100connection pooling. 101A <code>DataSource</code> object can also be implemented to work with the 102middle tier infrastructure so that the connections it produces can be 103used for distributed transactions without any special coding. 104 105<H2>Connection Pooling and Statement Pooling</H2> 106 107Connections made via a <code>DataSource</code> 108object that is implemented to work with a middle tier connection pool manager 109will participate in connection pooling. This can improve performance 110dramatically because creating new connections is very expensive. 111Connection pooling allows a connection to be used and reused, 112thus cutting down substantially on the number of new connections 113that need to be created. 114<P> 115Connection pooling is totally transparent. It is done automatically 116in the middle tier of a Java EE configuration, so from an application's 117viewpoint, no change in code is required. An application simply uses 118the <code>DataSource.getConnection</code> method to get the pooled 119connection and uses it the same way it uses any <code>Connection</code> 120object. 121<P> 122The classes and interfaces used for connection pooling are: 123<UL> 124 <LI><code>ConnectionPoolDataSource</code> 125 <LI><code>PooledConnection</code> 126 <LI><code>ConnectionEvent</code> 127 <LI><code>ConnectionEventListener</code> 128 <LI><code>StatementEvent</code> 129 <LI><code>StatementEventListener</code> 130</UL> 131The connection pool manager, a facility in the middle tier of 132a three-tier architecture, uses these classes and interfaces 133behind the scenes. When a <code>ConnectionPoolDataSource</code> object 134is called on to create a <code>PooledConnection</code> object, the 135connection pool manager will register as a <code>ConnectionEventListener</code> 136object with the new <code>PooledConnection</code> object. When the connection 137is closed or there is an error, the connection pool manager (being a listener) 138gets a notification that includes a <code>ConnectionEvent</code> object. 139<p> 140If the connection pool manager supports <code>Statement</code> pooling, for 141<code>PreparedStatements</code>, which can be determined by invoking the method 142<code>DatabaseMetaData.supportsStatementPooling</code>, the 143connection pool manager will register as a <code>StatementEventListener</code> 144object with the new <code>PooledConnection</code> object. When the 145<code>PreparedStatement</code> is closed or there is an error, the connection 146pool manager (being a listener) 147gets a notification that includes a <code>StatementEvent</code> object. 148<p> 149 150<H2>Distributed Transactions</H2> 151 152As with pooled connections, connections made via a <code>DataSource</code> 153object that is implemented to work with the middle tier infrastructure 154may participate in distributed transactions. This gives an application 155the ability to involve data sources on multiple servers in a single 156transaction. 157<P> 158The classes and interfaces used for distributed transactions are: 159<UL> 160 <LI><code>XADataSource</code> 161 <LI><code>XAConnection</code> 162</UL> 163These interfaces are used by the transaction manager; an application does 164not use them directly. 165<P> 166The <code>XAConnection</code> interface is derived from the 167<code>PooledConnection</code> interface, so what applies to a pooled connection 168also applies to a connection that is part of a distributed transaction. 169A transaction manager in the middle tier handles everything transparently. 170The only change in application code is that an application cannot do anything 171that would interfere with the transaction manager's handling of the transaction. 172Specifically, an application cannot call the methods <code>Connection.commit</code> 173or <code>Connection.rollback</code>, and it cannot set the connection to be in 174auto-commit mode (that is, it cannot call 175<code>Connection.setAutoCommit(true)</code>). 176<P> 177An application does not need to do anything special to participate in a 178distributed transaction. 179It simply creates connections to the data sources it wants to use via 180the <code>DataSource.getConnection</code> method, just as it normally does. 181The transaction manager manages the transaction behind the scenes. The 182<code>XADataSource</code> interface creates <code>XAConnection</code> objects, and 183each <code>XAConnection</code> object creates an <code>XAResource</code> object 184that the transaction manager uses to manage the connection. 185 186 187<H2>Rowsets</H2> 188The <code>RowSet</code> interface works with various other classes and 189interfaces behind the scenes. These can be grouped into three categories. 190<OL> 191<LI>Event Notification 192<UL> 193 <LI><code>RowSetListener</code><br> 194A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup> 195component because it has properties and participates in the JavaBeans 196event notification mechanism. The <code>RowSetListener</code> interface 197is implemented by a component that wants to be notified about events that 198occur to a particular <code>RowSet</code> object. Such a component registers 199itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code> 200method. 201<P> 202When the <code>RowSet</code> object changes one of its rows, changes all of 203it rows, or moves its cursor, it also notifies each listener that is registered 204with it. The listener reacts by carrying out its implementation of the 205notification method called on it. 206<P> 207 <LI><code>RowSetEvent</code><br> 208As part of its internal notification process, a <code>RowSet</code> object 209creates an instance of <code>RowSetEvent</code> and passes it to the listener. 210The listener can use this <code>RowSetEvent</code> object to find out which rowset 211had the event. 212</UL> 213<P> 214<LI>Metadata 215<UL> 216 <LI><code>RowSetMetaData</code><br> 217This interface, derived from the 218<code>ResultSetMetaData</code> interface, provides information about 219the columns in a <code>RowSet</code> object. An application can use 220<code>RowSetMetaData</code> methods to find out how many columns the 221rowset contains and what kind of data each column can contain. 222<P> 223The <code>RowSetMetaData</code> interface provides methods for 224setting the information about columns, but an application would not 225normally use these methods. When an application calls the <code>RowSet</code> 226method <code>execute</code>, the <code>RowSet</code> object will contain 227a new set of rows, and its <code>RowSetMetaData</code> object will have been 228internally updated to contain information about the new columns. 229<P> 230</UL> 231<LI>The Reader/Writer Facility<br> 232A <code>RowSet</code> object that implements the <code>RowSetInternal</code> 233interface can call on the <code>RowSetReader</code> object associated with it 234to populate itself with data. It can also call on the <code>RowSetWriter</code> 235object associated with it to write any changes to its rows back to the 236data source from which it originally got the rows. 237A rowset that remains connected to its data source does not need to use a 238reader and writer because it can simply operate on the data source directly. 239 240<UL> 241 <LI><code>RowSetInternal</code><br> 242By implementing the <code>RowSetInternal</code> interface, a 243<code>RowSet</code> object gets access to 244its internal state and is able to call on its reader and writer. A rowset 245keeps track of the values in its current rows and of the values that immediately 246preceded the current ones, referred to as the <i>original</i> values. A rowset 247also keeps track of (1) the parameters that have been set for its command and 248(2) the connection that was passed to it, if any. A rowset uses the 249<code>RowSetInternal</code> methods behind the scenes to get access to 250this information. An application does not normally invoke these methods directly. 251<P> 252 <LI><code>RowSetReader</code><br> 253A disconnected <code>RowSet</code> object that has implemented the 254<code>RowSetInternal</code> interface can call on its reader (the 255<code>RowSetReader</code> object associated with it) to populate it with 256data. When an application calls the <code>RowSet.execute</code> method, 257that method calls on the rowset's reader to do much of the work. Implementations 258can vary widely, but generally a reader makes a connection to the data source, 259reads data from the data source and populates the rowset with it, and closes 260the connection. A reader may also update the <code>RowSetMetaData</code> object 261for its rowset. The rowset's internal state is also updated, either by the 262reader or directly by the method <code>RowSet.execute</code>. 263 264 265 <LI><code>RowSetWriter</code><br> 266A disconnected <code>RowSet</code> object that has implemented the 267<code>RowSetInternal</code> interface can call on its writer (the 268<code>RowSetWriter</code> object associated with it) to write changes 269back to the underlying data source. Implementations may vary widely, but 270generally, a writer will do the following: 271 272<P> 273<UL> 274 <LI>Make a connection to the data source 275 <LI>Check to see whether there is a conflict, that is, whether 276 a value that has been changed in the rowset has also been changed 277 in the data source 278 <LI>Write the new values to the data source if there is no conflict 279 <LI>Close the connection 280</UL> 281 282 283</UL> 284</OL> 285<P> 286The <code>RowSet</code> interface may be implemented in any number of 287ways, and anyone may write an implementation. Developers are encouraged 288to use their imaginations in coming up with new ways to use rowsets. 289<P> 290<B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a 291JDBC technology driver that implements the JDBC 4.0 API. 292You must check your driver documentation to be sure that it implements 293the particular features you want to use. 294<P> 295 296<h2>Package Specification</h2> 297 298<ul> 299 <li><a href="http://java.sun.com/products/jdbc/download.html">Specification of the 300 JDBC 4.0 API</a> 301</ul> 302 303<h2>Related Documentation</h2> 304 305The Java Series book published by Addison-Wesley Longman provides detailed 306information about the classes and interfaces in the <code>javax.sql</code> 307package: 308 309<ul> 310 <li><a href="http://java.sun.com/docs/books/jdbc"><i>JDBC<sup><font size=-2>TM</font></sup> 311 API Tutorial and Reference, Third Edition:</i></a> 312</ul> 313<P> 314@since 1.4 315</body> 316</html> 317