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