< prev index next >

src/java.sql/share/classes/javax/sql/package-info.java

Print this page
rev 52981 : 8215309: Convert package.html files to package-info.java files
Reviewed-by:
   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5 Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
   6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   7 
   8 This code is free software; you can redistribute it and/or modify it
   9 under the terms of the GNU General Public License version 2 only, as
  10 published by the Free Software Foundation.  Oracle designates this
  11 particular file as subject to the "Classpath" exception as provided
  12 by Oracle in the LICENSE file that accompanied this code.
  13 
  14 This code is distributed in the hope that it will be useful, but WITHOUT
  15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17 version 2 for more details (a copy is included in the LICENSE file that
  18 accompanied this code).
  19 
  20 You should have received a copy of the GNU General Public License version
  21 2 along with this work; if not, write to the Free Software Foundation,
  22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  23 
  24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  25 or visit www.oracle.com if you need additional information or have any
  26 questions.
  27 -->
  28 
  29 </head>
  30 
  31 
  32 
  33 <body bgcolor="white">
  34 
  35 Provides the API for server side data source access and processing from
  36 the Java&trade; programming language.
  37 This package supplements the <code>java.sql</code>
  38 package and, as of the version 1.4 release, is included in the 
  39 Java Platform, Standard Edition (Java SE&trade;).
  40 It remains an essential part of the Java Platform, Enterprise Edition
  41 (Java EE&trade;).
  42 <P>
  43 The <code>javax.sql</code> package provides for the following:
  44 <OL>
  45   <LI>The <code>DataSource</code> interface as an alternative to the 
  46       <code>DriverManager</code> for establishing a 
  47       connection with a data source
  48   <LI>Connection pooling and Statement pooling
  49   <LI>Distributed transactions
  50   <LI>Rowsets
  51 </OL>
  52 <P>
  53 Applications use the <code>DataSource</code> and <code>RowSet</code>
  54 APIs directly, but the connection pooling and distributed transaction
  55 APIs are used internally by the middle-tier infrastructure.
  56 
  57 <H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
  58 
  59 The <code>javax.sql</code> package provides the preferred
  60 way to make a connection with a data source.  The <code>DriverManager</code>
  61 class, the original mechanism, is still valid, and code using it will
  62 continue to run.  However, the newer <code>DataSource</code> mechanism
  63 is preferred because it offers many advantages over the 
  64 <code>DriverManager</code> mechanism.
  65 <P>
  66 These are the main advantages of using a <code>DataSource</code> object to 
  67 make a connection:
  68 <UL>
  69   
  70   <LI>Changes can be made to a data source's properties, which means
  71       that it is not necessary to make changes in application code when
  72       something about the data source or driver changes.
  73   <LI>Connection  and Statement pooling and distributed transactions are available
  74       through a <code>DataSource</code> object that is
  75       implemented to work with the middle-tier infrastructure.
  76       Connections made through the <code>DriverManager</code>
  77       do not have connection and statement pooling or distributed transaction
  78       capabilities.
  79 </UL>
  80 <P>
  81 Driver vendors provide <code>DataSource</code> implementations. A
  82 particular <code>DataSource</code> object represents a particular
  83 physical data source, and each connection the <code>DataSource</code> object
  84 creates is a connection to that physical data source. 
  85 <P>
  86 A logical name for the data source is registered with a naming service that
  87 uses the Java Naming and Directory Interface&trade;
  88 (JNDI) API, usually by a system administrator or someone performing the 
  89 duties of a system administrator. An application can retrieve the
  90 <code>DataSource</code> object it wants by doing a lookup on the logical
  91 name that has been registered for it.  The application can then use the 
  92 <code>DataSource</code> object to create a connection to the physical data
  93 source it represents.
  94 <P>
  95 A <code>DataSource</code> object can be implemented to work with the 
  96 middle tier infrastructure so that the connections it produces will be
  97 pooled for reuse. An application that uses such a <code>DataSource</code> 
  98 implementation will automatically get a connection that participates in
  99 connection pooling.  
 100 A <code>DataSource</code> object can also be implemented to work with the 
 101 middle tier infrastructure so that the connections it produces can be
 102 used for distributed transactions without any special coding.
 103 
 104 <H2>Connection Pooling and Statement Pooling</H2>
 105 
 106 Connections made via a <code>DataSource</code>
 107 object that is implemented to work with a middle tier connection pool manager
 108 will participate in connection pooling.  This can improve performance
 109 dramatically because creating new connections is very expensive. 
 110 Connection pooling allows a connection to be used and reused, 
 111 thus cutting down substantially on the number of new connections 
 112 that need to be created.
 113 <P>
 114 Connection pooling is totally transparent.  It is done automatically
 115 in the middle tier of a Java EE configuration, so from an application's 
 116 viewpoint, no change in code is required. An application simply uses
 117 the <code>DataSource.getConnection</code> method to get the pooled
 118 connection and uses it the same way it uses any <code>Connection</code>
 119 object.
 120 <P>
 121 The classes and interfaces used for connection pooling are:
 122 <UL>
 123   <LI><code>ConnectionPoolDataSource</code>
 124   <LI><code>PooledConnection</code>
 125   <LI><code>ConnectionEvent</code>
 126   <LI><code>ConnectionEventListener</code>
 127    <LI><code>StatementEvent</code>
 128   <LI><code>StatementEventListener</code>
 129 </UL>
 130 The connection pool manager, a facility in the middle tier of
 131 a three-tier architecture, uses these classes and interfaces
 132 behind the scenes.  When a <code>ConnectionPoolDataSource</code> object
 133 is called on to create a <code>PooledConnection</code> object, the
 134 connection pool manager will register as a <code>ConnectionEventListener</code>
 135 object with the new <code>PooledConnection</code> object.  When the connection
 136 is closed or there is an error, the connection pool manager (being a listener)
 137 gets a notification that includes a <code>ConnectionEvent</code> object.
 138 <p>
 139 If the connection pool manager supports <code>Statement</code> pooling, for
 140 <code>PreparedStatements</code>, which can be determined by invoking the method 
 141 <code>DatabaseMetaData.supportsStatementPooling</code>,  the
 142 connection pool manager will register as a <code>StatementEventListener</code>
 143 object with the new <code>PooledConnection</code> object.  When the 
 144 <code>PreparedStatement</code> is closed or there is an error, the connection 
 145 pool manager (being a listener)
 146 gets a notification that includes a <code>StatementEvent</code> object.
 147 
 148 <H2>Distributed Transactions</H2>
 149 
 150 As with pooled connections, connections made via a <code>DataSource</code>
 151 object that is implemented to work with the middle tier infrastructure
 152 may participate in distributed transactions.  This gives an application
 153 the ability to involve data sources on multiple servers in a single
 154 transaction.
 155 <P>
 156 The classes and interfaces used for distributed transactions are:
 157 <UL>
 158   <LI><code>XADataSource</code>
 159   <LI><code>XAConnection</code>
 160 </UL>
 161 These interfaces are used by the transaction manager; an application does
 162 not use them directly.
 163 <P>
 164 The <code>XAConnection</code> interface is derived from the
 165 <code>PooledConnection</code> interface, so what applies to a pooled connection
 166 also applies to a connection that is part of a distributed transaction.  
 167 A transaction manager in the middle tier handles everything transparently.
 168 The only change in application code is that an application cannot do anything
 169 that would interfere with the transaction manager's handling of the transaction.
 170 Specifically, an application cannot call the methods <code>Connection.commit</code> 
 171 or <code>Connection.rollback</code>, and it cannot set the connection to be in 
 172 auto-commit mode (that is, it cannot call 
 173 <code>Connection.setAutoCommit(true)</code>).  
 174 <P>
 175 An application does not need to do anything special to participate in a
 176 distributed transaction.
 177 It simply creates connections to the data sources it wants to use via
 178 the <code>DataSource.getConnection</code> method, just as it normally does.
 179 The transaction manager manages the transaction behind the scenes.  The
 180 <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
 181 each <code>XAConnection</code> object creates an <code>XAResource</code> object 
 182 that the transaction manager uses to manage the connection.
 183 
 184 
 185 <H2>Rowsets</H2>
 186 The <code>RowSet</code> interface works with various other classes and
 187 interfaces behind the scenes. These can be grouped into three categories.
 188 <OL>
 189 <LI>Event Notification 
 190 <UL>
 191   <LI><code>RowSetListener</code><br>
 192 A <code>RowSet</code> object is a JavaBeans&trade;
 193 component because it has properties and participates in the JavaBeans
 194 event notification mechanism. The <code>RowSetListener</code> interface 
 195 is implemented by a component that wants to be notified about events that 
 196 occur to a particular <code>RowSet</code> object.  Such a component registers
 197 itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
 198 method.
 199 <P>
 200 When the <code>RowSet</code> object changes one of its rows, changes all of
 201 it rows, or moves its cursor, it also notifies each listener that is registered 
 202 with it.  The listener reacts by carrying out its implementation of the 
 203 notification method called on it.
 204   <LI><code>RowSetEvent</code><br>
 205 As part of its internal notification process, a <code>RowSet</code> object
 206 creates an instance of <code>RowSetEvent</code> and passes it to the listener.
 207 The listener can use this <code>RowSetEvent</code> object to find out which rowset
 208 had the event.
 209 </UL>
 210 <LI>Metadata 
 211 <UL>
 212   <LI><code>RowSetMetaData</code><br>
 213 This interface, derived from the
 214 <code>ResultSetMetaData</code> interface, provides information about
 215 the columns in a <code>RowSet</code> object.  An application can use
 216 <code>RowSetMetaData</code> methods to find out how many columns the
 217 rowset contains and what kind of data each column can contain.
 218 <P>
 219 The <code>RowSetMetaData</code> interface provides methods for
 220 setting the information about columns, but an application would not
 221 normally use these methods.  When an application calls the <code>RowSet</code> 
 222 method <code>execute</code>, the <code>RowSet</code> object will contain
 223 a new set of rows, and its <code>RowSetMetaData</code> object will have been
 224 internally updated to contain information about the new columns.
 225 </UL>
 226 <LI>The Reader/Writer Facility<br>
 227 A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
 228 interface can call on the <code>RowSetReader</code> object associated with it
 229 to populate itself with data.  It can also call on the <code>RowSetWriter</code>
 230 object associated with it to write any changes to its rows back to the
 231 data source from which it originally got the rows.
 232 A rowset that remains connected to its data source does not need to use a 
 233 reader and writer because it can simply operate on the data source directly.
 234 
 235 <UL>
 236   <LI><code>RowSetInternal</code><br>
 237 By implementing the <code>RowSetInternal</code> interface, a 
 238 <code>RowSet</code> object gets access to
 239 its internal state and is able to call on its reader and writer. A rowset
 240 keeps track of the values in its current rows and of the values that immediately
 241 preceded the current ones, referred to as the <i>original</i> values.  A rowset
 242 also keeps track of (1) the parameters that have been set for its command and 
 243 (2) the connection that was passed to it, if any.  A rowset uses the 
 244 <code>RowSetInternal</code> methods behind the scenes to get access to
 245 this information.  An application does not normally invoke these methods directly.
 246 
 247   <LI><code>RowSetReader</code><br>
 248 A disconnected <code>RowSet</code> object that has implemented the 
 249 <code>RowSetInternal</code> interface can call on its reader (the 
 250 <code>RowSetReader</code> object associated with it) to populate it with 
 251 data.  When an application calls the <code>RowSet.execute</code> method, 
 252 that method calls on the rowset's reader to do much of the work. Implementations
 253 can vary widely, but generally a reader makes a connection to the data source,
 254 reads data from the data source and populates the rowset with it, and closes
 255 the connection. A reader may also update the <code>RowSetMetaData</code> object
 256 for its rowset.  The rowset's internal state is also updated, either by the
 257 reader or directly by the method <code>RowSet.execute</code>.
 258 
 259 
 260   <LI><code>RowSetWriter</code><br>
 261 A disconnected <code>RowSet</code> object that has implemented the 
 262 <code>RowSetInternal</code> interface can call on its writer (the 
 263 <code>RowSetWriter</code> object associated with it) to write changes
 264 back to the underlying data source.  Implementations may vary widely, but
 265 generally, a writer will do the following:
 266 
 267 <UL>
 268   <LI>Make a connection to the data source 
 269   <LI>Check to see whether there is a conflict, that is, whether
 270       a value that has been changed in the rowset has also been changed 
 271       in the data source
 272   <LI>Write the new values to the data source if there is no conflict 
 273   <LI>Close the connection
 274 </UL>
 275  
 276 
 277 </UL>
 278 </OL>
 279 <P>
 280 The <code>RowSet</code> interface may be implemented in any number of
 281 ways, and anyone may write an implementation. Developers are encouraged 
 282 to use their imaginations in coming up with new ways to use rowsets.
 283 
 284 
 285 <h2>Package Specification</h2>
 286 
 287 <ul>
 288   <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
 289 </ul>
 290 
 291 <h2>Related Documentation</h2>
 292 
 293 The Java Series book published by Addison-Wesley Longman provides detailed
 294 information about the classes and interfaces in the <code>javax.sql</code>
 295 package: 
 296 
 297 <ul>
 298   <li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
 299           <i>JDBC™API Tutorial and Reference, Third Edition</i></a>
 300 </ul>
 301 </body>
 302 </html>
   1 /**
   2  * Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  * <p>
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  * <p>
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  * <p>
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  * <p>
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /**
  27  * Provides the API for server side data source access and processing from
  28  * the Java&trade; programming language.
  29  * This package supplements the <code>java.sql</code>
  30  * package and, as of the version 1.4 release, is included in the
  31  * Java Platform, Standard Edition (Java SE&trade;).
  32  * It remains an essential part of the Java Platform, Enterprise Edition
  33  * (Java EE&trade;).
  34  * <p>
  35  * The <code>javax.sql</code> package provides for the following:
  36  * <OL>
  37  * <LI>The <code>DataSource</code> interface as an alternative to the
  38  * <code>DriverManager</code> for establishing a
  39  * connection with a data source
  40  * <LI>Connection pooling and Statement pooling
  41  * <LI>Distributed transactions
  42  * <LI>Rowsets
  43  * </OL>
  44  * <p>
  45  * Applications use the <code>DataSource</code> and <code>RowSet</code>
  46  * APIs directly, but the connection pooling and distributed transaction
  47  * APIs are used internally by the middle-tier infrastructure.
  48  *
  49  * <H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
  50  * <p>
  51  * The <code>javax.sql</code> package provides the preferred
  52  * way to make a connection with a data source.  The <code>DriverManager</code>
  53  * class, the original mechanism, is still valid, and code using it will
  54  * continue to run.  However, the newer <code>DataSource</code> mechanism
  55  * is preferred because it offers many advantages over the
  56  * <code>DriverManager</code> mechanism.
  57  * <p>
  58  * These are the main advantages of using a <code>DataSource</code> object to
  59  * make a connection:
  60  * <UL>
  61  *
  62  * <LI>Changes can be made to a data source's properties, which means
  63  * that it is not necessary to make changes in application code when
  64  * something about the data source or driver changes.
  65  * <LI>Connection  and Statement pooling and distributed transactions are available
  66  * through a <code>DataSource</code> object that is
  67  * implemented to work with the middle-tier infrastructure.
  68  * Connections made through the <code>DriverManager</code>
  69  * do not have connection and statement pooling or distributed transaction
  70  * capabilities.
  71  * </UL>
  72  * <p>
  73  * Driver vendors provide <code>DataSource</code> implementations. A
  74  * particular <code>DataSource</code> object represents a particular
  75  * physical data source, and each connection the <code>DataSource</code> object
  76  * creates is a connection to that physical data source.
  77  * <p>
  78  * A logical name for the data source is registered with a naming service that
  79  * uses the Java Naming and Directory Interface&trade;
  80  * (JNDI) API, usually by a system administrator or someone performing the
  81  * duties of a system administrator. An application can retrieve the
  82  * <code>DataSource</code> object it wants by doing a lookup on the logical
  83  * name that has been registered for it.  The application can then use the
  84  * <code>DataSource</code> object to create a connection to the physical data
  85  * source it represents.
  86  * <p>
  87  * A <code>DataSource</code> object can be implemented to work with the
  88  * middle tier infrastructure so that the connections it produces will be
  89  * pooled for reuse. An application that uses such a <code>DataSource</code>
  90  * implementation will automatically get a connection that participates in
  91  * connection pooling.
  92  * A <code>DataSource</code> object can also be implemented to work with the
  93  * middle tier infrastructure so that the connections it produces can be
  94  * used for distributed transactions without any special coding.
  95  *
  96  * <H2>Connection Pooling and Statement Pooling</H2>
  97  * <p>
  98  * Connections made via a <code>DataSource</code>
  99  * object that is implemented to work with a middle tier connection pool manager
 100  * will participate in connection pooling.  This can improve performance
 101  * dramatically because creating new connections is very expensive.
 102  * Connection pooling allows a connection to be used and reused,
 103  * thus cutting down substantially on the number of new connections
 104  * that need to be created.
 105  * <p>
 106  * Connection pooling is totally transparent.  It is done automatically
 107  * in the middle tier of a Java EE configuration, so from an application's
 108  * viewpoint, no change in code is required. An application simply uses
 109  * the <code>DataSource.getConnection</code> method to get the pooled
 110  * connection and uses it the same way it uses any <code>Connection</code>
 111  * object.
 112  * <p>
 113  * The classes and interfaces used for connection pooling are:
 114  * <UL>
 115  * <LI><code>ConnectionPoolDataSource</code>
 116  * <LI><code>PooledConnection</code>
 117  * <LI><code>ConnectionEvent</code>
 118  * <LI><code>ConnectionEventListener</code>
 119  * <LI><code>StatementEvent</code>
 120  * <LI><code>StatementEventListener</code>
 121  * </UL>
 122  * The connection pool manager, a facility in the middle tier of
 123  * a three-tier architecture, uses these classes and interfaces
 124  * behind the scenes.  When a <code>ConnectionPoolDataSource</code> object
 125  * is called on to create a <code>PooledConnection</code> object, the
 126  * connection pool manager will register as a <code>ConnectionEventListener</code>
 127  * object with the new <code>PooledConnection</code> object.  When the connection
 128  * is closed or there is an error, the connection pool manager (being a listener)
 129  * gets a notification that includes a <code>ConnectionEvent</code> object.
 130  * <p>
 131  * If the connection pool manager supports <code>Statement</code> pooling, for
 132  * <code>PreparedStatements</code>, which can be determined by invoking the method
 133  * <code>DatabaseMetaData.supportsStatementPooling</code>,  the
 134  * connection pool manager will register as a <code>StatementEventListener</code>
 135  * object with the new <code>PooledConnection</code> object.  When the
 136  * <code>PreparedStatement</code> is closed or there is an error, the connection
 137  * pool manager (being a listener)
 138  * gets a notification that includes a <code>StatementEvent</code> object.
 139  *
 140  * <H2>Distributed Transactions</H2>
 141  * <p>
 142  * As with pooled connections, connections made via a <code>DataSource</code>
 143  * object that is implemented to work with the middle tier infrastructure
 144  * may participate in distributed transactions.  This gives an application
 145  * the ability to involve data sources on multiple servers in a single
 146  * transaction.
 147  * <p>
 148  * The classes and interfaces used for distributed transactions are:
 149  * <UL>
 150  * <LI><code>XADataSource</code>
 151  * <LI><code>XAConnection</code>
 152  * </UL>
 153  * These interfaces are used by the transaction manager; an application does
 154  * not use them directly.
 155  * <p>
 156  * The <code>XAConnection</code> interface is derived from the
 157  * <code>PooledConnection</code> interface, so what applies to a pooled connection
 158  * also applies to a connection that is part of a distributed transaction.
 159  * A transaction manager in the middle tier handles everything transparently.
 160  * The only change in application code is that an application cannot do anything
 161  * that would interfere with the transaction manager's handling of the transaction.
 162  * Specifically, an application cannot call the methods <code>Connection.commit</code>
 163  * or <code>Connection.rollback</code>, and it cannot set the connection to be in
 164  * auto-commit mode (that is, it cannot call
 165  * <code>Connection.setAutoCommit(true)</code>).
 166  * <p>
 167  * An application does not need to do anything special to participate in a
 168  * distributed transaction.
 169  * It simply creates connections to the data sources it wants to use via
 170  * the <code>DataSource.getConnection</code> method, just as it normally does.
 171  * The transaction manager manages the transaction behind the scenes.  The
 172  * <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
 173  * each <code>XAConnection</code> object creates an <code>XAResource</code> object
 174  * that the transaction manager uses to manage the connection.
 175  *
 176  *
 177  * <H2>Rowsets</H2>
 178  * The <code>RowSet</code> interface works with various other classes and
 179  * interfaces behind the scenes. These can be grouped into three categories.
 180  * <OL>
 181  * <LI>Event Notification
 182  * <UL>
 183  * <LI><code>RowSetListener</code><br>
 184  * A <code>RowSet</code> object is a JavaBeans&trade;
 185  * component because it has properties and participates in the JavaBeans
 186  * event notification mechanism. The <code>RowSetListener</code> interface
 187  * is implemented by a component that wants to be notified about events that
 188  * occur to a particular <code>RowSet</code> object.  Such a component registers
 189  * itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
 190  * method.
 191  * <p>
 192  * When the <code>RowSet</code> object changes one of its rows, changes all of
 193  * it rows, or moves its cursor, it also notifies each listener that is registered
 194  * with it.  The listener reacts by carrying out its implementation of the
 195  * notification method called on it.
 196  * <LI><code>RowSetEvent</code><br>
 197  * As part of its internal notification process, a <code>RowSet</code> object
 198  * creates an instance of <code>RowSetEvent</code> and passes it to the listener.
 199  * The listener can use this <code>RowSetEvent</code> object to find out which rowset
 200  * had the event.
 201  * </UL>
 202  * <LI>Metadata
 203  * <UL>
 204  * <LI><code>RowSetMetaData</code><br>
 205  * This interface, derived from the
 206  * <code>ResultSetMetaData</code> interface, provides information about
 207  * the columns in a <code>RowSet</code> object.  An application can use
 208  * <code>RowSetMetaData</code> methods to find out how many columns the
 209  * rowset contains and what kind of data each column can contain.
 210  * <p>
 211  * The <code>RowSetMetaData</code> interface provides methods for
 212  * setting the information about columns, but an application would not
 213  * normally use these methods.  When an application calls the <code>RowSet</code>
 214  * method <code>execute</code>, the <code>RowSet</code> object will contain
 215  * a new set of rows, and its <code>RowSetMetaData</code> object will have been
 216  * internally updated to contain information about the new columns.
 217  * </UL>
 218  * <LI>The Reader/Writer Facility<br>
 219  * A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
 220  * interface can call on the <code>RowSetReader</code> object associated with it
 221  * to populate itself with data.  It can also call on the <code>RowSetWriter</code>
 222  * object associated with it to write any changes to its rows back to the
 223  * data source from which it originally got the rows.
 224  * A rowset that remains connected to its data source does not need to use a
 225  * reader and writer because it can simply operate on the data source directly.
 226  *
 227  * <UL>
 228  * <LI><code>RowSetInternal</code><br>
 229  * By implementing the <code>RowSetInternal</code> interface, a
 230  * <code>RowSet</code> object gets access to
 231  * its internal state and is able to call on its reader and writer. A rowset
 232  * keeps track of the values in its current rows and of the values that immediately
 233  * preceded the current ones, referred to as the <i>original</i> values.  A rowset
 234  * also keeps track of (1) the parameters that have been set for its command and
 235  * (2) the connection that was passed to it, if any.  A rowset uses the
 236  * <code>RowSetInternal</code> methods behind the scenes to get access to
 237  * this information.  An application does not normally invoke these methods directly.
 238  *
 239  * <LI><code>RowSetReader</code><br>
 240  * A disconnected <code>RowSet</code> object that has implemented the
 241  * <code>RowSetInternal</code> interface can call on its reader (the
 242  * <code>RowSetReader</code> object associated with it) to populate it with
 243  * data.  When an application calls the <code>RowSet.execute</code> method,
 244  * that method calls on the rowset's reader to do much of the work. Implementations
 245  * can vary widely, but generally a reader makes a connection to the data source,
 246  * reads data from the data source and populates the rowset with it, and closes
 247  * the connection. A reader may also update the <code>RowSetMetaData</code> object
 248  * for its rowset.  The rowset's internal state is also updated, either by the
 249  * reader or directly by the method <code>RowSet.execute</code>.
 250  *
 251  *
 252  * <LI><code>RowSetWriter</code><br>
 253  * A disconnected <code>RowSet</code> object that has implemented the
 254  * <code>RowSetInternal</code> interface can call on its writer (the
 255  * <code>RowSetWriter</code> object associated with it) to write changes
 256  * back to the underlying data source.  Implementations may vary widely, but
 257  * generally, a writer will do the following:
 258  *
 259  * <UL>
 260  * <LI>Make a connection to the data source
 261  * <LI>Check to see whether there is a conflict, that is, whether
 262  * a value that has been changed in the rowset has also been changed
 263  * in the data source
 264  * <LI>Write the new values to the data source if there is no conflict
 265  * <LI>Close the connection
 266  * </UL>
 267  *
 268  *
 269  * </UL>
 270  * </OL>
 271  * <p>
 272  * The <code>RowSet</code> interface may be implemented in any number of
 273  * ways, and anyone may write an implementation. Developers are encouraged
 274  * to use their imaginations in coming up with new ways to use rowsets.
 275  *
 276  *
 277  * <h2>Package Specification</h2>
 278  *
 279  * <ul>
 280  * <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
 281  * </ul>
 282  *
 283  * <h2>Related Documentation</h2>
 284  * <p>
 285  * The Java Series book published by Addison-Wesley Longman provides detailed
 286  * information about the classes and interfaces in the <code>javax.sql</code>
 287  * package:
 288  *
 289  * <ul>
 290  * <li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
 291  * <i>JDBC™API Tutorial and Reference, Third Edition</i></a>
 292  * </ul>
 293  */
 294 package javax.sql;








< prev index next >