<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"><html><head>                                      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><!--Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. This code is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 along with this work; if not, write to the Free Software Foundation,Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USAor visit www.oracle.com if you need additional information or have anyquestions. -->  <title>javax.sql.rowset Package</title></head>  <body bgcolor="#ffffff"> <!-- Description clause -->Standard interfaces and base classes for JDBC <code>RowSet</code>implementations. This package contains interfaces and classes that a standard <code>RowSet</code> implementation either implements or extends.  <h2>Table of Contents</h2><ul><li><a href="#pkgspec">1.0 Package Specification</a><li><a href="#stdrowset">2.0 Standard RowSet Definitions</a><li><a href="#impl">3.0 Implementater's Guide</a><li><a href="#relspec">4.0 Related Specifications</a><li><a href="#reldocs">5.0 Related Documentation</a></ul> <h3><a name="pkgspec">1.0 Package Specification</a></h3>This package specifies five standard JDBC <code>RowSet</code> interfaces. All five extend the <a href="../RowSet.html">RowSet</a> interface described in the JDBC 3.0specification.  It is anticipated that additional definitionsof more specialized JDBC <code>RowSet</code> types will emerge as this technology matures. Future definitions <i>should</i> be specified as subinterfaces using inheritance similar to the way it is used in this specification.<p><i>Note:</i> The interface definitions provided in this package form the basis forall compliant JDBC <code>RowSet</code> implementations. Vendors and more advanceddevelopers who intend to provide their own compliant <code>RowSet</code> implementations should pay particular attention to the assertions detailed in specificationinterfaces.  <h3><a name="stdrowset">2.0 Standard RowSet Definitions</a></h3><ul><li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around a <tt>ResultSet</tt> object that makes it possible to use the result set as a JavaBeans<sup><font size=-2>TM</font></sup> component. Thus,a <tt>JdbcRowSet</tt> object can be a Bean that any toolmakes available for assembling an application as part of a component basedarchitecture . A <tt>JdbcRowSet</tt> object is a connected <code>RowSet</code>object, that is, it <b>must</b> continually maintain its connection to its data source using a JDBCtechnology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>object provides a fully updatable and scrollable tabular data structure as defined in the JDBC 3.0 specification.<p><li><a href="CachedRowSet.html"><b><code>CachedRowSet</code>&trade;</b></a> - A <tt>CachedRowSet</tt> object is a JavaBeans<sup><font size=-2>TM</font></sup> component that is scrollable, updatable, serializable, and generally disconnected from the source of its data. A <tt>CachedRowSet</tt> objecttypically contains rows from a result set, but it can also contain rows from anyfile with a tabular format, such as a spreadsheet. <tt>CachedRowSet</tt> implementations <b>must</b> use the <tt>SyncFactory</tt> to manage and obtain pluggable<code>SyncProvider</code> objects to provide synchronization between thedisconnected <code>RowSet</code> object and the originating data source. Typically a <code>SyncProvider</code> implementation relies upon a JDBCdriver to obtain connectivity to a particular data source.Further details on this mechanism are discussed in the <ahref="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> packagespecification.<p><li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A <code>WebRowSet</code> object is an extension of <tt>CachedRowSet</tt>that can read and write a <code>RowSet</code> object in a well formed XML format.This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object (an extension of the <a href="../RowSetReader.html"><code>RowSetReader</code></a>interface) to read a rowset in XML format. It calls an <a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the <a href="../RowSetWriter.html"><code>RowSetWriter</code></a> interface) to write a rowset in XML format. The reader and writer required by<code>WebRowSet</code> objects are provided by the<code>SyncFactory</code> in the form of <code>SyncProvider</code>implementations. In order to ensure well formed XML usage, a standard generic XMLSchema is defined and published at<a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd"><code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>.<p>   <li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A<tt>FilteredRowSet</tt> object provides filtering functionality in a programmaticand extensible way. There are many instances when a <tt>RowSet</tt> <code>object</code>has a need to provide filtering in its contents without sacrificing the disconnectedenvironment, thus saving the expense of having to create a connection to the data source.Solutions to this need vary from providing heavyweight full scale SQL query abilities, to portable components, to more lightweight approaches. A <code>FilteredRowSet</code> object consumesan implementation of the <a href="Predicate.html"><code>Predicate</code></a> interface, which <b>may</b> define a filter at run time. In turn, a<code>FilteredRowSet</code> object is tasked with enforcing the set filter for bothinbound and outbound read and write operations. That is, all filters can beconsidered as bi-directional. No standard filters are defined;however, sufficient mechanics are specified to permit any required filter to beimplemented.<p><li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <tt>JoinRowSet</tt>interface  describes a mechanism by which relationships can be established between two or more standard <code>RowSet</code> implementations. Any number of <tt>RowSet</tt> objects can be added to a <tt>JoinRowSet</tt> object provided  the <tt>RowSet</tt>objects can be related  in a SQL <tt>JOIN</tt> like fashion. By definition, the SQL <tt>JOIN</tt> statement  is used to combine the data contained in two (<i>or more</i>) relationaldatabase tables based upon a common attribute. By establishing and then enforcingcolumn matches, a <tt>JoinRowSet</tt> object establishes relationships between<tt>RowSet</tt> instances without the need to touch the originating data source.     </ul> <h3><a name="impl">3.0 Implementer's Guide</a></h3>Compliant implementations of JDBC <code>RowSet</code> Implementations <b>must</b> follow the assertions described in this specification. In accordancewith the terms of the <a href="http://www.jcp.org">Java Community Process</a>, aTest Compatibility Kit (TCK) can be licensed to ensure compatibility with thespecification. The following paragraphs outline a number of starting points forimplementers of the standard JDBC <code>RowSet</code> definitions. Implementersshould also consult the <i>Implementer's Guide</i> in the <ahref="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelineson <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.<p><ul><li><b>3.1 Constructor</b><p>    All <code>RowSet</code> implementations <strong>must</strong> provide ano-argument constructor.</li><li><b>3.2 Role of the <code>BaseRowSet</code> Class</b><p>A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more standard interfaces specified in this package and and <b>may</b> extend the <a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a <code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>interface and extend the <code>BaseRowSet</code> abstract class. The<code>BaseRowSet</code> class provides the standard architecture on which all<code>RowSet</code> implementations should be built, regardless of whether the<code>RowSet</code> objects exist in a connected or disconnected environment.The <tt>BaseRowSet</tt> abstract class provides any <tt>RowSet</tt> implementationwith its base functionality, including property manipulation and event notificationthat is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a> component requirements. As an example, all implementations provided in thereference implementations (contained in the <tt>com.sun.rowset</tt> package) usethe <tt>BaseRowSet</tt> class as a basis for their implementations.            <P>The following table illustrates the features that the <code>BaseRowSet</code>abstract class provides.  <blockquote>                        <table cellpadding="2" cellspacing="2" border="1" width="75%">          <tbody>            <tr>              <td valign="top"><b>Feature</b><br>              </td>              <td valign="top"><b>Details</b><br>              </td>            </tr>            <tr>              <td valign="top">Properties<br>              </td>              <td valign="top">Provides standard JavaBeans property manipulation  mechanisms to allow applications to get and set <code>RowSet</code> command andproperty  values. Refer to the   documentation of the <tt>javax.sql.RowSet</tt>interface  (available in the JDBC 3.0 specification) for more details onthe standard  <code>RowSet</code> properties.<br>              </td>            </tr>            <tr>              <td valign="top">Event notification<br>              </td>              <td valign="top">Provides standard JavaBeans event notifications  to registered event listeners. Refer to the documentation of <tt>javax.sql.RowSetEvent           </tt> interface (available in the JDBC 3.0 specification) formore  details on how  to register and handle standard RowSet events generatedby  compliant implementations.<br>              </td>            </tr>            <tr>              <td valign="top">Setters for a RowSet object's command<br>              </td>              <td valign="top">Provides a complete set of setter methods                 for setting RowSet command parameters.<br>              </td>            </tr>            <tr>              <td valign="top">Streams<br>              </td>              <td valign="top">Provides fields for storing of stream instances  in addition to providing a set of constants for stream type designation.<br>              </td>            </tr>                                     </tbody>                        </table>    </blockquote><p><li><b>3.3 Connected RowSet Requirements</b><p>The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> alwaysbe connected to the originating data source. Implementations of the <code>JdbcRowSet</code>should ensure that this connection is provided solely by a JDBC driver. Furthermore, <code>RowSet</code> objects that are implementations of the <code>JdbcRowSet</code> interface and are therefore operating in a connected environmentdo not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> objector a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver tosupply their needs by virtue of the presence of an underlying updatable and scrollable<code>ResultSet</code> implementation.<p> <li><b>3.4 Disconnected RowSet Requirements</b><p> A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object, <b>should</b> delegate  connection management to a <code>SyncProvider</code> object provided by the <code>SyncFactory</code>. To ensure fully disconnected semantics, all disconnected <code>RowSet</code> objects <b>must</b> ensurethat the original connection made to the data source to populate the <code>RowSet</code> object is closed to permit the garbage collector to recover and release resources. The<code>SyncProvider</code> object ensures that the critical JDBC properties are maintained in order to re-establish a connection to the data source when a synchronization is required. A disconnected <code>RowSet</code> object should therefore ensure that no extraneous references remain on the <code>Connection</code> object.<p><li><b>3.5 Role of RowSetMetaDataImpl</b><p>The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard settermethod implementations for metadata for both connected and disconnected <code>RowSet</code> objects. All implementations are free to use this standardimplementation but are not required to do so.<p><li><b>3.6 RowSetWarning Class</b><p>The <code>RowSetWarning</code> class provides warnings that can be seton <code>RowSet</code> implementations.Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,<code>RowSetWarning</code>  objects are silently chained to the object whose methodcaused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>  ensure that this chaining occurs if a warning is generated and also ensure that thewarnings are available via the <code>getRowSetWarnings</code> method defined in eitherthe <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. After a warning has been retrieved with one of the<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method<code>getNextWarning</code> can be called on it to retrieve any warnings that mightbe chained on it.  If a warning is returned, <code>getNextWarning</code> can be calledon it, and so on until there are no more warnings.  <P><li><b>3.7 The Joinable Interface</b><P>The <code>Joinable</code> interface provides both connected and disconnected <code>RowSet</code> objects with the capability to be added to a <code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.A <code>RowSet</code> object that has  implemented the <code>Joinable</code> interface can set a match column, retrieve a match column, or unset a match column.A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object'smatch column as a basis for adding the <code>RowSet</code> object.</li> <li><b>3.8 The RowSetFactory Interface</b>    <p>        A <code>RowSetFactory</code> implementation <strong>must</strong>        be provided.</li></ul> <h3><a name="relspec">4.0 Related Specifications</a></h3><ul><li><a href="http://java.sun.com/products/jdbc">JDBC 3.0 Specification</a><li><a href="http://www.w3.org/XML/Schema">XML Schema</a><li><a href="http://www.syncml.org">SyncML</a></ul> <h3><a name="reldocs">5.0 Related Documentation</a></h3><ul><li><a href="http://java.sun.com/developer/Books/JDBCTutorial/chapter5.html">JDBC RowSet Tutorial</a>      </ul></body></html>