GNU Classpath (0.20) | |
Frames | No Frames |
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: }
GNU Classpath (0.20) |