Source for java.sql.Connection

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