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 (Java SE™).
40 It remains an essential part of the Java Platform, Enterprise Edition
41 (Java EE™).
42 <P>
43 The <code>javax.sql</code> package provides for the following:
44 <OL>
45 <LI>The <code>DataSource</code> interface as an alternative to the
46 <code>DriverManager</code> for establishing a
47 connection with a data source
48 <LI>Connection pooling and Statement pooling
49 <LI>Distributed transactions
50 <LI>Rowsets
51 </OL>
52 <P>
53 Applications use the <code>DataSource</code> and <code>RowSet</code>
54 APIs directly, but the connection pooling and distributed transaction
55 APIs are used internally by the middle-tier infrastructure.
56
67 make a connection:
68 <UL>
69
70 <LI>Changes can be made to a data source's properties, which means
71 that it is not necessary to make changes in application code when
72 something about the data source or driver changes.
73 <LI>Connection and Statement pooling and distributed transactions are available
74 through a <code>DataSource</code> object that is
75 implemented to work with the middle-tier infrastructure.
76 Connections made through the <code>DriverManager</code>
77 do not have connection and statement pooling or distributed transaction
78 capabilities.
79 </UL>
80 <P>
81 Driver vendors provide <code>DataSource</code> implementations. A
82 particular <code>DataSource</code> object represents a particular
83 physical data source, and each connection the <code>DataSource</code> object
84 creates is a connection to that physical data source.
85 <P>
86 A logical name for the data source is registered with a naming service that
87 uses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>
88 (JNDI) API, usually by a system administrator or someone performing the
89 duties of a system administrator. An application can retrieve the
90 <code>DataSource</code> object it wants by doing a lookup on the logical
91 name that has been registered for it. The application can then use the
92 <code>DataSource</code> object to create a connection to the physical data
93 source it represents.
94 <P>
95 A <code>DataSource</code> object can be implemented to work with the
96 middle tier infrastructure so that the connections it produces will be
97 pooled for reuse. An application that uses such a <code>DataSource</code>
98 implementation will automatically get a connection that participates in
99 connection pooling.
100 A <code>DataSource</code> object can also be implemented to work with the
101 middle tier infrastructure so that the connections it produces can be
102 used for distributed transactions without any special coding.
103
104 <H2>Connection Pooling and Statement Pooling</H2>
105
106 Connections made via a <code>DataSource</code>
107 object that is implemented to work with a middle tier connection pool manager
172 auto-commit mode (that is, it cannot call
173 <code>Connection.setAutoCommit(true)</code>).
174 <P>
175 An application does not need to do anything special to participate in a
176 distributed transaction.
177 It simply creates connections to the data sources it wants to use via
178 the <code>DataSource.getConnection</code> method, just as it normally does.
179 The transaction manager manages the transaction behind the scenes. The
180 <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
181 each <code>XAConnection</code> object creates an <code>XAResource</code> object
182 that the transaction manager uses to manage the connection.
183
184
185 <H2>Rowsets</H2>
186 The <code>RowSet</code> interface works with various other classes and
187 interfaces behind the scenes. These can be grouped into three categories.
188 <OL>
189 <LI>Event Notification
190 <UL>
191 <LI><code>RowSetListener</code><br>
192 A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>
193 component because it has properties and participates in the JavaBeans
194 event notification mechanism. The <code>RowSetListener</code> interface
195 is implemented by a component that wants to be notified about events that
196 occur to a particular <code>RowSet</code> object. Such a component registers
197 itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
198 method.
199 <P>
200 When the <code>RowSet</code> object changes one of its rows, changes all of
201 it rows, or moves its cursor, it also notifies each listener that is registered
202 with it. The listener reacts by carrying out its implementation of the
203 notification method called on it.
204 <LI><code>RowSetEvent</code><br>
205 As part of its internal notification process, a <code>RowSet</code> object
206 creates an instance of <code>RowSetEvent</code> and passes it to the listener.
207 The listener can use this <code>RowSetEvent</code> object to find out which rowset
208 had the event.
209 </UL>
210 <LI>Metadata
211 <UL>
212 <LI><code>RowSetMetaData</code><br>
|
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™ 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 (Java SE™).
40 It remains an essential part of the Java Platform, Enterprise Edition
41 (Java EE™).
42 <P>
43 The <code>javax.sql</code> package provides for the following:
44 <OL>
45 <LI>The <code>DataSource</code> interface as an alternative to the
46 <code>DriverManager</code> for establishing a
47 connection with a data source
48 <LI>Connection pooling and Statement pooling
49 <LI>Distributed transactions
50 <LI>Rowsets
51 </OL>
52 <P>
53 Applications use the <code>DataSource</code> and <code>RowSet</code>
54 APIs directly, but the connection pooling and distributed transaction
55 APIs are used internally by the middle-tier infrastructure.
56
67 make a connection:
68 <UL>
69
70 <LI>Changes can be made to a data source's properties, which means
71 that it is not necessary to make changes in application code when
72 something about the data source or driver changes.
73 <LI>Connection and Statement pooling and distributed transactions are available
74 through a <code>DataSource</code> object that is
75 implemented to work with the middle-tier infrastructure.
76 Connections made through the <code>DriverManager</code>
77 do not have connection and statement pooling or distributed transaction
78 capabilities.
79 </UL>
80 <P>
81 Driver vendors provide <code>DataSource</code> implementations. A
82 particular <code>DataSource</code> object represents a particular
83 physical data source, and each connection the <code>DataSource</code> object
84 creates is a connection to that physical data source.
85 <P>
86 A logical name for the data source is registered with a naming service that
87 uses the Java Naming and Directory Interface™
88 (JNDI) API, usually by a system administrator or someone performing the
89 duties of a system administrator. An application can retrieve the
90 <code>DataSource</code> object it wants by doing a lookup on the logical
91 name that has been registered for it. The application can then use the
92 <code>DataSource</code> object to create a connection to the physical data
93 source it represents.
94 <P>
95 A <code>DataSource</code> object can be implemented to work with the
96 middle tier infrastructure so that the connections it produces will be
97 pooled for reuse. An application that uses such a <code>DataSource</code>
98 implementation will automatically get a connection that participates in
99 connection pooling.
100 A <code>DataSource</code> object can also be implemented to work with the
101 middle tier infrastructure so that the connections it produces can be
102 used for distributed transactions without any special coding.
103
104 <H2>Connection Pooling and Statement Pooling</H2>
105
106 Connections made via a <code>DataSource</code>
107 object that is implemented to work with a middle tier connection pool manager
172 auto-commit mode (that is, it cannot call
173 <code>Connection.setAutoCommit(true)</code>).
174 <P>
175 An application does not need to do anything special to participate in a
176 distributed transaction.
177 It simply creates connections to the data sources it wants to use via
178 the <code>DataSource.getConnection</code> method, just as it normally does.
179 The transaction manager manages the transaction behind the scenes. The
180 <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
181 each <code>XAConnection</code> object creates an <code>XAResource</code> object
182 that the transaction manager uses to manage the connection.
183
184
185 <H2>Rowsets</H2>
186 The <code>RowSet</code> interface works with various other classes and
187 interfaces behind the scenes. These can be grouped into three categories.
188 <OL>
189 <LI>Event Notification
190 <UL>
191 <LI><code>RowSetListener</code><br>
192 A <code>RowSet</code> object is a JavaBeans™
193 component because it has properties and participates in the JavaBeans
194 event notification mechanism. The <code>RowSetListener</code> interface
195 is implemented by a component that wants to be notified about events that
196 occur to a particular <code>RowSet</code> object. Such a component registers
197 itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
198 method.
199 <P>
200 When the <code>RowSet</code> object changes one of its rows, changes all of
201 it rows, or moves its cursor, it also notifies each listener that is registered
202 with it. The listener reacts by carrying out its implementation of the
203 notification method called on it.
204 <LI><code>RowSetEvent</code><br>
205 As part of its internal notification process, a <code>RowSet</code> object
206 creates an instance of <code>RowSetEvent</code> and passes it to the listener.
207 The listener can use this <code>RowSetEvent</code> object to find out which rowset
208 had the event.
209 </UL>
210 <LI>Metadata
211 <UL>
212 <LI><code>RowSetMetaData</code><br>
|