|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|
2 <html> |
|
3 <head> |
|
4 <!-- |
|
5 Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this |
|
11 particular file as subject to the "Classpath" exception as provided |
|
12 by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
25 CA 95054 USA or visit www.sun.com if you need additional information or |
|
26 have any 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> |