1 /**
2 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
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 *
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 *
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 *
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}
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} package provides for the following:
36 * <OL>
37 * <LI>The {@code DataSource} interface as an alternative to the
38 * {@code DriverManager} 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} and {@code RowSet}
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} Object to Make a Connection</H2>
50 * <p>
51 * The {@code javax.sql} package provides the preferred
52 * way to make a connection with a data source. The {@code DriverManager}
53 * class, the original mechanism, is still valid, and code using it will
54 * continue to run. However, the newer {@code DataSource} mechanism
55 * is preferred because it offers many advantages over the
56 * {@code DriverManager} mechanism.
57 * <p>
58 * These are the main advantages of using a {@code DataSource} 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} object that is
67 * implemented to work with the middle-tier infrastructure.
68 * Connections made through the {@code DriverManager}
69 * do not have connection and statement pooling or distributed transaction
70 * capabilities.
71 * </UL>
72 * <p>
73 * Driver vendors provide {@code DataSource} implementations. A
74 * particular {@code DataSource} object represents a particular
75 * physical data source, and each connection the {@code DataSource} 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} 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} object to create a connection to the physical data
85 * source it represents.
86 * <p>
87 * A {@code DataSource} 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}
90 * implementation will automatically get a connection that participates in
91 * connection pooling.
92 * A {@code DataSource} 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}
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} method to get the pooled
110 * connection and uses it the same way it uses any {@code Connection}
111 * object.
112 * <p>
113 * The classes and interfaces used for connection pooling are:
114 * <UL>
115 * <LI>{@code ConnectionPoolDataSource}
116 * <LI>{@code PooledConnection}
117 * <LI>{@code ConnectionEvent}
118 * <LI>{@code ConnectionEventListener}
119 * <LI>{@code StatementEvent}
120 * <LI>{@code StatementEventListener}
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} object
125 * is called on to create a {@code PooledConnection} object, the
126 * connection pool manager will register as a {@code ConnectionEventListener}
127 * object with the new {@code PooledConnection} 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} object.
130 * <p>
131 * If the connection pool manager supports {@code Statement} pooling, for
132 * {@code PreparedStatements}, which can be determined by invoking the method
133 * {@code DatabaseMetaData.supportsStatementPooling}, the
134 * connection pool manager will register as a {@code StatementEventListener}
135 * object with the new {@code PooledConnection} object. When the
136 * {@code PreparedStatement} is closed or there is an error, the connection
137 * pool manager (being a listener)
138 * gets a notification that includes a {@code StatementEvent} object.
139 *
140 * <H2>Distributed Transactions</H2>
141 * <p>
142 * As with pooled connections, connections made via a {@code DataSource}
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}
151 * <LI>{@code XAConnection}
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} interface is derived from the
157 * {@code PooledConnection} 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}
163 * or {@code Connection.rollback}, and it cannot set the connection to be in
164 * auto-commit mode (that is, it cannot call
165 * {@code Connection.setAutoCommit(true)}).
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} method, just as it normally does.
171 * The transaction manager manages the transaction behind the scenes. The
172 * {@code XADataSource} interface creates {@code XAConnection} objects, and
173 * each {@code XAConnection} object creates an {@code XAResource} object
174 * that the transaction manager uses to manage the connection.
175 *
176 *
177 * <H2>Rowsets</H2>
178 * The {@code RowSet} 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}<br>
184 * A {@code RowSet} object is a JavaBeans
185 * component because it has properties and participates in the JavaBeans
186 * event notification mechanism. The {@code RowSetListener} interface
187 * is implemented by a component that wants to be notified about events that
188 * occur to a particular {@code RowSet} object. Such a component registers
189 * itself as a listener with a rowset via the {@code RowSet.addRowSetListener}
190 * method.
191 * <p>
192 * When the {@code RowSet} 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}<br>
197 * As part of its internal notification process, a {@code RowSet} object
198 * creates an instance of {@code RowSetEvent} and passes it to the listener.
199 * The listener can use this {@code RowSetEvent} object to find out which rowset
200 * had the event.
201 * </UL>
202 * <LI>Metadata
203 * <UL>
204 * <LI>{@code RowSetMetaData}<br>
205 * This interface, derived from the
206 * {@code ResultSetMetaData} interface, provides information about
207 * the columns in a {@code RowSet} object. An application can use
208 * {@code RowSetMetaData} 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} 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}
214 * method {@code execute}, the {@code RowSet} object will contain
215 * a new set of rows, and its {@code RowSetMetaData} 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} object that implements the {@code RowSetInternal}
220 * interface can call on the {@code RowSetReader} object associated with it
221 * to populate itself with data. It can also call on the {@code RowSetWriter}
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}<br>
229 * By implementing the {@code RowSetInternal} interface, a
230 * {@code RowSet} 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} 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}<br>
240 * A disconnected {@code RowSet} object that has implemented the
241 * {@code RowSetInternal} interface can call on its reader (the
242 * {@code RowSetReader} object associated with it) to populate it with
243 * data. When an application calls the {@code RowSet.execute} 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} 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}.
250 *
251 *
252 * <LI>{@code RowSetWriter}<br>
253 * A disconnected {@code RowSet} object that has implemented the
254 * {@code RowSetInternal} interface can call on its writer (the
255 * {@code RowSetWriter} 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} 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}
287 * package:
288 *
289 * <ul>
290 * <li>“<i>JDBC™API Tutorial and Reference, Third Edition</i>”
291 * </ul>
292 */
293 package javax.sql;