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