1<!doctype html>
2<html lang="en">
3<head>
4
5  <meta http-equiv="Content-Type"
6 content="text/html; charset=iso-8859-1">
7<!--
8Copyright (c) 2003, 2017, 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>
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 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>
50
51<h3><a id="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 id="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 <code>ResultSet</code> object that makes it possible to use the result set as a
70JavaBeans&trade; component. Thus,
71a <code>JdbcRowSet</code> object can be a Bean that any tool
72makes available for assembling an application as part of a component based
73architecture. A <code>JdbcRowSet</code> 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
80<li><a href="CachedRowSet.html">
81<b><code>CachedRowSet</code>&trade;</b></a>
82 - A <code>CachedRowSet</code> object is a JavaBeans&trade;
83 component that is scrollable, updatable, serializable, and generally disconnected from
84 the source of its data. A <code>CachedRowSet</code> 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. <code>CachedRowSet</code> implementations
87<b>must</b> use the <code>SyncFactory</code> 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
96<li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A 
97<code>WebRowSet</code> object is an extension of <code>CachedRowSet</code>
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
112<li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
113<code>FilteredRowSet</code> object provides filtering functionality in a programmatic
114and extensible way. There are many instances when a <code>RowSet</code> <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
128<li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <code>JoinRowSet</code>
129interface  describes a mechanism by which relationships can be established between
130two or more standard <code>RowSet</code> implementations. Any number of <code>RowSet</code>
131 objects can be added to a <code>JoinRowSet</code> object provided  the <code>RowSet</code>objects
132can be related  in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code>
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 <code>JoinRowSet</code> object establishes relationships between
136<code>RowSet</code> instances without the need to touch the originating data source.
137</ul>
138
139<h3><a id="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
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 <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 <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> 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 <code>com.sun.rowset</code> package) use
171the <code>BaseRowSet</code> 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 class="striped" style="vertical-align:top; width:75%">
177	<caption>Features in <code>BaseRowSet</code></caption>
178          <thead>
179            <tr>
180              <th>Feature</th>
181              <th>Details</th>
182            </tr>
183          </thead>
184          <tbody>
185            <tr>
186              <td>Properties</td>
187              <td>Provides standard JavaBeans property manipulation
188mechanisms to allow applications to get and set <code>RowSet</code> command and
189property  values. Refer to the   documentation of the <code>javax.sql.RowSet</code>
190interface  (available in the JDBC 3.0 specification) for more details on
191the standard  <code>RowSet</code> properties.</td>
192            </tr>
193            <tr>
194              <td>Event notification</td>
195              <td>Provides standard JavaBeans event notifications
196to registered event listeners. Refer to the documentation of <code>javax.sql.RowSetEvent</code>
197interface (available in the JDBC 3.0 specification) for
198more details on how  to register and handle standard RowSet events generated
199by  compliant implementations.</td>
200            </tr>
201            <tr>
202              <td>Setters for a RowSet object's command</td>
203              <td>Provides a complete set of setter methods
204                 for setting RowSet command parameters.</td>
205            </tr>
206            <tr>
207              <td>Streams</td>
208              <td>Provides fields for storing of stream instances
209  in addition to providing a set of constants for stream type designation.</td>
210            </tr>
211      </tbody>
212    </table>
213    </blockquote>
214
215<li><b>3.3 Connected RowSet Requirements</b>
216<p>
217The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
218be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
219should ensure that this connection is provided solely by a JDBC driver.
220Furthermore, <code>RowSet</code> objects that are implementations of the
221<code>JdbcRowSet</code> interface and are therefore operating in a connected environment
222do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
223or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
224supply their needs by virtue of the presence of an underlying updatable and scrollable
225<code>ResultSet</code> implementation.
226
227<li>
228<b>3.4 Disconnected RowSet Requirements</b>
229<p> 
230A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object,
231<b>should</b> delegate  
232connection management to a <code>SyncProvider</code> object provided by the
233<code>SyncFactory</code>. To ensure fully disconnected semantics, all
234disconnected <code>RowSet</code> objects <b>must</b> ensure
235that the original connection made to the data source to populate the <code>RowSet</code>
236object is closed to permit the garbage collector to recover and release resources. The
237<code>SyncProvider</code> object ensures that the critical JDBC properties are
238maintained in order to re-establish a connection to the data source when a
239synchronization is required. A disconnected <code>RowSet</code> object should
240therefore ensure that no
241extraneous references remain on the <code>Connection</code> object.
242
243<li><b>3.5 Role of RowSetMetaDataImpl</b>
244<p>
245The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
246<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
247method implementations for metadata for both connected and disconnected
248<code>RowSet</code> objects. All implementations are free to use this standard
249implementation but are not required to do so.
250
251<li><b>3.6 RowSetWarning Class</b>
252<p>
253The <code>RowSetWarning</code> class provides warnings that can be set
254on <code>RowSet</code> implementations.
255Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
256<code>RowSetWarning</code>  objects are silently chained to the object whose method
257caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>
258ensure that this chaining occurs if a warning is generated and also ensure that the
259warnings are available via the <code>getRowSetWarnings</code> method defined in either
260the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface.
261After a warning has been retrieved with one of the
262<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
263<code>getNextWarning</code> can be called on it to retrieve any warnings that might
264be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
265on it, and so on until there are no more warnings.
266
267<li><b>3.7 The Joinable Interface</b>
268<P>
269The <code>Joinable</code> interface provides both connected and disconnected
270<code>RowSet</code> objects with the capability to be added to a
271<code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
272A <code>RowSet</code> object that has  implemented the <code>Joinable</code>
273interface can set a match column, retrieve a match column, or unset a match column.
274A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
275match column as a basis for adding the <code>RowSet</code> object.
276</li>
277
278<li><b>3.8 The RowSetFactory Interface</b>
279    <p>
280        A <code>RowSetFactory</code> implementation <strong>must</strong>
281        be provided.
282</li>
283</ul>
284
285<h3><a id="relspec">4.0 Related Specifications</a></h3>
286<ul>
287<li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
288<li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
289</ul>
290
291<h3><a id="reldocs">5.0 Related Documentation</a></h3>
292<ul>
293<li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/rowset.html">
294JDBC RowSet Tutorial</a>
295</ul>
296</body>
297</html>
298