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 <!--
8 Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10
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.
16
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).
22
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.
26
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.
30
31 -->
32 <title>javax.sql.rowset Package</title>
33 </head>
34 <body bgcolor="#ffffff">
35
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.
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 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.
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
69 a <tt>ResultSet</tt> object that makes it possible to use the result set as a
70 JavaBeans™ 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.
79
80 <li><a href="CachedRowSet.html">
81 <b><code>CachedRowSet</code>™</b></a>
82 - A <tt>CachedRowSet</tt> object is a JavaBeans™
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.
95
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>.
111
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.
127
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>
138
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.
149
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>
221
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.
233
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.
249
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.
257
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.
273
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>
284
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>
291
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>
297
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>