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