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:   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: }