1<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> 2<html> 3<head> 4 5 <meta http-equiv="Content-Type" 6 content="text/html; charset=iso-8859-1"> 7<!-- 8Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. 9DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 10 11This code is free software; you can redistribute it and/or modify it 12under the terms of the GNU General Public License version 2 only, as 13published by the Free Software Foundation. Oracle designates this 14particular file as subject to the "Classpath" exception as provided 15by Oracle in the LICENSE file that accompanied this code. 16 17This code is distributed in the hope that it will be useful, but WITHOUT 18ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 19FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 20version 2 for more details (a copy is included in the LICENSE file that 21accompanied this code). 22 23You should have received a copy of the GNU General Public License version 242 along with this work; if not, write to the Free Software Foundation, 25Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 26 27Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 28or visit www.oracle.com if you need additional information or have any 29questions. 30 31--> 32 <title>javax.sql.rowset Package</title> 33</head> 34 <body bgcolor="#ffffff"> 35 36<!-- Description clause --> 37Standard interfaces and base classes for JDBC <code>RowSet</code> 38implementations. This package contains interfaces and classes 39that a standard <code>RowSet</code> implementation either implements or extends. 40 41 42<h2>Table of Contents</h2> 43<ul> 44<li><a href="#pkgspec">1.0 Package Specification</a> 45<li><a href="#stdrowset">2.0 Standard RowSet Definitions</a> 46<li><a href="#impl">3.0 Implementater's Guide</a> 47<li><a href="#relspec">4.0 Related Specifications</a> 48<li><a href="#reldocs">5.0 Related Documentation</a> 49</ul> 50 51<h3><a name="pkgspec">1.0 Package Specification</a></h3> 52This package specifies five standard JDBC <code>RowSet</code> interfaces. 53 All five extend the 54<a href="../RowSet.html">RowSet</a> interface described in the JDBC 3.0 55specification. It is anticipated that additional definitions 56of more specialized JDBC <code>RowSet</code> types will emerge as this technology 57matures. Future definitions <i>should</i> be specified as subinterfaces using 58inheritance similar to the way it is used in this specification. 59<p> 60<i>Note:</i> The interface definitions provided in this package form the basis for 61all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced 62developers who intend to provide their own compliant <code>RowSet</code> implementations 63should pay particular attention to the assertions detailed in specification 64interfaces. 65 66<h3><a name="stdrowset">2.0 Standard RowSet Definitions</a></h3> 67<ul> 68<li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around 69a <tt>ResultSet</tt> object that makes it possible to use the result set as a 70JavaBeans<sup><font size=-2>TM</font></sup> component. Thus, 71a <tt>JdbcRowSet</tt> object can be a Bean that any tool 72makes available for assembling an application as part of a component based 73architecture . A <tt>JdbcRowSet</tt> object is a connected <code>RowSet</code> 74object, that is, it 75<b>must</b> continually maintain its connection to its data source using a JDBC 76technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code> 77object provides a fully updatable and scrollable tabular 78data structure as defined in the JDBC 3.0 specification. 79<p> 80<li><a href="CachedRowSet.html"> 81<b><code>CachedRowSet</code>™</b></a> 82 - A <tt>CachedRowSet</tt> object is a JavaBeans<sup><font size=-2>TM</font></sup> 83 component that is scrollable, updatable, serializable, and generally disconnected from 84 the source of its data. A <tt>CachedRowSet</tt> object 85typically contains rows from a result set, but it can also contain rows from any 86file with a tabular format, such as a spreadsheet. <tt>CachedRowSet</tt> implementations 87<b>must</b> use the <tt>SyncFactory</tt> to manage and obtain pluggable 88<code>SyncProvider</code> objects to provide synchronization between the 89disconnected <code>RowSet</code> object and the originating data source. 90Typically a <code>SyncProvider</code> implementation relies upon a JDBC 91driver to obtain connectivity to a particular data source. 92Further details on this mechanism are discussed in the <a 93href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package 94specification. 95<p> 96<li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A 97<code>WebRowSet</code> object is an extension of <tt>CachedRowSet</tt> 98that can read and write a <code>RowSet</code> object in a well formed XML format. 99This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object 100(an extension of the <a href="../RowSetReader.html"><code>RowSetReader</code></a> 101interface) to read a rowset in XML format. It calls an 102<a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the 103<a href="../RowSetWriter.html"><code>RowSetWriter</code></a> interface) 104to write a rowset in XML format. The reader and writer required by 105<code>WebRowSet</code> objects are provided by the 106<code>SyncFactory</code> in the form of <code>SyncProvider</code> 107implementations. In order to ensure well formed XML usage, a standard generic XML 108Schema is defined and published at 109<a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd"> 110<code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>. 111<p> 112<li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A 113<tt>FilteredRowSet</tt> object provides filtering functionality in a programmatic 114and extensible way. There are many instances when a <tt>RowSet</tt> <code>object</code> 115has a need to provide filtering in its contents without sacrificing the disconnected 116environment, thus saving the expense of having to create a connection to the data source. 117Solutions to this need vary from providing heavyweight full scale 118SQL query abilities, to portable components, to more lightweight 119approaches. A <code>FilteredRowSet</code> object consumes 120an implementation of the <a href="Predicate.html"><code>Predicate</code></a> 121interface, which <b>may</b> define a filter at run time. In turn, a 122<code>FilteredRowSet</code> object is tasked with enforcing the set filter for both 123inbound and outbound read and write operations. That is, all filters can be 124considered as bi-directional. No standard filters are defined; 125however, sufficient mechanics are specified to permit any required filter to be 126implemented. 127<p> 128<li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <tt>JoinRowSet</tt> 129interface describes a mechanism by which relationships can be established between 130two or more standard <code>RowSet</code> implementations. Any number of <tt>RowSet</tt> 131 objects can be added to a <tt>JoinRowSet</tt> object provided the <tt>RowSet</tt>objects 132can be related in a SQL <tt>JOIN</tt> like fashion. By definition, the SQL <tt>JOIN</tt> 133statement is used to combine the data contained in two (<i>or more</i>) relational 134database tables based upon a common attribute. By establishing and then enforcing 135column matches, a <tt>JoinRowSet</tt> object establishes relationships between 136<tt>RowSet</tt> instances without the need to touch the originating data source. 137</ul> 138 139<h3><a name="impl">3.0 Implementer's Guide</a></h3> 140Compliant implementations of JDBC <code>RowSet</code> Implementations 141<b>must</b> follow the assertions described in this specification. In accordance 142with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a 143Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the 144specification. The following paragraphs outline a number of starting points for 145implementers of the standard JDBC <code>RowSet</code> definitions. Implementers 146should also consult the <i>Implementer's Guide</i> in the <a 147href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines 148on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations. 149<p> 150<ul> 151<li><b>3.1 Constructor</b> 152<p> 153 All <code>RowSet</code> implementations <strong>must</strong> provide a 154no-argument constructor. 155</li> 156<li><b>3.2 Role of the <code>BaseRowSet</code> Class</b> 157<p> 158A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more 159standard interfaces specified in this package and and <b>may</b> extend the 160<a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a 161<code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code> 162interface and extend the <code>BaseRowSet</code> abstract class. The 163<code>BaseRowSet</code> class provides the standard architecture on which all 164<code>RowSet</code> implementations should be built, regardless of whether the 165<code>RowSet</code> objects exist in a connected or disconnected environment. 166The <tt>BaseRowSet</tt> abstract class provides any <tt>RowSet</tt> implementation 167with its base functionality, including property manipulation and event notification 168that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a> 169component requirements. As an example, all implementations provided in the 170reference implementations (contained in the <tt>com.sun.rowset</tt> package) use 171the <tt>BaseRowSet</tt> class as a basis for their implementations. 172<P> 173The following table illustrates the features that the <code>BaseRowSet</code> 174abstract class provides. 175 <blockquote> 176 <table cellpadding="2" cellspacing="2" border="1" width="75%"> 177 <tbody> 178 <tr> 179 <td valign="top"><b>Feature</b><br> 180 </td> 181 <td valign="top"><b>Details</b><br> 182 </td> 183 </tr> 184 <tr> 185 <td valign="top">Properties<br> 186 </td> 187 <td valign="top">Provides standard JavaBeans property manipulation 188 mechanisms to allow applications to get and set <code>RowSet</code> command and 189property values. Refer to the documentation of the <tt>javax.sql.RowSet</tt> 190interface (available in the JDBC 3.0 specification) for more details on 191the standard <code>RowSet</code> properties.<br> 192 </td> 193 </tr> 194 <tr> 195 <td valign="top">Event notification<br> 196 </td> 197 <td valign="top">Provides standard JavaBeans event notifications 198 to registered event listeners. Refer to the documentation of <tt>javax.sql.RowSetEvent 199 </tt> interface (available in the JDBC 3.0 specification) for 200more details on how to register and handle standard RowSet events generated 201by compliant implementations.<br> 202 </td> 203 </tr> 204 <tr> 205 <td valign="top">Setters for a RowSet object's command<br> 206 </td> 207 <td valign="top">Provides a complete set of setter methods 208 for setting RowSet command parameters.<br> 209 </td> 210 </tr> 211 <tr> 212 <td valign="top">Streams<br> 213 </td> 214 <td valign="top">Provides fields for storing of stream instances 215 in addition to providing a set of constants for stream type designation.<br> 216 </td> 217 </tr> 218 219 </tbody> 220 </table> 221 </blockquote> 222<p> 223<li><b>3.3 Connected RowSet Requirements</b> 224<p> 225The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always 226be connected to the originating data source. Implementations of the <code>JdbcRowSet</code> 227should ensure that this connection is provided solely by a JDBC driver. 228Furthermore, <code>RowSet</code> objects that are implementations of the 229<code>JdbcRowSet</code> interface and are therefore operating in a connected environment 230do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object 231or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to 232supply their needs by virtue of the presence of an underlying updatable and scrollable 233<code>ResultSet</code> implementation. 234<p> 235 236<li> 237<b>3.4 Disconnected RowSet Requirements</b> 238<p> 239A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object, 240<b>should</b> delegate 241connection management to a <code>SyncProvider</code> object provided by the 242<code>SyncFactory</code>. To ensure fully disconnected semantics, all 243disconnected <code>RowSet</code> objects <b>must</b> ensure 244that the original connection made to the data source to populate the <code>RowSet</code> 245object is closed to permit the garbage collector to recover and release resources. The 246<code>SyncProvider</code> object ensures that the critical JDBC properties are 247maintained in order to re-establish a connection to the data source when a 248synchronization is required. A disconnected <code>RowSet</code> object should 249therefore ensure that no 250extraneous references remain on the <code>Connection</code> object. 251<p> 252<li><b>3.5 Role of RowSetMetaDataImpl</b> 253<p> 254The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the 255<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter 256method implementations for metadata for both connected and disconnected 257<code>RowSet</code> objects. All implementations are free to use this standard 258implementation but are not required to do so. 259<p> 260<li><b>3.6 RowSetWarning Class</b> 261<p> 262The <code>RowSetWarning</code> class provides warnings that can be set 263on <code>RowSet</code> implementations. 264Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects, 265<code>RowSetWarning</code> objects are silently chained to the object whose method 266caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b> 267ensure that this chaining occurs if a warning is generated and also ensure that the 268warnings are available via the <code>getRowSetWarnings</code> method defined in either 269the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. 270After a warning has been retrieved with one of the 271<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method 272<code>getNextWarning</code> can be called on it to retrieve any warnings that might 273be chained on it. If a warning is returned, <code>getNextWarning</code> can be called 274on it, and so on until there are no more warnings. 275 276 277<P> 278<li><b>3.7 The Joinable Interface</b> 279<P> 280The <code>Joinable</code> interface provides both connected and disconnected 281<code>RowSet</code> objects with the capability to be added to a 282<code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation. 283A <code>RowSet</code> object that has implemented the <code>Joinable</code> 284interface can set a match column, retrieve a match column, or unset a match column. 285A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's 286match column as a basis for adding the <code>RowSet</code> object. 287</li> 288 289<li><b>3.8 The RowSetFactory Interface</b> 290 <p> 291 A <code>RowSetFactory</code> implementation <strong>must</strong> 292 be provided. 293</li> 294</ul> 295 296<h3><a name="relspec">4.0 Related Specifications</a></h3> 297<ul> 298<li><a href="http://java.sun.com/products/jdbc">JDBC 3.0 Specification</a> 299<li><a href="http://www.w3.org/XML/Schema">XML Schema</a> 300<li><a href="http://www.syncml.org">SyncML</a> 301</ul> 302 303<h3><a name="reldocs">5.0 Related Documentation</a></h3> 304<ul> 305<li><a href="http://java.sun.com/developer/Books/JDBCTutorial/chapter5.html"> 306JDBC RowSet Tutorial</a> 307</ul> 308</body> 309</html> 310