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
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
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>
|
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
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
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>
|