Skip to content

D
dragonwell8_jdk

openanolis / dragonwell8_jdk

通知 4
Star 2
Fork 0
D
dragonwell8_jdk
切换分支/标签
查找文件 普通视图历史永久链接Permalink
package.html 15.3 KB
Newer Older
D
Initial load  
duke 已提交
1 2 3 4 5 6 7 
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
                                    
  <meta http-equiv="Content-Type"
 content="text/html; charset=iso-8859-1">
<!--
O
6943119: Rebrand source copyright notices  
ohair 已提交
8 
Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
D
Initial load  
duke 已提交
9 10 11 12 
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
O
6943119: Rebrand source copyright notices  
ohair 已提交
13 
published by the Free Software Foundation.  Oracle designates this
D
Initial load  
duke 已提交
14 
particular file as subject to the "Classpath" exception as provided
O
6943119: Rebrand source copyright notices  
ohair 已提交
15 
by Oracle in the LICENSE file that accompanied this code.
D
Initial load  
duke 已提交
16 17 18 19 20 21 22 23 24 25 26 

This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).

You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
O
6956202: Fix a few missed rebranding issues, please contact lines etc.  
ohair 已提交
27 28 29 
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
D
Initial load  
duke 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 

-->
  <title>javax.sql.rowset Package</title>
</head>
  <body bgcolor="#ffffff">

<!-- Description clause -->
Standard interfaces and base classes for JDBC <code>RowSet</code>
implementations. This package contains interfaces and classes 
that a standard <code>RowSet</code> implementation either implements or extends.


<h2>Table of Contents</h2>
<ul>
<li><a href="#pkgspec">1.0 Package Specification</a>
<li><a href="#stdrowset">2.0 Standard RowSet Definitions</a>
<li><a href="#impl">3.0 Implementater's Guide</a>
<li><a href="#relspec">4.0 Related Specifications</a>
<li><a href="#reldocs">5.0 Related Documentation</a>
</ul>

<h3><a name="pkgspec">1.0 Package Specification</a></h3>
This package specifies five standard JDBC <code>RowSet</code> interfaces.
 All five extend the 
<a href="../RowSet.html">RowSet</a> interface described in the JDBC 3.0
specification.  It is anticipated that additional definitions
of more specialized JDBC <code>RowSet</code> types will emerge as this technology 
matures. Future definitions <i>should</i> be specified as subinterfaces using 
inheritance similar to the way it is used in this specification.
<p>
<i>Note:</i> The interface definitions provided in this package form the basis for
all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
developers who intend to provide their own compliant <code>RowSet</code> implementations 
should pay particular attention to the assertions detailed in specification
interfaces. 

<h3><a name="stdrowset">2.0 Standard RowSet Definitions</a></h3>
<ul>
<li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around 
a <tt>ResultSet</tt> object that makes it possible to use the result set as a 
JavaBeans<sup><font size=-2>TM</font></sup> component. Thus,
a <tt>JdbcRowSet</tt> object can be a Bean that any tool
makes available for assembling an application as part of a component based
architecture . A <tt>JdbcRowSet</tt> object is a connected <code>RowSet</code>
object, that is, it 
<b>must</b> continually maintain its connection to its data source using a JDBC
technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
object provides a fully updatable and scrollable tabular 
data structure as defined in the JDBC 3.0 specification.
<p>
<li><a href="CachedRowSet.html">
<b><code>CachedRowSet</code><sup><font size=-2>TM></font></sup</b></a> 
 - A <tt>CachedRowSet</tt> object is a JavaBeans<sup><font size=-2>TM</font></sup>
 component that is scrollable, updatable, serializable, and generally disconnected from
 the source of its data. A <tt>CachedRowSet</tt> object
