libjava/java/sql/Connection.java

   1 /* Connection.java -- Manage a database connection.
   2    Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.sql;
  40
  41 import java.util.Map;
  42
  43 /**
  44  * This interface provides methods for managing a connection to a database.
  45  *
  46  * @author Aaron M. Renn (arenn@urbanophile.com)
  47  */
  48 public interface Connection
  49 {
  50   /**
  51    * This transaction isolation level indicates that transactions are not
  52    * supported.
  53    */
  54   int TRANSACTION_NONE = 0;
  55
  56   /**
  57    * This transaction isolation level indicates that one transaction can
  58    * read modifications by other transactions before the other transactions
  59    * have committed their changes.  This could result in invalid reads.
  60    */
  61   int TRANSACTION_READ_UNCOMMITTED = 1;
  62
  63   /**
  64    * This transaction isolation leve indicates that only committed data from
  65    * other transactions will be read.  If a transaction reads a row, then
  66    * another transaction commits a change to that row, the first transaction
  67    * would retrieve the changed row on subsequent reads of the same row.
  68    */
  69   int TRANSACTION_READ_COMMITTED = 2;
  70
  71   /**
  72    * This transaction isolation level indicates that only committed data from
  73    * other transactions will be read.  It also ensures that data read from
  74    * a row will not be different on a subsequent read even if another
  75    * transaction commits a change.
  76    */
  77   int TRANSACTION_REPEATABLE_READ = 4;
  78
  79   /**
  80    * This transaction isolation level indicates that only committed data from
  81    * other transactions will be read.  It also ensures that data read from
  82    * a row will not be different on a subsequent read even if another
  83    * transaction commits a change.  Additionally, rows modified by other
  84    * transactions will not affect the result set returned during subsequent
  85    * executions of the same WHERE clause in this transaction.
  86    */
  87   int TRANSACTION_SERIALIZABLE = 8;
  88
  89   /**
  90    * This method creates a new SQL statement.  The default result set type
  91    * and concurrency will be used.
  92    *
  93    * @return A new <code>Statement</code> object.
  94    * @exception SQLException If an error occurs.
  95    * @see Statement
  96    */
  97   Statement createStatement() throws SQLException;
  98
  99   /**
 100    * This method creates a new <code>PreparedStatement</code> for the specified
 101    * SQL string.  This method is designed for use with parameterized
 102    * statements.  The default result set type and concurrency will be used.
 103    *
 104    * @param The SQL statement to use in creating this
 105    *        <code>PreparedStatement</code>.
 106    * @return A new <code>PreparedStatement</code>.
 107    * @exception SQLException If an error occurs.
 108    * @see PreparedStatement
 109    */
 110   PreparedStatement prepareStatement(String sql) throws SQLException;
 111
 112   /**
 113    * This method creates a new <code>CallableStatement</code> for the
 114    * specified SQL string.  Thie method is designed to be used with
 115    * stored procedures.  The default result set type and concurrency
 116    * will be used.
 117    *
 118    * @param The SQL statement to use in creating this
 119    *        <code>CallableStatement</code>.
 120    * @return A new <code>CallableStatement</code>.
 121    * @exception SQLException If an error occurs.
 122    * @see CallableStatement
 123    */
 124   CallableStatement prepareCall(String sql) throws SQLException;
 125
 126   /**
 127    * This method converts the specified generic SQL statement into the
 128    * native grammer of the database this object is connected to.
 129    *
 130    * @param The JDBC generic SQL statement.
 131    * @return The native SQL statement.
 132    * @exception SQLException If an error occurs.
 133    */
 134   String nativeSQL(String sql) throws SQLException;
 135
 136   /**
 137    * This method turns auto commit mode on or off.  In auto commit mode,
 138    * every SQL statement is committed its own transaction.  Otherwise a
 139    * transaction must be explicitly committed or rolled back.
 140    *
 141    * @param autoCommit <code>true</code> to enable auto commit mode,
 142    *        <code>false</code> to disable it.
 143    * @exception SQLException If an error occurs.
 144    * @see commit
 145    * @see rollback
 146    */
 147   void setAutoCommit(boolean autoCommit) throws SQLException;
 148
 149   /**
 150    * This method tests whether or not auto commit mode is currently enabled.
 151    * In auto commit mode,  every SQL statement is committed its own transaction.
 152    * Otherwise a transaction must be explicitly committed or rolled back.
 153    *
 154    * @return <code>true</code> if auto commit mode is enabled,
 155    * <code>false</code> otherwise.
 156    *
 157    * @exception SQLException If an error occurs.
 158    *
 159    * @see commit
 160    * @see rollback
 161    */
 162   boolean getAutoCommit() throws SQLException;
 163
 164  /**
 165   * This method commits any SQL statements executed on this connection since
 166   * the last commit or rollback.
 167   *
 168   * @exception SQLException If an error occurs.
 169   */
 170   void commit() throws SQLException;
 171
 172   /**
 173    * This method rolls back any SQL statements executed on this connection
 174    * since the last commit or rollback.
 175    *
 176    * @exception SQLException If an error occurs.
 177    */
 178   void rollback() throws SQLException;
 179
 180   /**
 181    * This method immediately closes this database connection.
 182    *
 183    * @exception SQLException If an error occurs.
 184    */
 185   void close() throws SQLException;
 186
 187   /**
 188    * This method tests whether or not this connection has been closed.
 189    *
 190    * @return <code>true</code> if the connection is closed, <code>false</code>
 191    *         otherwise.
 192    * @exception SQLException If an error occurs.
 193    */
 194   boolean isClosed() throws SQLException;
 195
 196   /**
 197    * This method returns the meta data for this database connection.
 198    *
 199    * @return The meta data for this database.
 200    * @exception SQLException If an error occurs.
 201    * @see DatabaseMetaData
 202    */
 203   DatabaseMetaData getMetaData() throws SQLException;
 204
 205   /**
 206    * This method turns read only mode on or off.  It may not be called while
 207    * a transaction is in progress.
 208    *
 209    * @param readOnly <code>true</code> if this connection is read only,
 210    *        <code>false</code> otherwise.
 211    * @exception SQLException If an error occurs.
 212    */
 213   void setReadOnly(boolean readOnly) throws SQLException;
 214
 215   /**
 216    * This method tests whether or not this connection is in read only mode.
 217    *
 218    * @return <code>true</code> if the connection is read only <code>false</code>
 219    *         otherwise.
 220    * @exception SQLException If an error occurs.
 221    */
 222   boolean isReadOnly() throws SQLException;
 223
 224   /**
 225    * This method sets the name of the catalog in use by this connection.
 226    * Note that this method does nothing if catalogs are not supported by
 227    * this database.
 228    *
 229    * @param catalog The name of the catalog to use for this connection.
 230    * @exception SQLException If an error occurs.
 231    */
 232   void setCatalog(String catalog) throws SQLException;
 233
 234   /**
 235    * This method returns the name of the catalog in use by this connection,
 236    * if any.
 237    *
 238    * @return The name of the catalog, or <code>null</code> if one does not
 239    *         exist or catalogs are not supported by this database.
 240    * @exception SQLException If an error occurs.
 241    */
 242   String getCatalog() throws SQLException;
 243
 244   /**
 245    * This method sets the current transaction isolation mode.  This must
 246    * be one of the constants defined in this interface.
 247    *
 248    * @param level The transaction isolation level.
 249    * @exception SQLException If an error occurs.
 250    */
 251   void setTransactionIsolation(int level) throws SQLException;
 252
 253   /**
 254    * This method returns the current transaction isolation mode.  This will
 255    * be one of the constants defined in this interface.
 256    *
 257    * @return The transaction isolation level.
 258    * @exception SQLException If an error occurs.
 259    */
 260   int getTransactionIsolation() throws SQLException;
 261
 262   /**
 263    * This method returns the first warning that occurred on this connection,
 264    * if any.  If there were any subsequence warnings, they will be chained
 265    * to the first one.
 266    *
 267    * @return The first <code>SQLWarning</code> that occurred, or
 268    *         <code>null</code> if there have been no warnings.
 269    * @exception SQLException If an error occurs.
 270    */
 271   SQLWarning getWarnings() throws SQLException;
 272
 273   /**
 274    * This method clears all warnings that have occurred on this connection.
 275    *
 276    * @exception SQLException If an error occurs.
 277    */
 278   void clearWarnings() throws SQLException;
 279
 280   /**
 281    * This method creates a new SQL statement with the specified type and
 282    * concurrency.  Valid values for these parameters are specified in the
 283    * <code>ResultSet</code> class.
 284    *
 285    * @param resultSetType The type of result set to use for this statement.
 286    * @param resultSetConcurrency.  The type of concurrency to be used in
 287    *        the result set for this statement.
 288    * @return A new <code>Statement</code> object.
 289    * @exception SQLException If an error occurs.
 290    * @see Statement
 291    * @see ResultSet
 292    */
 293   Statement createStatement(int resultSetType, int resultSetConcurrency)
 294     throws SQLException;
 295
 296   /**
 297    * This method creates a new <code>PreparedStatement</code> for the specified
 298    * SQL string.  This method is designed for use with parameterized
 299    * statements.  The specified result set type and concurrency will be used.
 300    * Valid values for these parameters are specified in the
 301    * <code>ResultSet</code> class.
 302    *
 303    * @param The SQL statement to use in creating this
 304    *        <code>PreparedStatement</code>.
 305    * @param resultSetType The type of result set to use for this statement.
 306    * @param resultSetConcurrency.  The type of concurrency to be used in
 307    *        the result set for this statement.
 308    * @return A new <code>PreparedStatement</code>.
 309    * @exception SQLException If an error occurs.
 310    * @see PreparedStatement
 311    * @see ResultSet
 312    */
 313   PreparedStatement prepareStatement(String sql, int resultSetType,
 314     int resultSetConcurrency) throws SQLException;
 315
 316   /**
 317    * This method creates a new <code>CallableStatement</code> for the
 318    * specified SQL string.  Thie method is designed to be used with
 319    * stored procedures.  The specified result set type and concurrency
 320    * will be used.  Valid values for these parameters are specified in the
 321    * <code>ResultSet</code> class.
 322    *
 323    * @param The SQL statement to use in creating this
 324    *        <code>PreparedStatement</code>.
 325    * @param resultSetType The type of result set to use for this statement.
 326    * @param resultSetConcurrency.  The type of concurrency to be used in
 327    *        the result set for this statement.
 328    * @return A new <code>CallableStatement</code>.
 329    * @exception SQLException If an error occurs.
 330    * @see CallableStatement
 331    * @see ResultSet
 332    */
 333   CallableStatement prepareCall(String sql, int resultSetType, int
 334     resultSetConcurrency) throws SQLException;
 335
 336   /**
 337    * This method returns the mapping of SQL types to Java classes
 338    * currently in use by this connection.  This mapping will have no
 339    * entries unless they have been manually added.
 340    *
 341    * @return The SQL type to Java class mapping.
 342    * @exception SQLException If an error occurs.
 343    */
 344   Map getTypeMap() throws SQLException;
 345
 346   /**
 347    * This method sets the mapping table for SQL types to Java classes.
 348    * Any entries in this map override the defaults.
 349    *
 350    * @param map The new SQL mapping table.
 351    * @exception SQLException If an error occurs.
 352    */
 353   void setTypeMap(Map map) throws SQLException;
 354
 355   /**
 356    * @since 1.4
 357    */
 358   void setHoldability(int holdability) throws SQLException;
 359
 360   /**
 361    * @since 1.4
 362    */
 363   int getHoldability() throws SQLException;
 364
 365   /**
 366    * @since 1.4
 367    */
 368   Savepoint setSavepoint() throws SQLException;
 369
 370   /**
 371    * @since 1.4
 372    */
 373   Savepoint setSavepoint(String name) throws SQLException;
 374
 375   /**
 376    * @since 1.4
 377    */
 378   void rollback(Savepoint savepoint) throws SQLException;
 379
 380   /**
 381    * @since 1.4
 382    */
 383   void releaseSavepoint(Savepoint savepoint) throws SQLException;
 384
 385   /**
 386    * @since 1.4
 387    */
 388   Statement createStatement(int resultSetType, int
 389       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 390
 391   /**
 392    * @since 1.4
 393    */
 394   PreparedStatement prepareStatement(String sql, int resultSetType, int
 395       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 396
 397   /**
 398    * @since 1.4
 399    */
 400   CallableStatement prepareCall(String sql, int resultSetType, int
 401       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 402
 403   /**
 404    * @since 1.4
 405    */
 406   PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
 407       throws SQLException;
 408
 409   /**
 410    * @since 1.4
 411    */
 412   PreparedStatement prepareStatement(String sql, int[] columnIndexes)
 413       throws SQLException;
 414
 415   /**
 416    * @since 1.4
 417    */
 418   PreparedStatement prepareStatement(String sql, String[] columnNames)
 419       throws SQLException;
 420 }