Source for java.sql.Connection

   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: {
  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 level 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 sql 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 sql 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 sql 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:    * @exception SQLException If an error occurs.
 157:    * @see #commit()
 158:    * @see #rollback()
 159:    */
 160:   boolean getAutoCommit() throws SQLException;
 161: 
 162:  /**
 163:   * This method commits any SQL statements executed on this connection since 
 164:   * the last commit or rollback.
 165:   *
 166:   * @exception SQLException If an error occurs.
 167:   */
 168:   void commit() throws SQLException;
 169: 
 170:   /**
 171:    * This method rolls back any SQL statements executed on this connection
 172:    * since the last commit or rollback.
 173:    *
 174:    * @exception SQLException If an error occurs.
 175:    */
 176:   void rollback() throws SQLException;
 177: 
 178:   /**
 179:    * This method immediately closes this database connection.
 180:    *
 181:    * @exception SQLException If an error occurs.
 182:    */
 183:   void close() throws SQLException;
 184: 
 185:   /**
 186:    * This method tests whether or not this connection has been closed. 
 187:    *
 188:    * @return <code>true</code> if the connection is closed, <code>false</code>
 189:    *         otherwise.
 190:    * @exception SQLException If an error occurs.
 191:    */
 192:   boolean isClosed() throws SQLException;
 193: 
 194:   /**
 195:    * This method returns the meta data for this database connection.
 196:    *
 197:    * @return The meta data for this database.
 198:    * @exception SQLException If an error occurs.
 199:    * @see DatabaseMetaData
 200:    */
 201:   DatabaseMetaData getMetaData() throws SQLException;
 202: 
 203:   /**
 204:    * This method turns read only mode on or off.  It may not be called while
 205:    * a transaction is in progress.
 206:    *
 207:    * @param readOnly <code>true</code> if this connection is read only,
 208:    *                 <code>false</code> otherwise.
 209:    * @exception SQLException If an error occurs.
 210:    */
 211:   void setReadOnly(boolean readOnly) throws SQLException;
 212: 
 213:   /**
 214:    * This method tests whether or not this connection is in read only mode.
 215:    *
 216:    * @return <code>true</code> if the connection is read only <code>false</code>
 217:    *         otherwise.
 218:    * @exception SQLException If an error occurs.
 219:    */
 220:   boolean isReadOnly() throws SQLException;
 221: 
 222:   /**
 223:    * This method sets the name of the catalog in use by this connection.
 224:    * Note that this method does nothing if catalogs are not supported by
 225:    * this database.
 226:    *
 227:    * @param catalog The name of the catalog to use for this connection.
 228:    * @exception SQLException If an error occurs.
 229:    */
 230:   void setCatalog(String catalog) throws SQLException;
 231: 
 232:   /**
 233:    * This method returns the name of the catalog in use by this connection,
 234:    * if any.
 235:    *
 236:    * @return The name of the catalog, or <code>null</code> if none 
 237:    *         exists or catalogs are not supported by this database.
 238:    * @exception SQLException If an error occurs.
 239:    */
 240:   String getCatalog() throws SQLException;
 241: 
 242:   /**
 243:    * This method sets the current transaction isolation mode.  This must
 244:    * be one of the constants defined in this interface.
 245:    *
 246:    * @param level The transaction isolation level.
 247:    * @exception SQLException If an error occurs.
 248:    */
 249:   void setTransactionIsolation(int level) throws SQLException;
 250: 
 251:   /**
 252:    * This method returns the current transaction isolation mode.  This will
 253:    * be one of the constants defined in this interface.
 254:    *
 255:    * @return The transaction isolation level.
 256:    * @exception SQLException If an error occurs.
 257:    */
 258:   int getTransactionIsolation() throws SQLException;
 259: 
 260:   /**
 261:    * This method returns the first warning that occurred on this connection,
 262:    * if any.  If there were any subsequence warnings, they will be chained
 263:    * to the first one.
 264:    *
 265:    * @return The first <code>SQLWarning</code> that occurred, or 
 266:    *         <code>null</code> if there have been no warnings.
 267:    * @exception SQLException If an error occurs.
 268:    */
 269:   SQLWarning getWarnings() throws SQLException;
 270: 
 271:   /**
 272:    * This method clears all warnings that have occurred on this connection.
 273:    *
 274:    * @exception SQLException If an error occurs.
 275:    */
 276:   void clearWarnings() throws SQLException;
 277: 
 278:   /**
 279:    * This method creates a new SQL statement with the specified type and
 280:    * concurrency.  Valid values for these parameters are specified in the
 281:    * <code>ResultSet</code> class.
 282:    *
 283:    * @param resultSetType The type of result set to use for this statement.
 284:    * @param resultSetConcurrency  The type of concurrency to be used in
 285:    *                              the result set for this statement.
 286:    * @return A new <code>Statement</code> object.
 287:    * @exception SQLException If an error occurs.
 288:    * @see Statement
 289:    * @see ResultSet
 290:    */
 291:   Statement createStatement(int resultSetType, int resultSetConcurrency)
 292:     throws SQLException;
 293: 
 294:   /**
 295:    * This method creates a new <code>PreparedStatement</code> for the specified
 296:    * SQL string.  This method is designed for use with parameterized
 297:    * statements.  The specified result set type and concurrency will be used.
 298:    * Valid values for these parameters are specified in the
 299:    * <code>ResultSet</code> class.
 300:    *
 301:    * @param sql The SQL statement to use in creating this 
 302:    *            <code>PreparedStatement</code>.
 303:    * @param resultSetType The type of result set to use for this statement.
 304:    * @param resultSetConcurrency  The type of concurrency to be used in
 305:    *                              the result set for this statement.
 306:    * @return A new <code>PreparedStatement</code>.
 307:    * @exception SQLException If an error occurs.
 308:    * @see PreparedStatement
 309:    * @see ResultSet
 310:    */
 311:   PreparedStatement prepareStatement(String sql, int resultSetType, 
 312:     int resultSetConcurrency) throws SQLException;
 313: 
 314:   /**
 315:    * This method creates a new <code>CallableStatement</code> for the 
 316:    * specified SQL string.  Thie method is designed to be used with
 317:    * stored procedures.  The specified result set type and concurrency
 318:    * will be used.  Valid values for these parameters are specified in the
 319:    * <code>ResultSet</code> class.
 320:    *
 321:    * @param sql The SQL statement to use in creating this 
 322:    *            <code>PreparedStatement</code>.
 323:    * @param resultSetType The type of result set to use for this statement.
 324:    * @param resultSetConcurrency  The type of concurrency to be used in
 325:    *                              the result set for this statement.
 326:    * @return A new <code>CallableStatement</code>.
 327:    * @exception SQLException If an error occurs.
 328:    * @see CallableStatement
 329:    * @see ResultSet
 330:    */
 331:   CallableStatement prepareCall(String sql, int resultSetType, int
 332:     resultSetConcurrency) throws SQLException;
 333: 
 334:   /**
 335:    * This method returns the mapping of SQL types to Java classes
 336:    * currently in use by this connection.  This mapping will have no
 337:    * entries unless they have been manually added.
 338:    *
 339:    * @return The SQL type to Java class mapping.
 340:    * @exception SQLException If an error occurs.
 341:    */
 342:   Map<String, Class<?>> getTypeMap() throws SQLException;
 343: 
 344:   /**
 345:    * This method sets the mapping table for SQL types to Java classes.
 346:    * Any entries in this map override the defaults.
 347:    *
 348:    * @param map The new SQL mapping table.
 349:    * @exception SQLException If an error occurs.
 350:    */
 351:   void setTypeMap(Map<String, Class<?>> map) throws SQLException;
 352: 
 353:   /**
 354:    * Sets the default holdability of <code>ResultSet</code>S that are created
 355:    * from <code>Statement</code>S using this <code>Connection</code>.
 356:    * 
 357:    * @param holdability The default holdability value to set, this must be one
 358:    *                    of <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 359:    *                    <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
 360:    * @exception SQLException If an error occurs.
 361:    * @see ResultSet
 362:    * @since 1.4
 363:    */
 364:   void setHoldability(int holdability) throws SQLException;
 365: 
 366:   /**
 367:    * Gets the default holdability of <code>ResultSet</code>S that are created
 368:    * from <code>Statement</code>S using this <code>Connection</code>.
 369:    * 
 370:    * @return The current default holdability value, this must be one of
 371:    *          <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 372:    *          <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
 373:    * @exception SQLException If an error occurs.
 374:    * @see ResultSet
 375:    * @since 1.4
 376:    */
 377:   int getHoldability() throws SQLException;
 378: 
 379:   /**
 380:    * Creates a new unnamed savepoint for this <code>Connection</code>
 381:    * 
 382:    * @return The <code>Savepoint</code> object representing the savepoint.
 383:    * @exception SQLException If an error occurs.
 384:    * @since 1.4
 385:    */
 386:   Savepoint setSavepoint() throws SQLException;
 387: 
 388:   /**
 389:    * Creates a new savepoint with the specifiend name for this
 390:    * <code>Connection</code>.
 391:    * 
 392:    * @param name The name of the savepoint.
 393:    * @return The <code>Savepoint</code> object representing the savepoint.
 394:    * @exception SQLException If an error occurs.
 395:    * @since 1.4
 396:    */
 397:   Savepoint setSavepoint(String name) throws SQLException;
 398: 
 399:   /**
 400:    * Undoes all changes made after the specified savepoint was set.
 401:    * 
 402:    * @param savepoint The safepoint to roll back to.
 403:    * @exception SQLException If an error occurs.
 404:    * @since 1.4
 405:    */
 406:   void rollback(Savepoint savepoint) throws SQLException;
 407: 
 408:   /**
 409:    * Removes the specified savepoint from this <code>Connection</code>.
 410:    * Refering to a savepoint after it was removed is an error and will throw an
 411:    * SQLException.
 412:    * 
 413:    * @param savepoint The savepoint to release.
 414:    * @exception SQLException If an error occurs.
 415:    * @since 1.4
 416:    */
 417:   void releaseSavepoint(Savepoint savepoint) throws SQLException;
 418: 
 419:   /**
 420:    * This method creates a new SQL statement with the specified type,
 421:    * concurrency and holdability, instead of using the defaults.  Valid values
 422:    * for these parameters are specified in the <code>ResultSet</code> class.
 423:    * 
 424:    * @param resultSetType The type of result set to use for this statement.
 425:    * @param resultSetConcurrency The type of concurrency to be used in
 426:    *                             the result set for this statement.
 427:    * @param resultSetHoldability The type of holdability to be usd in the
 428:    *                             result set for this statement.
 429:    * @return A new <code>Statement</code>
 430:    * @exception SQLException If an error occurs.
 431:    * @see ResultSet
 432:    * @since 1.4
 433:    */
 434:   Statement createStatement(int resultSetType, int
 435:       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 436: 
 437:   /**
 438:    * This method creates a new <code>PreparedStatement</code> for the specified
 439:    * SQL string.  This method is designed for use with parameterized
 440:    * statements.  The specified result set type, concurrency and holdability
 441:    * will be used. Valid values for these parameters are specified in the
 442:    * <code>ResultSet</code> class.
 443:    *
 444:    * @param sql The SQL statement to use in creating this 
 445:    *            <code>PreparedStatement</code>.
 446:    * @param resultSetType The type of result set to use for this statement.
 447:    * @param resultSetConcurrency The type of concurrency to be used in
 448:    *                             the result set for this statement.
 449:    * @param resultSetHoldability The type of holdability to be usd in the
 450:    *                             result set for this statement.
 451:    * @return A new <code>PreparedStatement</code>.
 452:    * @exception SQLException If an error occurs.
 453:    * @see PreparedStatement
 454:    * @see ResultSet
 455:    * @since 1.4
 456:    */
 457:   PreparedStatement prepareStatement(String sql, int resultSetType, int
 458:       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 459: 
 460:   /**
 461:    * This method creates a new <code>CallableStatement</code> for the 
 462:    * specified SQL string.  Thie method is designed to be used with
 463:    * stored procedures.  The specified result set type, concurrency and
 464:    * holdability will be used.  Valid values for these parameters are specified
 465:    * in the <code>ResultSet</code> class.
 466:    *
 467:    * @param sql The SQL statement to use in creating this 
 468:    *            <code>PreparedStatement</code>.
 469:    * @param resultSetType The type of result set to use for this statement.
 470:    * @param resultSetConcurrency The type of concurrency to be used in
 471:    *                             the result set for this statement.
 472:    * @param resultSetHoldability The type of holdability to be used in the
 473:    *                             result set for this statement.
 474:    * @return A new <code>CallableStatement</code>.
 475:    * @exception SQLException If an error occurs.
 476:    * @see CallableStatement
 477:    * @see ResultSet
 478:    * @since 1.4
 479:    */
 480:   CallableStatement prepareCall(String sql, int resultSetType, int
 481:       resultSetConcurrency, int resultSetHoldability) throws SQLException;
 482: 
 483:   /**
 484:    * @since 1.4
 485:    */
 486:   PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
 487:       throws SQLException;
 488: 
 489:   /**
 490:    * @since 1.4
 491:    */
 492:   PreparedStatement prepareStatement(String sql, int[] columnIndexes)
 493:       throws SQLException;
 494: 
 495:   /**
 496:    * @since 1.4
 497:    */
 498:   PreparedStatement prepareStatement(String sql, String[] columnNames)
 499:       throws SQLException;
 500: }