| GNU Classpath (0.95) | |
| 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: { 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: }
| GNU Classpath (0.95) |