typically contains rows from a result set, but it can also contain rows from any
file with a tabular format, such as a spreadsheet. <tt>CachedRowSet</tt> implementations 
<b>must</b> use the <tt>SyncFactory</tt> to manage and obtain pluggable
<code>SyncProvider</code> objects to provide synchronization between the
disconnected <code>RowSet</code> object and the originating data source. 
Typically a <code>SyncProvider</code> implementation relies upon a JDBC
driver to obtain connectivity to a particular data source.
Further details on this mechanism are discussed in the <a
href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
specification.
<p>
<li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A 
<code>WebRowSet</code> object is an extension of <tt>CachedRowSet</tt>
that can read and write a <code>RowSet</code> object in a well formed XML format.
This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object 
(an extension of the <a href="../RowSetReader.html"><code>RowSetReader</code></a>
interface) to read a rowset in XML format. It calls an 
<a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the 
<a href="../RowSetWriter.html"><code>RowSetWriter</code></a> interface) 
to write a rowset in XML format. The reader and writer required by
<code>WebRowSet</code> objects are provided by the
<code>SyncFactory</code> in the form of <code>SyncProvider</code>
implementations. In order to ensure well formed XML usage, a standard generic XML
Schema is defined and published at
<a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">
<code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>.
<p>   
<li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
<tt>FilteredRowSet</tt> object provides filtering functionality in a programmatic
and extensible way. There are many instances when a <tt>RowSet</tt> <code>object</code>
has a need to provide filtering in its contents without sacrificing the disconnected
environment, thus saving the expense of having to create a connection to the data source.
Solutions to this need vary from providing heavyweight full scale 
SQL query abilities, to portable components, to more lightweight 
approaches. A <code>FilteredRowSet</code> object consumes
an implementation of the <a href="Predicate.html"><code>Predicate</code></a> 
interface, which <b>may</b> define a filter at run time. In turn, a
<code>FilteredRowSet</code> object is tasked with enforcing the set filter for both
inbound and outbound read and write operations. That is, all filters can be
considered as bi-directional. No standard filters are defined;
however, sufficient mechanics are specified to permit any required filter to be
implemented.
<p>
<li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <tt>JoinRowSet</tt>
interface  describes a mechanism by which relationships can be established between 
two or more standard <code>RowSet</code> implementations. Any number of <tt>RowSet</tt>
 objects can be added to a <tt>JoinRowSet</tt> object provided  the <tt>RowSet</tt>objects 
can be related  in a SQL <tt>JOIN</tt> like fashion. By definition, the SQL <tt>JOIN</tt> 
statement  is used to combine the data contained in two (<i>or more</i>) relational
database tables based upon a common attribute. By establishing and then enforcing
column matches, a <tt>JoinRowSet</tt> object establishes relationships between
<tt>RowSet</tt> instances without the need to touch the originating data source.     
</ul>

<h3><a name="impl">3.0 Implementer's Guide</a></h3>
Compliant implementations of JDBC <code>RowSet</code> Implementations 
<b>must</b> follow the assertions described in this specification. In accordance
with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
specification. The following paragraphs outline a number of starting points for
implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
should also consult the <i>Implementer's Guide</i> in the <a
href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
<p>
<ul>
<li><b>3.1 Role of the <code>BaseRowSet</code> Class</b>
<p>
A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more 
standard interfaces specified in this package and and <b>may</b> extend the 
<a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a 
<code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>
interface and extend the <code>BaseRowSet</code> abstract class. The
<code>BaseRowSet</code> class provides the standard architecture on which all
<code>RowSet</code> implementations should be built, regardless of whether the
<code>RowSet</code> objects exist in a connected or disconnected environment.
The <tt>BaseRowSet</tt> abstract class provides any <tt>RowSet</tt> implementation
with its base functionality, including property manipulation and event notification
that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a> 
component requirements. As an example, all implementations provided in the
reference implementations (contained in the <tt>com.sun.rowset</tt> package) use
the <tt>BaseRowSet</tt> class as a basis for their implementations.            
<P>
The following table illustrates the features that the <code>BaseRowSet</code>
abstract class provides.
  <blockquote>                    
    <table cellpadding="2" cellspacing="2" border="1" width="75%">
          <tbody>
            <tr>
              <td valign="top"><b>Feature</b><br>
              </td>
              <td valign="top"><b>Details</b><br>
              </td>
            </tr>
            <tr>
              <td valign="top">Properties<br>
              </td>
              <td valign="top">Provides standard JavaBeans property manipulation
  mechanisms to allow applications to get and set <code>RowSet</code> command and
