jdk/src/java.sql.rowset/share/classes/javax/sql/rowset/CachedRowSet.java
changeset 25991 e48157b42439
parent 25976 4de01a56e3ee
parent 25859 3317bb8137f4
equal deleted inserted replaced
25876:d06a6d3c66c0 25991:e48157b42439
   284  * control mechanism is desired, a different implementation of
   284  * control mechanism is desired, a different implementation of
   285  * <code>SyncProvider</code> can be plugged in using the method
   285  * <code>SyncProvider</code> can be plugged in using the method
   286  * <code>setSyncProvider</code>.
   286  * <code>setSyncProvider</code>.
   287  * <P>
   287  * <P>
   288  * In order to use the optimistic concurrency control routine, the
   288  * In order to use the optimistic concurrency control routine, the
   289  * <code>RIOptismisticProvider</code> maintains both its current
   289  * <code>RIOptimisticProvider</code> maintains both its current
   290  * value and its original value (the value it had immediately preceding the
   290  * value and its original value (the value it had immediately preceding the
   291  * current value). Note that if no changes have been made to the data in a
   291  * current value). Note that if no changes have been made to the data in a
   292  * <code>RowSet</code> object, its current values and its original values are the same,
   292  * <code>RowSet</code> object, its current values and its original values are the same,
   293  * both being the values with which the <code>RowSet</code> object was initially
   293  * both being the values with which the <code>RowSet</code> object was initially
   294  * populated.  However, once any values in the <code>RowSet</code> object have been
   294  * populated.  However, once any values in the <code>RowSet</code> object have been
   349  * scrolling and updating for <code>ResultSet</code> objects that
   349  * scrolling and updating for <code>ResultSet</code> objects that
   350  * do not provide these capabilities themselves.  In other words, a
   350  * do not provide these capabilities themselves.  In other words, a
   351  * <code>CachedRowSet</code> object can be used to augment the
   351  * <code>CachedRowSet</code> object can be used to augment the
   352  * capabilities of a JDBC technology-enabled driver (hereafter called a
   352  * capabilities of a JDBC technology-enabled driver (hereafter called a
   353  * "JDBC driver") when the DBMS does not provide full support for scrolling and
   353  * "JDBC driver") when the DBMS does not provide full support for scrolling and
   354  * updating. To achieve the effect of making a non-scrollble and read-only
   354  * updating. To achieve the effect of making a non-scrollable and read-only
   355  * <code>ResultSet</code> object scrollable and updatable, a programmer
   355  * <code>ResultSet</code> object scrollable and updatable, a programmer
   356  * simply needs to create a <code>CachedRowSet</code> object populated
   356  * simply needs to create a <code>CachedRowSet</code> object populated
   357  * with that <code>ResultSet</code> object's data.  This is demonstrated
   357  * with that <code>ResultSet</code> object's data.  This is demonstrated
   358  * in the following code fragment, where <code>stmt</code> is a
   358  * in the following code fragment, where <code>stmt</code> is a
   359  * <code>Statement</code> object.
   359  * <code>Statement</code> object.
   730     * established.
   730     * established.
   731     * <P>
   731     * <P>
   732     * Note: The <code>acceptChanges()</code> method will determine if the
   732     * Note: The <code>acceptChanges()</code> method will determine if the
   733     * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
   733     * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
   734     * to true, all updates in the synchronization are committed to the data
   734     * to true, all updates in the synchronization are committed to the data
   735     * source. Otherwise, the application <b>must</b> explicity call the
   735     * source. Otherwise, the application <b>must</b> explicitly call the
   736     * <code>commit()</code> or <code>rollback()</code> methods as appropriate.
   736     * <code>commit()</code> or <code>rollback()</code> methods as appropriate.
   737     *
   737     *
   738     * @throws SyncProviderException if the underlying
   738     * @throws SyncProviderException if the underlying
   739     * synchronization provider's writer fails to write the updates
   739     * synchronization provider's writer fails to write the updates
   740     * back to the data source
   740     * back to the data source
   799     * established.
   799     * established.
   800     * <P>
   800     * <P>
   801     * Note: The <code>acceptChanges()</code> method will determine if the
   801     * Note: The <code>acceptChanges()</code> method will determine if the
   802     * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
   802     * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
   803     * to true, all updates in the synchronization are committed to the data
   803     * to true, all updates in the synchronization are committed to the data
   804     * source. Otherwise, the application <b>must</b> explicity call the
   804     * source. Otherwise, the application <b>must</b> explicitly call the
   805     * <code>commit</code> or <code>rollback</code> methods as appropriate.
   805     * <code>commit</code> or <code>rollback</code> methods as appropriate.
   806     *
   806     *
   807     * @param con a standard JDBC <code>Connection</code> object
   807     * @param con a standard JDBC <code>Connection</code> object
   808     * @throws SyncProviderException if the underlying
   808     * @throws SyncProviderException if the underlying
   809     * synchronization provider's writer fails to write the updates
   809     * synchronization provider's writer fails to write the updates
   848     * <P>
   848     * <P>
   849     * This <code>CachedRowSet</code> object should lock until its contents and
   849     * This <code>CachedRowSet</code> object should lock until its contents and
   850     * associated updates are fully cleared, thus preventing 'dirty' reads by
   850     * associated updates are fully cleared, thus preventing 'dirty' reads by
   851     * other components that hold a reference to this <code>RowSet</code> object.
   851     * other components that hold a reference to this <code>RowSet</code> object.
   852     * In addition, the contents cannot be released
   852     * In addition, the contents cannot be released
   853     * until all all components reading this <code>CachedRowSet</code> object
   853     * until all components reading this <code>CachedRowSet</code> object
   854     * have completed their reads. This <code>CachedRowSet</code> object
   854     * have completed their reads. This <code>CachedRowSet</code> object
   855     * should be returned to normal behavior after firing the
   855     * should be returned to normal behavior after firing the
   856     * <code>rowSetChanged</code> event.
   856     * <code>rowSetChanged</code> event.
   857     * <P>
   857     * <P>
   858     * The metadata, including JDBC properties and Synchronization SPI
   858     * The metadata, including JDBC properties and Synchronization SPI
   932     * <code>undoUpdate</code> may be called at any time during the lifetime of a
   932     * <code>undoUpdate</code> may be called at any time during the lifetime of a
   933     * rowset; however, after a synchronization has occurred, this method has no
   933     * rowset; however, after a synchronization has occurred, this method has no
   934     * effect until further modification to the rowset data has occurred.
   934     * effect until further modification to the rowset data has occurred.
   935     *
   935     *
   936     * @throws SQLException if the cursor is before the first row or after the last
   936     * @throws SQLException if the cursor is before the first row or after the last
   937     *     row in in this <code>CachedRowSet</code> object
   937     *     row in this <code>CachedRowSet</code> object
   938     * @see #undoDelete
   938     * @see #undoDelete
   939     * @see #undoInsert
   939     * @see #undoInsert
   940     * @see java.sql.ResultSet#cancelRowUpdates
   940     * @see java.sql.ResultSet#cancelRowUpdates
   941     */
   941     */
   942     public void undoUpdate() throws SQLException;
   942     public void undoUpdate() throws SQLException;
  1069    /**
  1069    /**
  1070     * Retrieves the <code>SyncProvider</code> implementation for this
  1070     * Retrieves the <code>SyncProvider</code> implementation for this
  1071     * <code>CachedRowSet</code> object. Internally, this method is used by a rowset
  1071     * <code>CachedRowSet</code> object. Internally, this method is used by a rowset
  1072     * to trigger read or write actions between the rowset
  1072     * to trigger read or write actions between the rowset
  1073     * and the data source. For example, a rowset may need to get a handle
  1073     * and the data source. For example, a rowset may need to get a handle
  1074     * on the the rowset reader (<code>RowSetReader</code> object) from the
  1074     * on the rowset reader (<code>RowSetReader</code> object) from the
  1075     * <code>SyncProvider</code> to allow the rowset to be populated.
  1075     * <code>SyncProvider</code> to allow the rowset to be populated.
  1076     * <pre>
  1076     * <pre>
  1077     *     RowSetReader rowsetReader = null;
  1077     *     RowSetReader rowsetReader = null;
  1078     *     SyncProvider provider =
  1078     *     SyncProvider provider =
  1079     *         SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider");
  1079     *         SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider");
  1094     * <code>SyncProvider</code> object, including information about the
  1094     * <code>SyncProvider</code> object, including information about the
  1095     * vendor, version, provider identification, synchronization grade, and locks
  1095     * vendor, version, provider identification, synchronization grade, and locks
  1096     * it currently has set.
  1096     * it currently has set.
  1097     *
  1097     *
  1098     * @return the <code>SyncProvider</code> object that was set when the rowset
  1098     * @return the <code>SyncProvider</code> object that was set when the rowset
  1099     *      was instantiated, or if none was was set, the default provider
  1099     *      was instantiated, or if none was set, the default provider
  1100     * @throws SQLException if an error occurs while returning the
  1100     * @throws SQLException if an error occurs while returning the
  1101     * <code>SyncProvider</code> object
  1101     * <code>SyncProvider</code> object
  1102     * @see #setSyncProvider
  1102     * @see #setSyncProvider
  1103     */
  1103     */
  1104     public SyncProvider getSyncProvider() throws SQLException;
  1104     public SyncProvider getSyncProvider() throws SQLException;