Showing the changes to java/pkg/javax/sql/package.html (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,316 @@ | |||
| 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</sup></font>). | ||
| 41 | It remains an essential part of the Java Platform, Enterprise Edition | ||
| 42 | (Java EE<sup><font size=-2>TM</sup></font>). | ||
| 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 | <p> | ||
| 149 | |||
| 150 | <H2>Distributed Transactions</H2> | ||
| 151 | |||
| 152 | As with pooled connections, connections made via a <code>DataSource</code> | ||
| 153 | object that is implemented to work with the middle tier infrastructure | ||
| 154 | may participate in distributed transactions. This gives an application | ||
| 155 | the ability to involve data sources on multiple servers in a single | ||
| 156 | transaction. | ||
| 157 | <P> | ||
| 158 | The classes and interfaces used for distributed transactions are: | ||
| 159 | <UL> | ||
| 160 | <LI><code>XADataSource</code> | ||
| 161 | <LI><code>XAConnection</code> | ||
| 162 | </UL> | ||
| 163 | These interfaces are used by the transaction manager; an application does | ||
| 164 | not use them directly. | ||
| 165 | <P> | ||
| 166 | The <code>XAConnection</code> interface is derived from the | ||
| 167 | <code>PooledConnection</code> interface, so what applies to a pooled connection | ||
| 168 | also applies to a connection that is part of a distributed transaction. | ||
| 169 | A transaction manager in the middle tier handles everything transparently. | ||
| 170 | The only change in application code is that an application cannot do anything | ||
| 171 | that would interfere with the transaction manager's handling of the transaction. | ||
| 172 | Specifically, an application cannot call the methods <code>Connection.commit</code> | ||
| 173 | or <code>Connection.rollback</code>, and it cannot set the connection to be in | ||
| 174 | auto-commit mode (that is, it cannot call | ||
| 175 | <code>Connection.setAutoCommit(true)</code>). | ||
| 176 | <P> | ||
| 177 | An application does not need to do anything special to participate in a | ||
| 178 | distributed transaction. | ||
| 179 | It simply creates connections to the data sources it wants to use via | ||
| 180 | the <code>DataSource.getConnection</code> method, just as it normally does. | ||
| 181 | The transaction manager manages the transaction behind the scenes. The | ||
| 182 | <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and | ||
| 183 | each <code>XAConnection</code> object creates an <code>XAResource</code> object | ||
| 184 | that the transaction manager uses to manage the connection. | ||
| 185 | |||
| 186 | |||
| 187 | <H2>Rowsets</H2> | ||
| 188 | The <code>RowSet</code> interface works with various other classes and | ||
| 189 | interfaces behind the scenes. These can be grouped into three categories. | ||
| 190 | <OL> | ||
| 191 | <LI>Event Notification | ||
| 192 | <UL> | ||
| 193 | <LI><code>RowSetListener</code><br> | ||
| 194 | A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup> | ||
| 195 | component because it has properties and participates in the JavaBeans | ||
| 196 | event notification mechanism. The <code>RowSetListener</code> interface | ||
| 197 | is implemented by a component that wants to be notified about events that | ||
| 198 | occur to a particular <code>RowSet</code> object. Such a component registers | ||
| 199 | itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code> | ||
| 200 | method. | ||
| 201 | <P> | ||
| 202 | When the <code>RowSet</code> object changes one of its rows, changes all of | ||
| 203 | it rows, or moves its cursor, it also notifies each listener that is registered | ||
| 204 | with it. The listener reacts by carrying out its implementation of the | ||
| 205 | notification method called on it. | ||
| 206 | <P> | ||
| 207 | <LI><code>RowSetEvent</code><br> | ||
| 208 | As part of its internal notification process, a <code>RowSet</code> object | ||
| 209 | creates an instance of <code>RowSetEvent</code> and passes it to the listener. | ||
| 210 | The listener can use this <code>RowSetEvent</code> object to find out which rowset | ||
| 211 | had the event. | ||
| 212 | </UL> | ||
| 213 | <P> | ||
| 214 | <LI>Metadata | ||
| 215 | <UL> | ||
| 216 | <LI><code>RowSetMetaData</code><br> | ||
| 217 | This interface, derived from the | ||
| 218 | <code>ResultSetMetaData</code> interface, provides information about | ||
| 219 | the columns in a <code>RowSet</code> object. An application can use | ||
| 220 | <code>RowSetMetaData</code> methods to find out how many columns the | ||
| 221 | rowset contains and what kind of data each column can contain. | ||
| 222 | <P> | ||
| 223 | The <code>RowSetMetaData</code> interface provides methods for | ||
| 224 | setting the information about columns, but an application would not | ||
| 225 | normally use these methods. When an application calls the <code>RowSet</code> | ||
| 226 | method <code>execute</code>, the <code>RowSet</code> object will contain | ||
| 227 | a new set of rows, and its <code>RowSetMetaData</code> object will have been | ||
| 228 | internally updated to contain information about the new columns. | ||
| 229 | <P> | ||
| 230 | </UL> | ||
| 231 | <LI>The Reader/Writer Facility<br> | ||
| 232 | A <code>RowSet</code> object that implements the <code>RowSetInternal</code> | ||
| 233 | interface can call on the <code>RowSetReader</code> object associated with it | ||
| 234 | to populate itself with data. It can also call on the <code>RowSetWriter</code> | ||
| 235 | object associated with it to write any changes to its rows back to the | ||
| 236 | data source from which it originally got the rows. | ||
| 237 | A rowset that remains connected to its data source does not need to use a | ||
| 238 | reader and writer because it can simply operate on the data source directly. | ||
| 239 | |||
| 240 | <UL> | ||
| 241 | <LI><code>RowSetInternal</code><br> | ||
| 242 | By implementing the <code>RowSetInternal</code> interface, a | ||
| 243 | <code>RowSet</code> object gets access to | ||
| 244 | its internal state and is able to call on its reader and writer. A rowset | ||
| 245 | keeps track of the values in its current rows and of the values that immediately | ||
| 246 | preceded the current ones, referred to as the <i>original</i> values. A rowset | ||
| 247 | also 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 | ||
| 250 | this information. An application does not normally invoke these methods directly. | ||
| 251 | <P> | ||
| 252 | <LI><code>RowSetReader</code><br> | ||
| 253 | A 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 | ||
| 256 | data. When an application calls the <code>RowSet.execute</code> method, | ||
| 257 | that method calls on the rowset's reader to do much of the work. Implementations | ||
| 258 | can vary widely, but generally a reader makes a connection to the data source, | ||
| 259 | reads data from the data source and populates the rowset with it, and closes | ||
| 260 | the connection. A reader may also update the <code>RowSetMetaData</code> object | ||
| 261 | for its rowset. The rowset's internal state is also updated, either by the | ||
| 262 | reader or directly by the method <code>RowSet.execute</code>. | ||
| 263 | |||
| 264 | |||
| 265 | <LI><code>RowSetWriter</code><br> | ||
| 266 | A 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 | ||
| 269 | back to the underlying data source. Implementations may vary widely, but | ||
| 270 | generally, 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> | ||
| 286 | The <code>RowSet</code> interface may be implemented in any number of | ||
| 287 | ways, and anyone may write an implementation. Developers are encouraged | ||
| 288 | to 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 | ||
| 291 | JDBC technology driver that implements the JDBC 4.0 API. | ||
| 292 | You must check your driver documentation to be sure that it implements | ||
| 293 | the 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 | |||
| 305 | The Java Series book published by Addison-Wesley Longman provides detailed | ||
| 306 | information about the classes and interfaces in the <code>javax.sql</code> | ||
| 307 | package: | ||
| 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> | ||