1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5 Copyright (c) 2000, 2006, 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<sup><font size=-2>TM</font></sup> 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
  40 (Java SE<sup><font size=-2>TM</font></sup>).
  41 It remains an essential part of the Java Platform, Enterprise Edition
  42 (Java EE<sup><font size=-2>TM</font></sup>).
  43 <P>
  44 The <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>
  54 Applications use the <code>DataSource</code> and <code>RowSet</code>
  55 APIs directly, but the connection pooling and distributed transaction
  56 APIs are used internally by the middle-tier infrastructure.
  57 
  58 <H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
  59 
  60 The <code>javax.sql</code> package provides the preferred
  61 way to make a connection with a data source.  The <code>DriverManager</code>
  62 class, the original mechanism, is still valid, and code using it will
  63 continue to run.  However, the newer <code>DataSource</code> mechanism
  64 is preferred because it offers many advantages over the 
  65 <code>DriverManager</code> mechanism.
  66 <P>
  67 These are the main advantages of using a <code>DataSource</code> object to 
  68 make 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>
  82 Driver vendors provide <code>DataSource</code> implementations. A
  83 particular <code>DataSource</code> object represents a particular
  84 physical data source, and each connection the <code>DataSource</code> object
  85 creates is a connection to that physical data source. 
  86 <P>
  87 A logical name for the data source is registered with a naming service that
  88 uses 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 
  90 duties of a system administrator. An application can retrieve the
  91 <code>DataSource</code> object it wants by doing a lookup on the logical
  92 name 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
  94 source it represents.
  95 <P>
  96 A <code>DataSource</code> object can be implemented to work with the 
  97 middle tier infrastructure so that the connections it produces will be
  98 pooled for reuse. An application that uses such a <code>DataSource</code> 
  99 implementation will automatically get a connection that participates in
 100 connection pooling.  
 101 A <code>DataSource</code> object can also be implemented to work with the 
 102 middle tier infrastructure so that the connections it produces can be
 103 used for distributed transactions without any special coding.
 104 
 105 <H2>Connection Pooling and Statement Pooling</H2>
 106 
 107 Connections made via a <code>DataSource</code>
 108 object that is implemented to work with a middle tier connection pool manager
 109 will participate in connection pooling.  This can improve performance
 110 dramatically because creating new connections is very expensive. 
 111 Connection pooling allows a connection to be used and reused, 
 112 thus cutting down substantially on the number of new connections 
 113 that need to be created.
 114 <P>
 115 Connection pooling is totally transparent.  It is done automatically
 116 in the middle tier of a Java EE configuration, so from an application's 
 117 viewpoint, no change in code is required. An application simply uses
 118 the <code>DataSource.getConnection</code> method to get the pooled
 119 connection and uses it the same way it uses any <code>Connection</code>
 120 object.
 121 <P>
 122 The 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>
 131 The connection pool manager, a facility in the middle tier of
 132 a three-tier architecture, uses these classes and interfaces
 133 behind the scenes.  When a <code>ConnectionPoolDataSource</code> object
 134 is called on to create a <code>PooledConnection</code> object, the
 135 connection pool manager will register as a <code>ConnectionEventListener</code>
 136 object with the new <code>PooledConnection</code> object.  When the connection
 137 is closed or there is an error, the connection pool manager (being a listener)
 138 gets a notification that includes a <code>ConnectionEvent</code> object.
 139 <p>
 140 If 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
 143 connection pool manager will register as a <code>StatementEventListener</code>
 144 object with the new <code>PooledConnection</code> object.  When the 
 145 <code>PreparedStatement</code> is closed or there is an error, the connection 
 146 pool manager (being a listener)
 147 gets a notification that includes a <code>StatementEvent</code> object.
 148 
 149 <H2>Distributed Transactions</H2>
 150 
 151 As with pooled connections, connections made via a <code>DataSource</code>
 152 object that is implemented to work with the middle tier infrastructure
 153 may participate in distributed transactions.  This gives an application
 154 the ability to involve data sources on multiple servers in a single
 155 transaction.
 156 <P>
 157 The classes and interfaces used for distributed transactions are:
 158 <UL>
 159   <LI><code>XADataSource</code>
 160   <LI><code>XAConnection</code>
 161 </UL>
 162 These interfaces are used by the transaction manager; an application does
 163 not use them directly.
 164 <P>
 165 The <code>XAConnection</code> interface is derived from the
 166 <code>PooledConnection</code> interface, so what applies to a pooled connection
 167 also applies to a connection that is part of a distributed transaction.  
 168 A transaction manager in the middle tier handles everything transparently.
 169 The only change in application code is that an application cannot do anything
 170 that would interfere with the transaction manager's handling of the transaction.
 171 Specifically, an application cannot call the methods <code>Connection.commit</code> 
 172 or <code>Connection.rollback</code>, and it cannot set the connection to be in 
 173 auto-commit mode (that is, it cannot call 
 174 <code>Connection.setAutoCommit(true)</code>).  
 175 <P>
 176 An application does not need to do anything special to participate in a
 177 distributed transaction.
 178 It simply creates connections to the data sources it wants to use via
 179 the <code>DataSource.getConnection</code> method, just as it normally does.
 180 The transaction manager manages the transaction behind the scenes.  The
 181 <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
 182 each <code>XAConnection</code> object creates an <code>XAResource</code> object 
 183 that the transaction manager uses to manage the connection.
 184 
 185 
 186 <H2>Rowsets</H2>
 187 The <code>RowSet</code> interface works with various other classes and
 188 interfaces behind the scenes. These can be grouped into three categories.
 189 <OL>
 190 <LI>Event Notification 
 191 <UL>
 192   <LI><code>RowSetListener</code><br>
 193 A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>
 194 component because it has properties and participates in the JavaBeans
 195 event notification mechanism. The <code>RowSetListener</code> interface 
 196 is implemented by a component that wants to be notified about events that 
 197 occur to a particular <code>RowSet</code> object.  Such a component registers
 198 itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
 199 method.
 200 <P>
 201 When the <code>RowSet</code> object changes one of its rows, changes all of
 202 it rows, or moves its cursor, it also notifies each listener that is registered 
 203 with it.  The listener reacts by carrying out its implementation of the 
 204 notification method called on it.
 205   <LI><code>RowSetEvent</code><br>
 206 As part of its internal notification process, a <code>RowSet</code> object
 207 creates an instance of <code>RowSetEvent</code> and passes it to the listener.
 208 The listener can use this <code>RowSetEvent</code> object to find out which rowset
 209 had the event.
 210 </UL>
 211 <LI>Metadata 
 212 <UL>
 213   <LI><code>RowSetMetaData</code><br>
 214 This interface, derived from the
 215 <code>ResultSetMetaData</code> interface, provides information about
 216 the columns in a <code>RowSet</code> object.  An application can use
 217 <code>RowSetMetaData</code> methods to find out how many columns the
 218 rowset contains and what kind of data each column can contain.
 219 <P>
 220 The <code>RowSetMetaData</code> interface provides methods for
 221 setting the information about columns, but an application would not
 222 normally use these methods.  When an application calls the <code>RowSet</code> 
 223 method <code>execute</code>, the <code>RowSet</code> object will contain
 224 a new set of rows, and its <code>RowSetMetaData</code> object will have been
 225 internally updated to contain information about the new columns.
 226 </UL>
 227 <LI>The Reader/Writer Facility<br>
 228 A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
 229 interface can call on the <code>RowSetReader</code> object associated with it
 230 to populate itself with data.  It can also call on the <code>RowSetWriter</code>
 231 object associated with it to write any changes to its rows back to the
 232 data source from which it originally got the rows.
 233 A rowset that remains connected to its data source does not need to use a 
 234 reader and writer because it can simply operate on the data source directly.
 235 
 236 <UL>
 237   <LI><code>RowSetInternal</code><br>
 238 By implementing the <code>RowSetInternal</code> interface, a 
 239 <code>RowSet</code> object gets access to
 240 its internal state and is able to call on its reader and writer. A rowset
 241 keeps track of the values in its current rows and of the values that immediately
 242 preceded the current ones, referred to as the <i>original</i> values.  A rowset
 243 also keeps track of (1) the parameters that have been set for its command and 
 244 (2) the connection that was passed to it, if any.  A rowset uses the 
 245 <code>RowSetInternal</code> methods behind the scenes to get access to
 246 this information.  An application does not normally invoke these methods directly.
 247 
 248   <LI><code>RowSetReader</code><br>
 249 A disconnected <code>RowSet</code> object that has implemented the 
 250 <code>RowSetInternal</code> interface can call on its reader (the 
 251 <code>RowSetReader</code> object associated with it) to populate it with 
 252 data.  When an application calls the <code>RowSet.execute</code> method, 
 253 that method calls on the rowset's reader to do much of the work. Implementations
 254 can vary widely, but generally a reader makes a connection to the data source,
 255 reads data from the data source and populates the rowset with it, and closes
 256 the connection. A reader may also update the <code>RowSetMetaData</code> object
 257 for its rowset.  The rowset's internal state is also updated, either by the
 258 reader or directly by the method <code>RowSet.execute</code>.
 259 
 260 
 261   <LI><code>RowSetWriter</code><br>
 262 A disconnected <code>RowSet</code> object that has implemented the 
 263 <code>RowSetInternal</code> interface can call on its writer (the 
 264 <code>RowSetWriter</code> object associated with it) to write changes
 265 back to the underlying data source.  Implementations may vary widely, but
 266 generally, a writer will do the following:
 267 
 268 <UL>
 269   <LI>Make a connection to the data source 
 270   <LI>Check to see whether there is a conflict, that is, whether
 271       a value that has been changed in the rowset has also been changed 
 272       in the data source
 273   <LI>Write the new values to the data source if there is no conflict 
 274   <LI>Close the connection
 275 </UL>
 276  
 277 
 278 </UL>
 279 </OL>
 280 <P>
 281 The <code>RowSet</code> interface may be implemented in any number of
 282 ways, and anyone may write an implementation. Developers are encouraged 
 283 to use their imaginations in coming up with new ways to use rowsets.
 284 <P>
 285 <B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a 
 286 JDBC technology driver that implements the JDBC 4.0 API.
 287 You must check your driver documentation to be sure that it implements
 288 the particular features you want to use.
 289 
 290 <h2>Package Specification</h2>
 291 
 292 <ul>
 293   <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.2 Specification</a>
 294 </ul>
 295 
 296 <h2>Related Documentation</h2>
 297 
 298 The Java Series book published by Addison-Wesley Longman provides detailed
 299 information about the classes and interfaces in the <code>javax.sql</code>
 300 package: 
 301 
 302 <ul>
 303   <li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
 304           <i>JDBC™API Tutorial and Reference, Third Edition</i></a>
 305 </ul>
 306 </body>
 307 </html>