1 /*
   2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   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  *
  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  *
  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  *
  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 package javax.sql.rowset;
  27 
  28 import java.sql.*;
  29 import javax.sql.*;
  30 import javax.naming.*;
  31 import java.io.*;
  32 import java.math.*;
  33 import java.io.*;
  34 
  35 /**
  36  * The standard interface that all standard implementations of
  37  * <code>JdbcRowSet</code> must implement.
  38  *
  39  * <h3>1.0 Overview</h3>
  40  * A wrapper around a <code>ResultSet</code> object that makes it possible
  41  * to use the result set as a JavaBeans&trade;
  42  * component.  Thus, a <code>JdbcRowSet</code> object can be one of the Beans that
  43  * a tool makes available for composing an application.  Because
  44  * a <code>JdbcRowSet</code> is a connected rowset, that is, it continually
  45  * maintains its connection to a database using a JDBC technology-enabled
  46  * driver, it also effectively makes the driver a JavaBeans component.
  47  * <P>
  48  * Because it is always connected to its database, an instance of
  49  * <code>JdbcRowSet</code>
  50  * can simply take calls invoked on it and in turn call them on its
  51  * <code>ResultSet</code> object. As a consequence, a result set can, for
  52  * example, be a component in a Swing application.
  53  * <P>
  54  * Another advantage of a <code>JdbcRowSet</code> object is that it can be
  55  * used to make a <code>ResultSet</code> object scrollable and updatable.  All
  56  * <code>RowSet</code> objects are by default scrollable and updatable. If
  57  * the driver and database being used do not support scrolling and/or updating
  58  * of result sets, an application can populate a <code>JdbcRowSet</code> object
  59  * with the data of a <code>ResultSet</code> object and then operate on the
  60  * <code>JdbcRowSet</code> object as if it were the <code>ResultSet</code>
  61  * object.
  62  *
  63  * <h3>2.0 Creating a <code>JdbcRowSet</code> Object</h3>
  64  * The reference implementation of the <code>JdbcRowSet</code> interface,
  65  * <code>JdbcRowSetImpl</code>, provides an implementation of
  66  * the default constructor.  A new instance is initialized with
  67  * default values, which can be set with new values as needed. A
  68  * new instance is not really functional until its <code>execute</code>
  69  * method is called. In general, this method does the following:
  70  * <UL>
  71  *   <LI> establishes a connection with a database
  72  *   <LI> creates a <code>PreparedStatement</code> object and sets any of its
  73  *        placeholder parameters
  74  *   <LI> executes the statement to create a <code>ResultSet</code> object
  75  * </UL>
  76  * If the <code>execute</code> method is successful, it will set the
  77  * appropriate private <code>JdbcRowSet</code> fields with the following:
  78  * <UL>
  79  *  <LI> a <code>Connection</code> object -- the connection between the rowset
  80  *       and the database
  81  *  <LI> a <code>PreparedStatement</code> object -- the query that produces
  82  *       the result set
  83  *  <LI> a <code>ResultSet</code> object -- the result set that the rowset's
  84  *       command produced and that is being made, in effect, a JavaBeans
  85  *       component
  86  * </UL>
  87  * If these fields have not been set, meaning that the <code>execute</code>
  88  * method has not executed successfully, no methods other than
  89  * <code>execute</code> and <code>close</code> may be called on the
  90  * rowset.  All other public methods will throw an exception.
  91  * <P>
  92  * Before calling the <code>execute</code> method, however, the command
  93  * and properties needed for establishing a connection must be set.
  94  * The following code fragment creates a <code>JdbcRowSetImpl</code> object,
  95  * sets the command and connection properties, sets the placeholder parameter,
  96  * and then invokes the method <code>execute</code>.
  97  * <PRE>
  98  *     JdbcRowSetImpl jrs = new JdbcRowSetImpl();
  99  *     jrs.setCommand("SELECT * FROM TITLES WHERE TYPE = ?");
 100  *     jrs.setURL("jdbc:myDriver:myAttribute");
 101  *     jrs.setUsername("cervantes");
 102  *     jrs.setPassword("sancho");
 103  *     jrs.setString(1, "BIOGRAPHY");
 104  *     jrs.execute();
 105  * </PRE>
 106  * The variable <code>jrs</code> now represents an instance of
 107  * <code>JdbcRowSetImpl</code> that is a thin wrapper around the
 108  * <code>ResultSet</code> object containing all the rows in the
 109  * table <code>TITLES</code> where the type of book is biography.
 110  * At this point, operations called on <code>jrs</code> will
 111  * affect the rows in the result set, which is effectively a JavaBeans
 112  * component.
 113  * <P>
 114  * The implementation of the <code>RowSet</code> method <code>execute</code> in the
 115  * <code>JdbcRowSet</code> reference implementation differs from that in the
 116  * <code>CachedRowSet</code>&trade;
 117  * reference implementation to account for the different
 118  * requirements of connected and disconnected <code>RowSet</code> objects.
 119  *
 120  * @author Jonathan Bruce
 121  */
 122 
 123 public interface JdbcRowSet extends RowSet, Joinable {
 124 
 125     /**
 126      * Retrieves a <code>boolean</code> indicating whether rows marked
 127      * for deletion appear in the set of current rows. If <code>true</code> is
 128      * returned, deleted rows are visible with the current rows. If
 129      * <code>false</code> is returned, rows are not visible with the set of
 130      * current rows. The default value is <code>false</code>.
 131      * <P>
 132      * Standard rowset implementations may choose to restrict this behavior
 133      * for security considerations or for certain deployment
 134      * scenarios. The visibility of deleted rows is implementation-defined
 135      * and does not represent standard behavior.
 136      * <P>
 137      * Note: Allowing deleted rows to remain visible complicates the behavior
 138      * of some standard JDBC <code>RowSet</code> implementations methods.
 139      * However, most rowset users can simply ignore this extra detail because
 140      * only very specialized applications will likely want to take advantage of
 141      * this feature.
 142      *
 143      * @return <code>true</code> if deleted rows are visible;
 144      *         <code>false</code> otherwise
 145      * @exception SQLException if a rowset implementation is unable to
 146      *          to determine whether rows marked for deletion remain visible
 147      * @see #setShowDeleted
 148      */
 149     public boolean getShowDeleted() throws SQLException;
 150 
 151     /**
 152      * Sets the property <code>showDeleted</code> to the given
 153      * <code>boolean</code> value. This property determines whether
 154      * rows marked for deletion continue to appear in the set of current rows.
 155      * If the value is set to <code>true</code>, deleted rows are immediately
 156      * visible with the set of current rows. If the value is set to
 157      * <code>false</code>, the deleted rows are set as invisible with the
 158      * current set of rows.
 159      * <P>
 160      * Standard rowset implementations may choose to restrict this behavior
 161      * for security considerations or for certain deployment
 162      * scenarios. This is left as implementation-defined and does not
 163      * represent standard behavior.
 164      *
 165      * @param b <code>true</code> if deleted rows should be shown;
 166      *              <code>false</code> otherwise
 167      * @exception SQLException if a rowset implementation is unable to
 168      *          to reset whether deleted rows should be visible
 169      * @see #getShowDeleted
 170      */
 171     public void setShowDeleted(boolean b) throws SQLException;
 172 
 173     /**
 174      * Retrieves the first warning reported by calls on this <code>JdbcRowSet</code>
 175      * object.
 176      * If a second warning was reported on this <code>JdbcRowSet</code> object,
 177      * it will be chained to the first warning and can be retrieved by
 178      * calling the method <code>RowSetWarning.getNextWarning</code> on the
 179      * first warning. Subsequent warnings on this <code>JdbcRowSet</code>
 180      * object will be chained to the <code>RowSetWarning</code> objects
 181      * returned by the method <code>RowSetWarning.getNextWarning</code>.
 182      *
 183      * The warning chain is automatically cleared each time a new row is read.
 184      * This method may not be called on a <code>RowSet</code> object
 185      * that has been closed;
 186      * doing so will cause an <code>SQLException</code> to be thrown.
 187      * <P>
 188      * Because it is always connected to its data source, a <code>JdbcRowSet</code>
 189      * object can rely on the presence of active
 190      * <code>Statement</code>, <code>Connection</code>, and <code>ResultSet</code>
 191      * instances. This means that  applications can obtain additional
 192      * <code>SQLWarning</code>
 193      * notifications by calling the <code>getNextWarning</code> methods that
 194      * they provide.
 195      * Disconnected <code>Rowset</code> objects, such as a
 196      * <code>CachedRowSet</code> object, do not have access to
 197      * these <code>getNextWarning</code> methods.
 198      *
 199      * @return the first <code>RowSetWarning</code>
 200      * object reported on this <code>JdbcRowSet</code> object
 201      * or <code>null</code> if there are none
 202      * @throws SQLException if this method is called on a closed
 203      * <code>JdbcRowSet</code> object
 204      * @see RowSetWarning
 205      */
 206     public RowSetWarning getRowSetWarnings() throws SQLException;
 207 
 208    /**
 209     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
 210     * the <code>ResultSet</code> or JDBC properties passed to it's constructors.
 211     * This method wraps the <code>Connection</code> commit method to allow flexible
 212     * auto commit or non auto commit transactional control support.
 213     * <p>
 214     * Makes all changes made since the previous commit/rollback permanent
 215     * and releases any database locks currently held by this Connection
 216     * object. This method should be used only when auto-commit mode has
 217     * been disabled.
 218     *
 219     * @throws SQLException if a database access error occurs or this
 220     * Connection object within this <code>JdbcRowSet</code> is in auto-commit mode
 221     * @see java.sql.Connection#setAutoCommit
 222     */
 223     public void commit() throws SQLException;
 224 
 225 
 226    /**
 227     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
 228     * the original <code>ResultSet</code> or JDBC properties passed to it. This
 229     * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
 230     * to allow an application to determine the <code>JdbcRowSet</code> transaction
 231     * behavior.
 232     * <p>
 233     * Sets this connection's auto-commit mode to the given state. If a
 234     * connection is in auto-commit mode, then all its SQL statements will
 235     * be executed and committed as individual transactions. Otherwise, its
 236     * SQL statements are grouped into transactions that are terminated by a
 237     * call to either the method commit or the method rollback. By default,
 238     * new connections are in auto-commit mode.
 239     *
 240     * @return {@code true} if auto-commit is enabled; {@code false} otherwise
 241     * @throws SQLException if a database access error occurs
 242     * @see java.sql.Connection#getAutoCommit()
 243     */
 244     public boolean getAutoCommit() throws SQLException;
 245 
 246 
 247    /**
 248     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
 249     * the original <code>ResultSet</code> or JDBC properties passed to it. This
 250     * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
 251     * to allow an application to set the <code>JdbcRowSet</code> transaction behavior.
 252     * <p>
 253     * Sets the current auto-commit mode for this <code>Connection</code> object.
 254     * @param autoCommit {@code true} to enable auto-commit; {@code false} to
 255     * disable auto-commit
 256     * @throws SQLException if a database access error occurs
 257     * @see java.sql.Connection#setAutoCommit(boolean)
 258     */
 259     public void setAutoCommit(boolean autoCommit) throws SQLException;
 260 
 261     /**
 262      * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
 263      * the original <code>ResultSet</code> or JDBC properties passed to it.
 264      * Undoes all changes made in the current transaction and releases any
 265      * database locks currently held by this <code>Connection</code> object. This method
 266      * should be used only when auto-commit mode has been disabled.
 267      *
 268      * @throws SQLException if a database access error occurs or this <code>Connection</code>
 269      * object within this <code>JdbcRowSet</code> is in auto-commit mode.
 270      * @see #rollback(Savepoint)
 271      */
 272      public void rollback() throws SQLException;
 273 
 274 
 275     /**
 276      * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
 277      * the original <code>ResultSet</code> or JDBC properties passed to it.
 278      * Undoes all changes made in the current transaction to the last set savepoint
 279      * and releases any database locks currently held by this <code>Connection</code>
 280      * object. This method should be used only when auto-commit mode has been disabled.
 281      * @param s The {@code Savepoint} to rollback to
 282      * @throws SQLException if a database access error occurs or this <code>Connection</code>
 283      * object within this <code>JdbcRowSet</code> is in auto-commit mode.
 284      * @see #rollback
 285      */
 286     public void rollback(Savepoint s) throws SQLException;
 287 
 288 }