0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<html>
0N/A<head>
0N/A<!--
2362N/ACopyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
0N/AThis code is free software; you can redistribute it and/or modify it
0N/Aunder the terms of the GNU General Public License version 2 only, as
2362N/Apublished by the Free Software Foundation. Oracle designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
2362N/Aby Oracle in the LICENSE file that accompanied this code.
0N/A
0N/AThis code is distributed in the hope that it will be useful, but WITHOUT
0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/Aversion 2 for more details (a copy is included in the LICENSE file that
0N/Aaccompanied this code).
0N/A
0N/AYou should have received a copy of the GNU General Public License version
0N/A2 along with this work; if not, write to the Free Software Foundation,
0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A-->
0N/A
0N/A</head>
0N/A
0N/A
0N/A
0N/A<body bgcolor="white">
0N/A
0N/AProvides the API for server side data source access and processing from
0N/Athe Java<sup><font size=-2>TM</font></sup> programming language.
0N/AThis package supplements the <code>java.sql</code>
0N/Apackage and, as of the version 1.4 release, is included in the
0N/AJava Platform, Standard Edition
0N/A(Java SE<sup><font size=-2>TM</sup></font>).
0N/AIt remains an essential part of the Java Platform, Enterprise Edition
0N/A(Java EE<sup><font size=-2>TM</sup></font>).
0N/A<P>
0N/AThe <code>javax.sql</code> package provides for the following:
0N/A<OL>
0N/A <LI>The <code>DataSource</code> interface as an alternative to the
0N/A <code>DriverManager</code> for establishing a
0N/A connection with a data source
0N/A <LI>Connection pooling and Statement pooling
0N/A <LI>Distributed transactions
0N/A <LI>Rowsets
0N/A</OL>
0N/A<P>
0N/AApplications use the <code>DataSource</code> and <code>RowSet</code>
0N/AAPIs directly, but the connection pooling and distributed transaction
0N/AAPIs are used internally by the middle-tier infrastructure.
0N/A
0N/A<H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
0N/A
0N/AThe <code>javax.sql</code> package provides the preferred
0N/Away to make a connection with a data source. The <code>DriverManager</code>
0N/Aclass, the original mechanism, is still valid, and code using it will
0N/Acontinue to run. However, the newer <code>DataSource</code> mechanism
0N/Ais preferred because it offers many advantages over the
0N/A<code>DriverManager</code> mechanism.
0N/A<P>
0N/AThese are the main advantages of using a <code>DataSource</code> object to
0N/Amake a connection:
0N/A<UL>
0N/A
0N/A <LI>Changes can be made to a data source's properties, which means
0N/A that it is not necessary to make changes in application code when
0N/A something about the data source or driver changes.
0N/A <LI>Connection and Statement pooling and distributed transactions are available
0N/A through a <code>DataSource</code> object that is
0N/A implemented to work with the middle-tier infrastructure.
0N/A Connections made through the <code>DriverManager</code>
0N/A do not have connection and statement pooling or distributed transaction
0N/A capabilities.
0N/A</UL>
0N/A<P>
0N/ADriver vendors provide <code>DataSource</code> implementations. A
0N/Aparticular <code>DataSource</code> object represents a particular
0N/Aphysical data source, and each connection the <code>DataSource</code> object
0N/Acreates is a connection to that physical data source.
0N/A<P>
0N/AA logical name for the data source is registered with a naming service that
0N/Auses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>
0N/A(JNDI) API, usually by a system administrator or someone performing the
0N/Aduties of a system administrator. An application can retrieve the
0N/A<code>DataSource</code> object it wants by doing a lookup on the logical
0N/Aname that has been registered for it. The application can then use the
0N/A<code>DataSource</code> object to create a connection to the physical data
0N/Asource it represents.
0N/A<P>
0N/AA <code>DataSource</code> object can be implemented to work with the
0N/Amiddle tier infrastructure so that the connections it produces will be
0N/Apooled for reuse. An application that uses such a <code>DataSource</code>
0N/Aimplementation will automatically get a connection that participates in
0N/Aconnection pooling.
0N/AA <code>DataSource</code> object can also be implemented to work with the
0N/Amiddle tier infrastructure so that the connections it produces can be
0N/Aused for distributed transactions without any special coding.
0N/A
0N/A<H2>Connection Pooling and Statement Pooling</H2>
0N/A
0N/AConnections made via a <code>DataSource</code>
0N/Aobject that is implemented to work with a middle tier connection pool manager
0N/Awill participate in connection pooling. This can improve performance
0N/Adramatically because creating new connections is very expensive.
0N/AConnection pooling allows a connection to be used and reused,
0N/Athus cutting down substantially on the number of new connections
0N/Athat need to be created.
0N/A<P>
0N/AConnection pooling is totally transparent. It is done automatically
0N/Ain the middle tier of a Java EE configuration, so from an application's
0N/Aviewpoint, no change in code is required. An application simply uses
0N/Athe <code>DataSource.getConnection</code> method to get the pooled
0N/Aconnection and uses it the same way it uses any <code>Connection</code>
0N/Aobject.
0N/A<P>
0N/AThe classes and interfaces used for connection pooling are:
0N/A<UL>
0N/A <LI><code>ConnectionPoolDataSource</code>
0N/A <LI><code>PooledConnection</code>
0N/A <LI><code>ConnectionEvent</code>
0N/A <LI><code>ConnectionEventListener</code>
0N/A <LI><code>StatementEvent</code>
0N/A <LI><code>StatementEventListener</code>
0N/A</UL>
0N/AThe connection pool manager, a facility in the middle tier of
0N/Aa three-tier architecture, uses these classes and interfaces
0N/Abehind the scenes. When a <code>ConnectionPoolDataSource</code> object
0N/Ais called on to create a <code>PooledConnection</code> object, the
0N/Aconnection pool manager will register as a <code>ConnectionEventListener</code>
0N/Aobject with the new <code>PooledConnection</code> object. When the connection
0N/Ais closed or there is an error, the connection pool manager (being a listener)
0N/Agets a notification that includes a <code>ConnectionEvent</code> object.
0N/A<p>
0N/AIf the connection pool manager supports <code>Statement</code> pooling, for
0N/A<code>PreparedStatements</code>, which can be determined by invoking the method
0N/A<code>DatabaseMetaData.supportsStatementPooling</code>, the
0N/Aconnection pool manager will register as a <code>StatementEventListener</code>
0N/Aobject with the new <code>PooledConnection</code> object. When the
0N/A<code>PreparedStatement</code> is closed or there is an error, the connection
0N/Apool manager (being a listener)
0N/Agets a notification that includes a <code>StatementEvent</code> object.
0N/A<p>
0N/A
0N/A<H2>Distributed Transactions</H2>
0N/A
0N/AAs with pooled connections, connections made via a <code>DataSource</code>
0N/Aobject that is implemented to work with the middle tier infrastructure
0N/Amay participate in distributed transactions. This gives an application
0N/Athe ability to involve data sources on multiple servers in a single
0N/Atransaction.
0N/A<P>
0N/AThe classes and interfaces used for distributed transactions are:
0N/A<UL>
0N/A <LI><code>XADataSource</code>
0N/A <LI><code>XAConnection</code>
0N/A</UL>
0N/AThese interfaces are used by the transaction manager; an application does
0N/Anot use them directly.
0N/A<P>
0N/AThe <code>XAConnection</code> interface is derived from the
0N/A<code>PooledConnection</code> interface, so what applies to a pooled connection
0N/Aalso applies to a connection that is part of a distributed transaction.
0N/AA transaction manager in the middle tier handles everything transparently.
0N/AThe only change in application code is that an application cannot do anything
0N/Athat would interfere with the transaction manager's handling of the transaction.
0N/ASpecifically, an application cannot call the methods <code>Connection.commit</code>
0N/Aor <code>Connection.rollback</code>, and it cannot set the connection to be in
0N/Aauto-commit mode (that is, it cannot call
0N/A<code>Connection.setAutoCommit(true)</code>).
0N/A<P>
0N/AAn application does not need to do anything special to participate in a
0N/Adistributed transaction.
0N/AIt simply creates connections to the data sources it wants to use via
0N/Athe <code>DataSource.getConnection</code> method, just as it normally does.
0N/AThe transaction manager manages the transaction behind the scenes. The
0N/A<code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
0N/Aeach <code>XAConnection</code> object creates an <code>XAResource</code> object
0N/Athat the transaction manager uses to manage the connection.
0N/A
0N/A
0N/A<H2>Rowsets</H2>
0N/AThe <code>RowSet</code> interface works with various other classes and
0N/Ainterfaces behind the scenes. These can be grouped into three categories.
0N/A<OL>
0N/A<LI>Event Notification
0N/A<UL>
0N/A <LI><code>RowSetListener</code><br>
0N/AA <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>
0N/Acomponent because it has properties and participates in the JavaBeans
0N/Aevent notification mechanism. The <code>RowSetListener</code> interface
0N/Ais implemented by a component that wants to be notified about events that
0N/Aoccur to a particular <code>RowSet</code> object. Such a component registers
0N/Aitself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
0N/Amethod.
0N/A<P>
0N/AWhen the <code>RowSet</code> object changes one of its rows, changes all of
0N/Ait rows, or moves its cursor, it also notifies each listener that is registered
0N/Awith it. The listener reacts by carrying out its implementation of the
0N/Anotification method called on it.
0N/A<P>
0N/A <LI><code>RowSetEvent</code><br>
0N/AAs part of its internal notification process, a <code>RowSet</code> object
0N/Acreates an instance of <code>RowSetEvent</code> and passes it to the listener.
0N/AThe listener can use this <code>RowSetEvent</code> object to find out which rowset
0N/Ahad the event.
0N/A</UL>
0N/A<P>
0N/A<LI>Metadata
0N/A<UL>
0N/A <LI><code>RowSetMetaData</code><br>
0N/AThis interface, derived from the
0N/A<code>ResultSetMetaData</code> interface, provides information about
0N/Athe columns in a <code>RowSet</code> object. An application can use
0N/A<code>RowSetMetaData</code> methods to find out how many columns the
0N/Arowset contains and what kind of data each column can contain.
0N/A<P>
0N/AThe <code>RowSetMetaData</code> interface provides methods for
0N/Asetting the information about columns, but an application would not
0N/Anormally use these methods. When an application calls the <code>RowSet</code>
0N/Amethod <code>execute</code>, the <code>RowSet</code> object will contain
0N/Aa new set of rows, and its <code>RowSetMetaData</code> object will have been
0N/Ainternally updated to contain information about the new columns.
0N/A<P>
0N/A</UL>
0N/A<LI>The Reader/Writer Facility<br>
0N/AA <code>RowSet</code> object that implements the <code>RowSetInternal</code>
0N/Ainterface can call on the <code>RowSetReader</code> object associated with it
0N/Ato populate itself with data. It can also call on the <code>RowSetWriter</code>
0N/Aobject associated with it to write any changes to its rows back to the
0N/Adata source from which it originally got the rows.
0N/AA rowset that remains connected to its data source does not need to use a
0N/Areader and writer because it can simply operate on the data source directly.
0N/A
0N/A<UL>
0N/A <LI><code>RowSetInternal</code><br>
0N/ABy implementing the <code>RowSetInternal</code> interface, a
0N/A<code>RowSet</code> object gets access to
0N/Aits internal state and is able to call on its reader and writer. A rowset
0N/Akeeps track of the values in its current rows and of the values that immediately
0N/Apreceded the current ones, referred to as the <i>original</i> values. A rowset
0N/Aalso keeps track of (1) the parameters that have been set for its command and
0N/A(2) the connection that was passed to it, if any. A rowset uses the
0N/A<code>RowSetInternal</code> methods behind the scenes to get access to
0N/Athis information. An application does not normally invoke these methods directly.
0N/A<P>
0N/A <LI><code>RowSetReader</code><br>
0N/AA disconnected <code>RowSet</code> object that has implemented the
0N/A<code>RowSetInternal</code> interface can call on its reader (the
0N/A<code>RowSetReader</code> object associated with it) to populate it with
0N/Adata. When an application calls the <code>RowSet.execute</code> method,
0N/Athat method calls on the rowset's reader to do much of the work. Implementations
0N/Acan vary widely, but generally a reader makes a connection to the data source,
0N/Areads data from the data source and populates the rowset with it, and closes
0N/Athe connection. A reader may also update the <code>RowSetMetaData</code> object
0N/Afor its rowset. The rowset's internal state is also updated, either by the
0N/Areader or directly by the method <code>RowSet.execute</code>.
0N/A
0N/A
0N/A <LI><code>RowSetWriter</code><br>
0N/AA disconnected <code>RowSet</code> object that has implemented the
0N/A<code>RowSetInternal</code> interface can call on its writer (the
0N/A<code>RowSetWriter</code> object associated with it) to write changes
0N/Aback to the underlying data source. Implementations may vary widely, but
0N/Agenerally, a writer will do the following:
0N/A
0N/A<P>
0N/A<UL>
0N/A <LI>Make a connection to the data source
0N/A <LI>Check to see whether there is a conflict, that is, whether
0N/A a value that has been changed in the rowset has also been changed
0N/A in the data source
0N/A <LI>Write the new values to the data source if there is no conflict
0N/A <LI>Close the connection
0N/A</UL>
0N/A
0N/A
0N/A</UL>
0N/A</OL>
0N/A<P>
0N/AThe <code>RowSet</code> interface may be implemented in any number of
0N/Aways, and anyone may write an implementation. Developers are encouraged
0N/Ato use their imaginations in coming up with new ways to use rowsets.
0N/A<P>
0N/A<B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a
0N/AJDBC technology driver that implements the JDBC 4.0 API.
0N/AYou must check your driver documentation to be sure that it implements
0N/Athe particular features you want to use.
0N/A<P>
0N/A
0N/A<h2>Package Specification</h2>
0N/A
0N/A<ul>
0N/A <li><a href="http://java.sun.com/products/jdbc/download.html">Specification of the
0N/A JDBC 4.0 API</a>
0N/A</ul>
0N/A
0N/A<h2>Related Documentation</h2>
0N/A
0N/AThe Java Series book published by Addison-Wesley Longman provides detailed
0N/Ainformation about the classes and interfaces in the <code>javax.sql</code>
0N/Apackage:
0N/A
0N/A<ul>
0N/A <li><a href="http://java.sun.com/docs/books/jdbc"><i>JDBC<sup><font size=-2>TM</font></sup>
0N/A API Tutorial and Reference, Third Edition:</i></a>
0N/A</ul>
0N/A<P>
0N/A@since 1.4
0N/A</body>
0N/A</html>