|
2
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<!--
|
|
5506
|
5 |
Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
|
|
2
|
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
|
|
5506
|
10 |
published by the Free Software Foundation. Oracle designates this
|
|
2
|
11 |
particular file as subject to the "Classpath" exception as provided
|
|
5506
|
12 |
by Oracle in the LICENSE file that accompanied this code.
|
|
2
|
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>
|