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, 2014, 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 <code>ResultSet</code> object that makes it possible to use the result set as a 70 JavaBeans™ component. Thus, 71 a <code>JdbcRowSet</code> object can be a Bean that any tool 72 makes available for assembling an application as part of a component based 73 architecture. A <code>JdbcRowSet</code> 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 <code>CachedRowSet</code> object is a JavaBeans™ 83 component that is scrollable, updatable, serializable, and generally disconnected from 84 the source of its data. A <code>CachedRowSet</code> 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. <code>CachedRowSet</code> implementations 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 <code>JoinRowSet</code> 129 interface describes a mechanism by which relationships can be established between 130 two 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 132 can be related in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code> 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 <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 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 <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 <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> 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 <code>com.sun.rowset</code> package) use 171 the <code>BaseRowSet</code> 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 <code>javax.sql.RowSet</code> 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 <code>javax.sql.RowSetEvent</code> 199 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> 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> | 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 <!-- 8 Copyright (c) 2003, 2014, 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> 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 id="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 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 69 a <code>ResultSet</code> object that makes it possible to use the result set as a 70 JavaBeans™ component. Thus, 71 a <code>JdbcRowSet</code> object can be a Bean that any tool 72 makes available for assembling an application as part of a component based 73 architecture. A <code>JdbcRowSet</code> 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 <code>CachedRowSet</code> object is a JavaBeans™ 83 component that is scrollable, updatable, serializable, and generally disconnected from 84 the source of its data. A <code>CachedRowSet</code> 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. <code>CachedRowSet</code> implementations 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 <code>JoinRowSet</code> 129 interface describes a mechanism by which relationships can be established between 130 two 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 132 can be related in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code> 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 <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> 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 <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 <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> 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 <code>com.sun.rowset</code> package) use 171 the <code>BaseRowSet</code> 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 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 188 mechanisms to allow applications to get and set <code>RowSet</code> command and 189 property values. Refer to the documentation of the <code>javax.sql.RowSet</code> 190 interface (available in the JDBC 3.0 specification) for more details on 191 the standard <code>RowSet</code> properties.</td> 192 </tr> 193 <tr> 194 <td>Event notification</td> 195 <td>Provides standard JavaBeans event notifications 196 to registered event listeners. Refer to the documentation of <code>javax.sql.RowSetEvent</code> 197 interface (available in the JDBC 3.0 specification) for 198 more details on how to register and handle standard RowSet events generated 199 by 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> 217 The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always 218 be connected to the originating data source. Implementations of the <code>JdbcRowSet</code> 219 should ensure that this connection is provided solely by a JDBC driver. 220 Furthermore, <code>RowSet</code> objects that are implementations of the 221 <code>JdbcRowSet</code> interface and are therefore operating in a connected environment 222 do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object 223 or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to 224 supply 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> 265 on it, and so on until there are no more warnings. 266 267 <li><b>3.7 The Joinable Interface</b> 268 <P> 269 The <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. 272 A <code>RowSet</code> object that has implemented the <code>Joinable</code> 273 interface can set a match column, retrieve a match column, or unset a match column. 274 A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's 275 match 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.2 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"> 294 JDBC RowSet Tutorial</a> 295 </ul> 296 </body> 297 </html> |