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 */ createStatement()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 */ prepareStatement(String sql)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 */ prepareCall(String sql)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 */ nativeSQL(String sql)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 */ setAutoCommit(boolean autoCommit)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 */ getAutoCommit()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 */ commit()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 */ rollback()177 void rollback() throws SQLException; 178 179 /** 180 * This method immediately closes this database connection. 181 * 182 * @exception SQLException If an error occurs. 183 */ close()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 */ isClosed()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 */ getMetaData()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 */ setReadOnly(boolean readOnly)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 */ isReadOnly()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 */ setCatalog(String catalog)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 */ getCatalog()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 */ setTransactionIsolation(int level)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 */ getTransactionIsolation()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 */ getWarnings()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 */ clearWarnings()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 */ createStatement(int resultSetType, int resultSetConcurrency)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 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency)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 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency)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 */ getTypeMap()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 */ setTypeMap(Map<String, Class<?>> map)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 */ setHoldability(int holdability)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 */ getHoldability()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 */ setSavepoint()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 */ setSavepoint(String name)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 */ rollback(Savepoint savepoint)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 */ releaseSavepoint(Savepoint savepoint)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 */ createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)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 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)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 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)481 CallableStatement prepareCall(String sql, int resultSetType, int 482 resultSetConcurrency, int resultSetHoldability) throws SQLException; 483 484 /** 485 * @since 1.4 486 */ prepareStatement(String sql, int autoGeneratedKeys)487 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) 488 throws SQLException; 489 490 /** 491 * @since 1.4 492 */ prepareStatement(String sql, int[] columnIndexes)493 PreparedStatement prepareStatement(String sql, int[] columnIndexes) 494 throws SQLException; 495 496 /** 497 * @since 1.4 498 */ prepareStatement(String sql, String[] columnNames)499 PreparedStatement prepareStatement(String sql, String[] columnNames) 500 throws SQLException; 501 } 502