001/* Connection.java -- Manage a database connection. 002 Copyright (C) 1999, 2000, 2002, 2006 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.sql; 040 041import java.util.Map; 042 043/** 044 * This interface provides methods for managing a connection to a database. 045 * 046 * @author Aaron M. Renn (arenn@urbanophile.com) 047 */ 048public interface Connection 049 extends AutoCloseable 050{ 051 /** 052 * This transaction isolation level indicates that transactions are not 053 * supported. 054 */ 055 int TRANSACTION_NONE = 0; 056 057 /** 058 * This transaction isolation level indicates that one transaction can 059 * read modifications by other transactions before the other transactions 060 * have committed their changes. This could result in invalid reads. 061 */ 062 int TRANSACTION_READ_UNCOMMITTED = 1; 063 064 /** 065 * This transaction isolation level indicates that only committed data from 066 * other transactions will be read. If a transaction reads a row, then 067 * another transaction commits a change to that row, the first transaction 068 * would retrieve the changed row on subsequent reads of the same row. 069 */ 070 int TRANSACTION_READ_COMMITTED = 2; 071 072 /** 073 * This transaction isolation level indicates that only committed data from 074 * other transactions will be read. It also ensures that data read from 075 * a row will not be different on a subsequent read even if another 076 * transaction commits a change. 077 */ 078 int TRANSACTION_REPEATABLE_READ = 4; 079 080 /** 081 * This transaction isolation level indicates that only committed data from 082 * other transactions will be read. It also ensures that data read from 083 * a row will not be different on a subsequent read even if another 084 * transaction commits a change. Additionally, rows modified by other 085 * transactions will not affect the result set returned during subsequent 086 * executions of the same WHERE clause in this transaction. 087 */ 088 int TRANSACTION_SERIALIZABLE = 8; 089 090 /** 091 * This method creates a new SQL statement. The default result set type 092 * and concurrency will be used. 093 * 094 * @return A new <code>Statement</code> object. 095 * @exception SQLException If an error occurs. 096 * @see Statement 097 */ 098 Statement createStatement() throws SQLException; 099 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}