src/share/classes/javax/sql/rowset/package.html

Print this page




  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&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.
  79 <p>
  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.
  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>
  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 <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
 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 <p>
 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 <p>
 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


 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                                
 219       </tbody>                    
 220     </table>
 221     </blockquote>
 222 <p>
 223 <li><b>3.3 Connected RowSet Requirements</b>
 224 <p>
 225 The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
 226 be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
 227 should ensure that this connection is provided solely by a JDBC driver. 
 228 Furthermore, <code>RowSet</code> objects that are implementations of the 
 229 <code>JdbcRowSet</code> interface and are therefore operating in a connected environment
 230 do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
 231 or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
 232 supply 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> 
 239 A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object, 
 240 <b>should</b> delegate  
 241 connection management to a <code>SyncProvider</code> object provided by the 
 242 <code>SyncFactory</code>. To ensure fully disconnected semantics, all 
 243 disconnected <code>RowSet</code> objects <b>must</b> ensure
 244 that the original connection made to the data source to populate the <code>RowSet</code> 
 245 object 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 
 247 maintained in order to re-establish a connection to the data source when a 
 248 synchronization is required. A disconnected <code>RowSet</code> object should 
 249 therefore ensure that no 
 250 extraneous references remain on the <code>Connection</code> object.
 251 <p>
 252 <li><b>3.5 Role of RowSetMetaDataImpl</b>
 253 <p>
 254 The <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
 256 method implementations for metadata for both connected and disconnected 
 257 <code>RowSet</code> objects. All implementations are free to use this standard
 258 implementation but are not required to do so.
 259 <p>
 260 <li><b>3.6 RowSetWarning Class</b>
 261 <p>
 262 The <code>RowSetWarning</code> class provides warnings that can be set
 263 on <code>RowSet</code> implementations.
 264 Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
 265 <code>RowSetWarning</code>  objects are silently chained to the object whose method
 266 caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>  
 267 ensure that this chaining occurs if a warning is generated and also ensure that the
 268 warnings are available via the <code>getRowSetWarnings</code> method defined in either
 269 the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. 
 270 After 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
 273 be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
 274 on 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>
 280 The <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.
 283 A <code>RowSet</code> object that has  implemented the <code>Joinable</code> 
 284 interface can set a match column, retrieve a match column, or unset a match column.
 285 A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
 286 match 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>


  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&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.
  79 
  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.
  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


 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>