property  values. Refer to the   documentation of the <tt>javax.sql.RowSet</tt>
interface  (available in the JDBC 3.0 specification) for more details on
the standard  <code>RowSet</code> properties.<br>
              </td>
            </tr>
            <tr>
              <td valign="top">Event notification<br>
              </td>
              <td valign="top">Provides standard JavaBeans event notifications
  to registered event listeners. Refer to the documentation of <tt>javax.sql.RowSetEvent
           </tt> interface (available in the JDBC 3.0 specification) for
more  details on how  to register and handle standard RowSet events generated
by  compliant implementations.<br>
              </td>
            </tr>
            <tr>
              <td valign="top">Setters for a RowSet object's command<br>
              </td>
              <td valign="top">Provides a complete set of setter methods
                 for setting RowSet command parameters.<br>
              </td>
            </tr>
            <tr>
              <td valign="top">Streams<br>
              </td>
              <td valign="top">Provides fields for storing of stream instances
  in addition to providing a set of constants for stream type designation.<br>
              </td>
            </tr>
                               
      </tbody>                    
    </table>
    </blockquote>
<p>
<li><b>3.2 Connected RowSet Requirements</b> 
<p>
The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
should ensure that this connection is provided solely by a JDBC driver. 
Furthermore, <code>RowSet</code> objects that are implementations of the 
<code>JdbcRowSet</code> interface and are therefore operating in a connected environment
do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
supply their needs by virtue of the presence of an underlying updatable and scrollable
<code>ResultSet</code> implementation.
<p>

<li>
<b>3.3 Disconnected RowSet Requirements</b> 
<p> 
A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object, 
<b>should</b> delegate  
connection management to a <code>SyncProvider</code> object provided by the 
<code>SyncFactory</code>. To ensure fully disconnected semantics, all 
disconnected <code>RowSet</code> objects <b>must</b> ensure
that the original connection made to the data source to populate the <code>RowSet</code> 
object is closed to permit the garbage collector to recover and release resources. The
<code>SyncProvider</code> object ensures that the critical JDBC properties are 
maintained in order to re-establish a connection to the data source when a 
synchronization is required. A disconnected <code>RowSet</code> object should 
therefore ensure that no 
extraneous references remain on the <code>Connection</code> object.
<p>
<li><b>3.4 Role of RowSetMetaDataImpl</b>
<p>
The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
method implementations for metadata for both connected and disconnected 
<code>RowSet</code> objects. All implementations are free to use this standard
implementation but are not required to do so.
<p>
<li><b>3.5 RowSetWarning Class</b>
<p>
The <code>RowSetWarning</code> class provides warnings that can be set
on <code>RowSet</code> implementations.
Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
<code>RowSetWarning</code>  objects are silently chained to the object whose method
caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>  
ensure that this chaining occurs if a warning is generated and also ensure that the
warnings are available via the <code>getRowSetWarnings</code> method defined in either
the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. 
After a warning has been retrieved with one of the
<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
<code>getNextWarning</code> can be called on it to retrieve any warnings that might
be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
on it, and so on until there are no more warnings.


<P>
<li><b>3.6 The Joinable Interface</b>
<P>
The <code>Joinable</code> interface provides both connected and disconnected 
<code>RowSet</code> objects with the capability to be added to a 
<code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
A <code>RowSet</code> object that has  implemented the <code>Joinable</code> 
interface can set a match column, retrieve a match column, or unset a match column.
A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
match column as a basis for adding the <code>RowSet</code> object. 
</ul>

<h3><a name="relspec">4.0 Related Specifications</a></h3>
<ul>
<li><a href="http://java.sun.com/products/jdbc">JDBC 3.0 Specification</a>
<li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
<li><a href="http://www.syncml.org">SyncML</a>
</ul>

<h3><a name="reldocs">5.0 Related Documentation</a></h3>
<ul>
<li><a href="http://developer.java.sun.com/developer/Books/JDBCTutorial/chapter5.html">
JDBC RowSet Tutorial</a>      
</ul>
</body>
</html>