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