1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   5   <meta http-equiv="Content-Type"
   6  content="text/html; charset=iso-8859-1">
   7 <!--
   8 Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
  11 This code is free software; you can redistribute it and/or modify it
  12 under the terms of the GNU General Public License version 2 only, as
  13 published by the Free Software Foundation.  Oracle designates this
  14 particular file as subject to the "Classpath" exception as provided
  15 by Oracle in the LICENSE file that accompanied this code.
  17 This code is distributed in the hope that it will be useful, but WITHOUT
  18 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20 version 2 for more details (a copy is included in the LICENSE file that
  21 accompanied this code).
  23 You should have received a copy of the GNU General Public License version
  24 2 along with this work; if not, write to the Free Software Foundation,
  25 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  27 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  28 or visit www.oracle.com if you need additional information or have any
  29 questions.
  31 -->
  32   <title>javax.sql.rowset Package</title>
  33 </head>
  34   <body bgcolor="#ffffff">
  36 <!-- Description clause -->
  37 Standard interfaces and base classes for JDBC <code>RowSet</code>
  38 implementations. This package contains interfaces and classes 
  39 that a standard <code>RowSet</code> implementation either implements or extends.
  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 Implementer'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>
  51 <h3><a name="pkgspec">1.0 Package Specification</a></h3>
  52 This 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
  55 specification.  It is anticipated that additional definitions
  56 of more specialized JDBC <code>RowSet</code> types will emerge as this technology 
  57 matures. Future definitions <i>should</i> be specified as subinterfaces using 
  58 inheritance 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
  61 all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
  62 developers who intend to provide their own compliant <code>RowSet</code> implementations 
  63 should pay particular attention to the assertions detailed in specification
  64 interfaces. 
  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 
  69 a <tt>ResultSet</tt> object that makes it possible to use the result set as a 
  70 JavaBeans&trade; component. Thus,
  71 a <tt>JdbcRowSet</tt> object can be a Bean that any tool
  72 makes available for assembling an application as part of a component based
  73 architecture . A <tt>JdbcRowSet</tt> object is a connected <code>RowSet</code>
  74 object, that is, it 
  75 <b>must</b> continually maintain its connection to its data source using a JDBC
  76 technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
  77 object provides a fully updatable and scrollable tabular 
  78 data structure as defined in the JDBC 3.0 specification.
  80 <li><a href="CachedRowSet.html">
  81 <b><code>CachedRowSet</code>&trade;</b></a>
  82  - A <tt>CachedRowSet</tt> object is a JavaBeans&trade;
  83  component that is scrollable, updatable, serializable, and generally disconnected from
  84  the source of its data. A <tt>CachedRowSet</tt> object
  85 typically contains rows from a result set, but it can also contain rows from any
  86 file 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
  89 disconnected <code>RowSet</code> object and the originating data source. 
  90 Typically a <code>SyncProvider</code> implementation relies upon a JDBC
  91 driver to obtain connectivity to a particular data source.
  92 Further details on this mechanism are discussed in the <a
  93 href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
  94 specification.
  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>
  98 that can read and write a <code>RowSet</code> object in a well formed XML format.
  99 This 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>
 101 interface) 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) 
 104 to 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>
 107 implementations. In order to ensure well formed XML usage, a standard generic XML
 108 Schema 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>.
 112 <li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
 113 <tt>FilteredRowSet</tt> object provides filtering functionality in a programmatic
 114 and extensible way. There are many instances when a <tt>RowSet</tt> <code>object</code>
 115 has a need to provide filtering in its contents without sacrificing the disconnected
 116 environment, thus saving the expense of having to create a connection to the data source.
 117 Solutions to this need vary from providing heavyweight full scale 
 118 SQL query abilities, to portable components, to more lightweight 
 119 approaches. A <code>FilteredRowSet</code> object consumes
 120 an implementation of the <a href="Predicate.html"><code>Predicate</code></a> 
 121 interface, 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
 123 inbound and outbound read and write operations. That is, all filters can be
 124 considered as bi-directional. No standard filters are defined;
 125 however, sufficient mechanics are specified to permit any required filter to be
 126 implemented.
 128 <li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <tt>JoinRowSet</tt>
 129 interface  describes a mechanism by which relationships can be established between 
 130 two 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 
 132 can be related  in a SQL <tt>JOIN</tt> like fashion. By definition, the SQL <tt>JOIN</tt> 
 133 statement  is used to combine the data contained in two (<i>or more</i>) relational
 134 database tables based upon a common attribute. By establishing and then enforcing
 135 column 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>
 139 <h3><a name="impl">3.0 Implementer's Guide</a></h3>
 140 Compliant implementations of JDBC <code>RowSet</code> Implementations 
 141 <b>must</b> follow the assertions described in this specification. In accordance
 142 with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
 143 Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
 144 specification. The following paragraphs outline a number of starting points for
 145 implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
 146 should also consult the <i>Implementer's Guide</i> in the <a
 147 href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
 148 on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
 150 <ul>
 151 <li><b>3.1 Constructor</b>
 152 <p>
 153     All <code>RowSet</code> implementations <strong>must</strong> provide a
 154 no-argument constructor.
 155 </li>
 156 <li><b>3.2 Role of the <code>BaseRowSet</code> Class</b>
 157 <p>
 158 A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more 
 159 standard 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>
 162 interface 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.
 166 The <tt>BaseRowSet</tt> abstract class provides any <tt>RowSet</tt> implementation
 167 with its base functionality, including property manipulation and event notification
 168 that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a> 
 169 component requirements. As an example, all implementations provided in the
 170 reference implementations (contained in the <tt>com.sun.rowset</tt> package) use
 171 the <tt>BaseRowSet</tt> class as a basis for their implementations.            
 172 <P>
 173 The following table illustrates the features that the <code>BaseRowSet</code>
 174 abstract 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
 189 property  values. Refer to the   documentation of the <tt>javax.sql.RowSet</tt>
 190 interface  (available in the JDBC 3.0 specification) for more details on
 191 the 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
 200 more  details on how  to register and handle standard RowSet events generated
 201 by  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       </tbody>
 219     </table>
 220     </blockquote>
 222 <li><b>3.3 Connected RowSet Requirements</b>
 223 <p>
 224 The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
 225 be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
 226 should ensure that this connection is provided solely by a JDBC driver. 
 227 Furthermore, <code>RowSet</code> objects that are implementations of the 
 228 <code>JdbcRowSet</code> interface and are therefore operating in a connected environment
 229 do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
 230 or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
 231 supply their needs by virtue of the presence of an underlying updatable and scrollable
 232 <code>ResultSet</code> implementation.
 234 <li>
 235 <b>3.4 Disconnected RowSet Requirements</b>
 236 <p> 
 237 A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object, 
 238 <b>should</b> delegate  
 239 connection management to a <code>SyncProvider</code> object provided by the 
 240 <code>SyncFactory</code>. To ensure fully disconnected semantics, all 
 241 disconnected <code>RowSet</code> objects <b>must</b> ensure
 242 that the original connection made to the data source to populate the <code>RowSet</code> 
 243 object is closed to permit the garbage collector to recover and release resources. The
 244 <code>SyncProvider</code> object ensures that the critical JDBC properties are 
 245 maintained in order to re-establish a connection to the data source when a 
 246 synchronization is required. A disconnected <code>RowSet</code> object should 
 247 therefore ensure that no 
 248 extraneous references remain on the <code>Connection</code> object.
 250 <li><b>3.5 Role of RowSetMetaDataImpl</b>
 251 <p>
 252 The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
 253 <a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
 254 method implementations for metadata for both connected and disconnected 
 255 <code>RowSet</code> objects. All implementations are free to use this standard
 256 implementation but are not required to do so.
 258 <li><b>3.6 RowSetWarning Class</b>
 259 <p>
 260 The <code>RowSetWarning</code> class provides warnings that can be set
 261 on <code>RowSet</code> implementations.
 262 Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
 263 <code>RowSetWarning</code>  objects are silently chained to the object whose method
 264 caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>  
 265 ensure that this chaining occurs if a warning is generated and also ensure that the
 266 warnings are available via the <code>getRowSetWarnings</code> method defined in either
 267 the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. 
 268 After a warning has been retrieved with one of the
 269 <code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
 270 <code>getNextWarning</code> can be called on it to retrieve any warnings that might
 271 be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
 272 on it, and so on until there are no more warnings.
 274 <li><b>3.7 The Joinable Interface</b>
 275 <P>
 276 The <code>Joinable</code> interface provides both connected and disconnected 
 277 <code>RowSet</code> objects with the capability to be added to a 
 278 <code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
 279 A <code>RowSet</code> object that has  implemented the <code>Joinable</code> 
 280 interface can set a match column, retrieve a match column, or unset a match column.
 281 A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
 282 match column as a basis for adding the <code>RowSet</code> object.
 283 </li>
 285 <li><b>3.8 The RowSetFactory Interface</b>
 286     <p>
 287         A <code>RowSetFactory</code> implementation <strong>must</strong>
 288         be provided.
 289 </li>
 290 </ul>
 292 <h3><a name="relspec">4.0 Related Specifications</a></h3>
 293 <ul>
 294 <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.2 Specification</a>
 295 <li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
 296 </ul>
 298 <h3><a name="reldocs">5.0 Related Documentation</a></h3>
 299 <ul>
 300 <li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/rowset.html">
 301 JDBC RowSet Tutorial</a>      
 302 </ul>
 303 </body>
 304 </html>