libjava/classpath/java/sql/Connection.java

   1 /* Connection.java -- Manage a database connection.
   2    Copyright (C) 1999, 2000, 2002, 2006 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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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   extends AutoCloseable
  50 {
  51   /**
  52    * This transaction isolation level indicates that transactions are not
  53    * supported.
  54    */
  55   int TRANSACTION_NONE = 0;
  56
  57   /**
  58    * This transaction isolation level indicates that one transaction can
  59    * read modifications by other transactions before the other transactions
  60    * have committed their changes.  This could result in invalid reads.
  61    */
  62   int TRANSACTION_READ_UNCOMMITTED = 1;
  63
  64   /**
  65    * This transaction isolation level indicates that only committed data from
  66    * other transactions will be read.  If a transaction reads a row, then
  67    * another transaction commits a change to that row, the first transaction
  68    * would retrieve the changed row on subsequent reads of the same row.
  69    */
  70   int TRANSACTION_READ_COMMITTED = 2;
  71
  72   /**
  73    * This transaction isolation level indicates that only committed data from
  74    * other transactions will be read.  It also ensures that data read from
  75    * a row will not be different on a subsequent read even if another
  76    * transaction commits a change.
  77    */
  78   int TRANSACTION_REPEATABLE_READ = 4;
  79
  80   /**
  81    * This transaction isolation level indicates that only committed data from
  82    * other transactions will be read.  It also ensures that data read from
  83    * a row will not be different on a subsequent read even if another
  84    * transaction commits a change.  Additionally, rows modified by other
  85    * transactions will not affect the result set returned during subsequent
  86    * executions of the same WHERE clause in this transaction.
  87    */
  88   int TRANSACTION_SERIALIZABLE = 8;
  89
  90   /**
  91    * This method creates a new SQL statement.  The default result set type
  92    * and concurrency will be used.
  93    *
  94    * @return A new <code>Statement</code> object.
  95    * @exception SQLException If an error occurs.
  96    * @see Statement
  97    */
  98   Statement createStatement() throws SQLException;
  99
 100   /**
 101    * This method creates a new <code>PreparedStatement</code> for the specified
 102    * SQL string.  This method is designed for use with parameterized
 103    * statements.  The default result set type and concurrency will be used.
 104    *
 105    * @param sql The SQL statement to use in creating this
 106    *            <code>PreparedStatement</code>.
 107    * @return A new <code>PreparedStatement</code>.
 108    * @exception SQLException If an error occurs.
 109    * @see PreparedStatement
 110    */
 111   PreparedStatement prepareStatement(String sql) throws SQLException;
 112
 113   /**
 114    * This method creates a new <code>CallableStatement</code> for the
 115    * specified SQL string.  Thie method is designed to be used with
 116    * stored procedures.  The default result set type and concurrency
 117    * will be used.
 118    *
 119    * @param sql The SQL statement to use in creating this
 120    *            <code>CallableStatement</code>.
 121    * @return A new <code>CallableStatement</code>.
 122    * @exception SQLException If an error occurs.
 123    * @see CallableStatement
 124    */
 125   CallableStatement prepareCall(String sql) throws SQLException;
 126
 127   /**
 128    * This method converts the specified generic SQL statement into the
 129    * native grammer of the database this object is connected to.
 130    *
 131    * @param sql The JDBC generic SQL statement.
 132    * @return The native SQL statement.
 133    * @exception SQLException If an error occurs.
 134    */
 135   String nativeSQL(String sql) throws SQLException;
 136
 137   /**
 138    * This method turns auto commit mode on or off.  In auto commit mode,
 139    * every SQL statement is committed its own transaction.  Otherwise a
 140    * transaction must be explicitly committed or rolled back.
 141    *
 142    * @param autoCommit <code>true</code> to enable auto commit mode,
 143    *                   <code>false</code> to disable it.
 144    * @exception SQLException If an error occurs.
 145    * @see #commit()
 146    * @see #rollback()
 147    */
 148   void setAutoCommit(boolean autoCommit) throws SQLException;
 149
 150   /**
 151    * This method tests whether or not auto commit mode is currently enabled.
 152    * In auto commit mode,  every SQL statement is committed its own transaction.
 153    * Otherwise a transaction must be explicitly committed or rolled back.
 154    *
 155    * @return <code>true</code> if auto commit mode is enabled,
 156    *         <code>false</code> otherwise.
 157    * @exception SQLException If an error occurs.
 158    * @see #commit()
 159    * @see #rollback()
 160    */
 161   boolean getAutoCommit() throws SQLException;
 162
 163  /**
 164   * This method commits any SQL statements executed on this connection since
 165   * the last commit or rollback.
 166   *
 167   * @exception SQLException If an error occurs.
 168   */
 169   void commit() throws SQLException;
 170
 171   /**
 172    * This method rolls back any SQL statements executed on this connection
 173    * since the last commit or rollback.
 174    *
 175    * @exception SQLException If an error occurs.
 176    */
 177   void rollback() throws SQLException;
 178
 179   /**
 180    * This method immediately closes this database connection.
 181    *
 182    * @exception SQLException If an error occurs.
 183    */
 184   void close() throws SQLException;
 185
 186   /**
 187    * This method tests whether or not this connection has been closed.
 188    *
 189    * @return <code>true</code> if the connection is closed, <code>false</code>
 190    *         otherwise.
 191    * @exception SQLException If an error occurs.
 192    */
 193   boolean isClosed() throws SQLException;
 194
 195   /**
 196    * This method returns the meta data for this database connection.
 197    *
 198    * @return The meta data for this database.
 199    * @exception SQLException If an error occurs.
 200    * @see DatabaseMetaData
 201    */
 202   DatabaseMetaData getMetaData() throws SQLException;
 203
 204   /**
 205    * This method turns read only mode on or off.  It may not be called while
 206    * a transaction is in progress.
 207    *
 208    * @param readOnly <code>true</code> if this connection is read only,
 209    *                 <code>false</code> otherwise.
 210    * @exception SQLException If an error occurs.
 211    */
 212   void setReadOnly(boolean readOnly) throws SQLException;
 213
 214   /**
 215    * This method tests whether or not this connection is in read only mode.
 216    *
 217    * @return <code>true</code> if the connection is read only <code>false</code>
 218    *         otherwise.
 219    * @exception SQLException If an error occurs.
 220    */
 221   boolean isReadOnly() throws SQLException;
 222
 223   /**
 224    * This method sets the name of the catalog in use by this connection.
 225    * Note that this method does nothing if catalogs are not supported by
 226    * this database.
 227    *
 228    * @param catalog The name of the catalog to use for this connection.
 229    * @exception SQLException If an error occurs.
 230    */
 231   void setCatalog(String catalog) throws SQLException;
 232
 233   /**
 234    * This method returns the name of the catalog in use by this connection,
 235    * if any.
 236    *
 237    * @return The name of the catalog, or <code>null</code> if none
 238    *         exists or catalogs are not supported by this database.
 239    * @exception SQLException If an error occurs.
 240    */
 241   String getCatalog() throws SQLException;
 242
 243   /**
 244    * This method sets the current transaction isolation mode.  This must
 245    * be one of the constants defined in this interface.
 246    *
 247    * @param level The transaction isolation level.
 248    * @exception SQLException If an error occurs.
 249    */
 250   void setTransactionIsolation(int level) throws SQLException;
 251
 252   /**
 253    * This method returns the current transaction isolation mode.  This will
 254    * be one of the constants defined in this interface.
 255    *
 256    * @return The transaction isolation level.
 257    * @exception SQLException If an error occurs.
 258    */
 259   int getTransactionIsolation() throws SQLException;
 260
 261   /**
 262    * This method returns the first warning that occurred on this connection,
 263    * if any.  If there were any subsequence warnings, they will be chained
 264    * to the first one.
 265    *
 266    * @return The first <code>SQLWarning</code> that occurred, or
 267    *         <code>null</code> if there have been no warnings.
 268    * @exception SQLException If an error occurs.
 269    */
 270   SQLWarning getWarnings() throws SQLException;
 271
 272   /**
 273    * This method clears all warnings that have occurred on this connection.
 274    *
 275    * @exception SQLException If an error occurs.
 276    */
 277   void clearWarnings() throws SQLException;
 278
 279   /**
 280    * This method creates a new SQL statement with the specified type and
 281    * concurrency.  Valid values for these parameters are specified in the
 282    * <code>ResultSet</code> class.
 283    *
 284    * @param resultSetType The type of result set to use for this statement.
 285    * @param resultSetConcurrency  The type of concurrency to be used in
 286    *                              the result set for this statement.
 287    * @return A new <code>Statement</code> object.
 288    * @exception SQLException If an error occurs.
 289    * @see Statement
 290    * @see ResultSet
 291    */
 292   Statement createStatement(int resultSetType, int resultSetConcurrency)
 293     throws SQLException;
 294
 295   /**
 296    * This method creates a new <code>PreparedStatement</code> for the specified
 297    * SQL string.  This method is designed for use with parameterized
 298    * statements.  The specified result set type and concurrency will be used.
 299    * Valid values for these parameters are specified in the
 300    * <code>ResultSet</code> class.
 301    *
 302    * @param sql The SQL statement to use in creating this
 303    *            <code>PreparedStatement</code>.
 304    * @param resultSetType The type of result set to use for this statement.
 305    * @param resultSetConcurrency  The type of concurrency to be used in
 306    *                              the result set for this statement.
 307    * @return A new <code>PreparedStatement</code>.
 308    * @exception SQLException If an error occurs.
 309    * @see PreparedStatement
 310    * @see ResultSet
 311    */
 312   PreparedStatement prepareStatement(String sql, int resultSetType,
 313     int resultSetConcurrency) throws SQLException;
 314
 315   /**
 316    * This method creates a new <code>CallableStatement</code> for the
 317    * specified SQL string.  Thie method is designed to be used with
 318    * stored procedures.  The specified result set type and concurrency
 319    * will be used.  Valid values for these parameters are specified in the
 320    * <code>ResultSet</code> class.
 321    *
 322    * @param sql The SQL statement to use in creating this
 323    *            <code>PreparedStatement</code>.
 324    * @param resultSetType The type of result set to use for this statement.
 325    * @param resultSetConcurrency  The type of concurrency to be used in
 326    *                              the result set for this statement.
 327    * @return A new <code>CallableStatement</code>.
 328    * @exception SQLException If an error occurs.
 329    * @see CallableStatement
 330    * @see ResultSet
 331    */
 332   CallableStatement prepareCall(String sql, int resultSetType, int
 333     resultSetConcurrency) throws SQLException;
 334
 335   /**
 336    * This method returns the mapping of SQL types to Java classes
 337    * currently in use by this connection.  This mapping will have no
 338    * entries unless they have been manually added.
 339    *
 340    * @return The SQL type to Java class mapping.
 341    * @exception SQLException If an error occurs.
 342    */
 343   Map<String, Class<?>> getTypeMap() throws SQLException;
 344
 345   /**
 346    * This method sets the mapping table for SQL types to Java classes.
 347    * Any entries in this map override the defaults.
 348    *
 349    * @param map The new SQL mapping table.
 350    * @exception SQLException If an error occurs.
 351    */
 352   void setTypeMap(Map<String, Class<?>> map) throws SQLException;
 353
 354   /**
 355    * Sets the default holdability of <code>ResultSet</code>S that are created
 356    * from <code>Statement</code>S using this <code>Connection</code>.
 357    *
 358    * @param holdability The default holdability value to set, this must be one
 359    *                    of <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 360    *                    <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
 361    * @exception SQLException If an error occurs.
 362    * @see ResultSet
 363    * @since 1.4
 364    */
 365   void setHoldability(int holdability) throws SQLException;
 366
 367   /**
 368    * Gets the default holdability of <code>ResultSet</code>S that are created
 369    * from <code>Statement</code>S using this <code>Connection</code>.
 370    *
 371    * @return The current default holdability value, this must be one of
 372    *          <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 373    *          <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
 374    * @exception SQLException If an error occurs.
 375    * @see ResultSet
 376    * @since 1.4
 377    */
 378   int getHoldability() throws SQLException;
 379
 380   /**
 381    * Creates a new unnamed savepoint for this <code>Connection</code>
 382    *
 383    * @return The <code>Savepoint</code> object representing the savepoint.
 384    * @exception SQLException If an error occurs.
 385    * @since 1.4
 386    */
 387   Savepoint setSavepoint() throws SQLException;
 388
 389   /**
 390    * Creates a new savepoint with the specifiend name for this
 391    * <code>Connection</code>.
 392    *
 393    * @param name The name of the savepoint.
 394    * @return The <code>Savepoint</code> object representing the savepoint.
 395    * @exception SQLException If an error occurs.
 396    * @since 1.4
 397    */
 398   Savepoint setSavepoint(String name) throws SQLException;
 399
 400   /**
 401    * Undoes all changes made after the specified savepoint was set.
 402    *
 403    * @param savepoint The safepoint to roll back to.
 404    * @exception SQLException If an error occurs.
 405    * @since 1.4
 406    */
 407   void rollback(Savepoint savepoint) throws SQLException;
 408
 409   /**
 410    * Removes the specified savepoint from this <code>Connection</code>.
 411    * Refering to a savepoint after it was removed is an error and will throw an
 412    * SQLException.
 413    *
 414    * @param savepoint The savepoint to release.
 415    * @exception SQLException If an error occurs.
 416    * @since 1.4
 417    */
 418   void releaseSavepoint(Savepoint savepoint) throws SQLException;
 419
 420   /**
 421    * This method creates a new SQL statement with the specified type,
 422    * concurrency and holdability, instead of using the defaults.  Valid values
 423    * for these parameters are specified in the <code>ResultSet</code> class.
 424    *
 425    * @param resultSetType The type of result set to use for this statement.
 426    * @param resultSetConcurrency The type of concurrency to be used in
 427    *                             the result set for this statement.
 428    * @param resultSetHoldability The type of holdability to be usd in the
 429    *                             result set for this statement.
 430    * @return A new <code>Statement</code>
 431    * @exception SQLException If an error occurs.
 432    * @see ResultSet
 433    * @since 1.4
 434    */
 435   Statement createStatement(int resultSetType, int
 436       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 437
 438   /**
 439    * This method creates a new <code>PreparedStatement</code> for the specified
 440    * SQL string.  This method is designed for use with parameterized
 441    * statements.  The specified result set type, concurrency and holdability
 442    * will be used. Valid values for these parameters are specified in the
 443    * <code>ResultSet</code> class.
 444    *
 445    * @param sql The SQL statement to use in creating this
 446    *            <code>PreparedStatement</code>.
 447    * @param resultSetType The type of result set to use for this statement.
 448    * @param resultSetConcurrency The type of concurrency to be used in
 449    *                             the result set for this statement.
 450    * @param resultSetHoldability The type of holdability to be usd in the
 451    *                             result set for this statement.
 452    * @return A new <code>PreparedStatement</code>.
 453    * @exception SQLException If an error occurs.
 454    * @see PreparedStatement
 455    * @see ResultSet
 456    * @since 1.4
 457    */
 458   PreparedStatement prepareStatement(String sql, int resultSetType, int
 459       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 460
 461   /**
 462    * This method creates a new <code>CallableStatement</code> for the
 463    * specified SQL string.  Thie method is designed to be used with
 464    * stored procedures.  The specified result set type, concurrency and
 465    * holdability will be used.  Valid values for these parameters are specified
 466    * in the <code>ResultSet</code> class.
 467    *
 468    * @param sql The SQL statement to use in creating this
 469    *            <code>PreparedStatement</code>.
 470    * @param resultSetType The type of result set to use for this statement.
 471    * @param resultSetConcurrency The type of concurrency to be used in
 472    *                             the result set for this statement.
 473    * @param resultSetHoldability The type of holdability to be used in the
 474    *                             result set for this statement.
 475    * @return A new <code>CallableStatement</code>.
 476    * @exception SQLException If an error occurs.
 477    * @see CallableStatement
 478    * @see ResultSet
 479    * @since 1.4
 480    */
 481   CallableStatement prepareCall(String sql, int resultSetType, int
 482       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 483
 484   /**
 485    * @since 1.4
 486    */
 487   PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
 488       throws SQLException;
 489
 490   /**
 491    * @since 1.4
 492    */
 493   PreparedStatement prepareStatement(String sql, int[] columnIndexes)
 494       throws SQLException;
 495
 496   /**
 497    * @since 1.4
 498    */
 499   PreparedStatement prepareStatement(String sql, String[] columnNames)
 500       throws SQLException;
 501 }