1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.sql; 19 20 import java.util.Map; 21 22 /** 23 * A connection represents a link from a Java application to a database. All SQL 24 * statements and results are returned within the context of a connection. 25 * Database statements that are executed within this context form a 26 * database session which forms one or more closed transactions. Especially in 27 * distributed applications, multiple concurrent connections may exist accessing 28 * the same values of the database. which may lead to the following phenomena 29 * (referred to as <i>transaction isolation levels</i>): 30 * <ul> 31 * <li><i>dirty reads</i>:<br> 32 * reading values from table rows that are not committed.</br></li> 33 * <li><i>non-repeatable reads</i>:<br> 34 * reading table rows more than once in a transaction but getting back different 35 * data because other transactions have altered the rows between the reads.</br></li> 36 * <li><i>phantom reads</i>:<br> 37 * retrieving additional "phantom" rows in the course of repeated table reads 38 * because other transactions have inserted additional rows that satisfy an 39 * SQL {@code WHERE} clause</br></li> 40 * </ul> 41 */ 42 public interface Connection { 43 44 /** 45 * A constant indicating that transactions are not supported. 46 */ 47 public static final int TRANSACTION_NONE = 0; 48 49 /** 50 * No <i>dirty reads</i> are permitted, therefore transactions may not read 51 * a row containing uncommitted values - but does not prevent an application 52 * from <i>non-repeatable reads</i> and <i>phantom reads</i>. 53 */ 54 public static final int TRANSACTION_READ_COMMITTED = 2; 55 56 /** 57 * In the case that reading uncommitted values is allowed, the following 58 * incidents may happen which may lead to an invalid results: 59 * <ul> 60 * <li><i>dirty reads</i></li> 61 * <li><i>non-repeatable reads</i></li> 62 * <li><i>phantom reads</i></li> 63 * </ul> 64 */ 65 public static final int TRANSACTION_READ_UNCOMMITTED = 1; 66 67 /** 68 * A constant indicating that <i>dirty reads</i> and <i>non-repeatable 69 * reads</i> are <b>prevented</b> but <i>phantom reads</i> can occur. 70 */ 71 public static final int TRANSACTION_REPEATABLE_READ = 4; 72 73 /** 74 * The constant that indicates that the following incidents are <b>all 75 * prevented</b> (the opposite of {@link #TRANSACTION_READ_UNCOMMITTED}): 76 * <ul> 77 * <li><i>dirty reads</i></li> 78 * <li><i>non-repeatable reads</i></li> 79 * <li><i>phantom reads</i></li> 80 * </ul> 81 */ 82 public static final int TRANSACTION_SERIALIZABLE = 8; 83 84 /** 85 * Discards all warnings that may have arisen for this connection. 86 * Subsequent calls to {@link #getWarnings()} will return {@code null} 87 * up until a new warning condition occurs. 88 * 89 * @throws SQLException 90 * if there is a problem accessing the database. 91 */ clearWarnings()92 public void clearWarnings() throws SQLException; 93 94 /** 95 * Causes the instant release of all database and driver connection 96 * resources associated with this object. Any subsequent invocations of this 97 * method have no effect. 98 * <p> 99 * It is strongly recommended that all connections are closed before they 100 * are dereferenced by the application ready for garbage collection. 101 * Although the {@code finalize} method of the connection closes the 102 * connection before garbage collection takes place, it is not advisable to 103 * leave the {@code close} operation to take place in this way. Mainly 104 * because undesired side-effects may appear. 105 * 106 * @throws SQLException 107 * if there is a problem accessing the database. 108 */ close()109 public void close() throws SQLException; 110 111 /** 112 * Commits all of the changes made since the last {@code commit} or 113 * {@code rollback} of the associated transaction. All locks in the database 114 * held by this connection are also relinquished. Calling this operation on 115 * connection objects in {@code auto-commit} mode leads to an error. 116 * 117 * @throws SQLException 118 * if there is a problem accessing the database or if the target 119 * connection instance is in auto-commit mode. 120 */ commit()121 public void commit() throws SQLException; 122 123 /** 124 * Returns a new instance of {@code Statement} for issuing SQL commands to 125 * the remote database. 126 * <p> 127 * {@code ResultSets} generated by the returned statement will default to 128 * type {@code ResultSet.TYPE_FORWARD_ONLY} and concurrency level {@code 129 * ResultSet.CONCUR_READ_ONLY}. 130 * 131 * @return a {@code Statement} object with default settings. 132 * @throws SQLException 133 * if there is a problem accessing the database. 134 * @see ResultSet 135 */ createStatement()136 public Statement createStatement() throws SQLException; 137 138 /** 139 * Returns a new instance of {@code Statement} whose associated {@code 140 * ResultSet}s have the characteristics specified in the type and 141 * concurrency arguments. 142 * 143 * @param resultSetType 144 * one of the following type specifiers: 145 * <ul> 146 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE} </li> <li> 147 * {@link ResultSet#TYPE_SCROLL_INSENSITIVE} </li> <li> 148 * {@link ResultSet#TYPE_FORWARD_ONLY}</li> 149 * </ul> 150 * @param resultSetConcurrency 151 * one of the following concurrency mode specifiers: 152 * <ul> 153 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> <li> 154 * {@link ResultSet#CONCUR_READ_ONLY}</li> 155 * </ul> 156 * @return a new instance of {@code Statement} capable of manufacturing 157 * {@code ResultSet}s that satisfy the specified {@code 158 * resultSetType} and {@code resultSetConcurrency} values. 159 * @throws SQLException 160 * if there is a problem accessing the database 161 */ createStatement(int resultSetType, int resultSetConcurrency)162 public Statement createStatement(int resultSetType, int resultSetConcurrency) 163 throws SQLException; 164 165 /** 166 * Returns a new instance of {@code Statement} whose associated 167 * {@code ResultSet}s will have the characteristics specified in the 168 * type, concurrency and holdability arguments. 169 * 170 * @param resultSetType 171 * one of the following type specifiers: 172 * <ul> 173 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li> 174 * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li> 175 * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li> 176 * </ul> 177 * @param resultSetConcurrency 178 * one of the following concurrency mode specifiers: 179 * <ul> 180 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> 181 * <li>{@link ResultSet#CONCUR_READ_ONLY}</li> 182 * </ul> 183 * @param resultSetHoldability 184 * one of the following holdability mode specifiers: 185 * <ul> 186 * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> 187 * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li> 188 * </ul> 189 * @return a new instance of {@code Statement} capable of 190 * manufacturing {@code ResultSet}s that satisfy the 191 * specified {@code resultSetType}, 192 * {@code resultSetConcurrency} and 193 * {@code resultSetHoldability} values. 194 * @throws SQLException 195 * if there is a problem accessing the database. 196 */ createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)197 public Statement createStatement(int resultSetType, 198 int resultSetConcurrency, int resultSetHoldability) 199 throws SQLException; 200 201 /** 202 * Returns a {@code boolean} indicating whether or not this connection is in 203 * the {@code auto-commit} operating mode. 204 * 205 * @return {@code true} if {@code auto-commit} is on, otherwise {@code 206 * false}. 207 * @throws SQLException 208 * if there is a problem accessing the database. 209 */ getAutoCommit()210 public boolean getAutoCommit() throws SQLException; 211 212 /** 213 * Gets this {@code Connection} object's current catalog name. 214 * 215 * @return the catalog name. {@code null} if there is no catalog 216 * name. 217 * @throws SQLException 218 * if there is a problem accessing the database. 219 */ getCatalog()220 public String getCatalog() throws SQLException; 221 222 /** 223 * Returns the holdability property that any {@code ResultSet} produced by 224 * this instance will have. 225 * 226 * @return one of the following holdability mode specifiers: 227 * <ul> 228 * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> <li> 229 * {@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li> 230 * </ul> 231 * @throws SQLException 232 * if there is a problem accessing the a database. 233 */ getHoldability()234 public int getHoldability() throws SQLException; 235 236 /** 237 * Gets the metadata about the database referenced by this connection. The 238 * returned {@code DatabaseMetaData} describes the database topography, 239 * available stored procedures, SQL syntax and so on. 240 * 241 * @return a {@code DatabaseMetaData} object containing the database 242 * description. 243 * @throws SQLException 244 * if there is a problem accessing the a database. 245 */ getMetaData()246 public DatabaseMetaData getMetaData() throws SQLException; 247 248 /** 249 * Returns the transaction isolation level for this connection. 250 * 251 * @return the transaction isolation value. 252 * @throws SQLException 253 * if there is a problem accessing the database. 254 * @see #TRANSACTION_NONE 255 * @see #TRANSACTION_READ_COMMITTED 256 * @see #TRANSACTION_READ_UNCOMMITTED 257 * @see #TRANSACTION_REPEATABLE_READ 258 * @see #TRANSACTION_SERIALIZABLE 259 */ getTransactionIsolation()260 public int getTransactionIsolation() throws SQLException; 261 262 /** 263 * Returns the type mapping associated with this {@code Connection} object. 264 * The type mapping must be set on the application level. 265 * 266 * @return the Type Map as a {@code java.util.Map}. 267 * @throws SQLException 268 * if there is a problem accessing the database. 269 */ getTypeMap()270 public Map<String, Class<?>> getTypeMap() throws SQLException; 271 272 /** 273 * Gets the first instance of any {@code SQLWarning} objects that may have 274 * been created in the use of this connection. If at least one warning has 275 * occurred then this operation returns the first one reported. A {@code 276 * null} indicates that no warnings have occurred. 277 * <p> 278 * By invoking the {@link SQLWarning#getNextWarning()} method of the 279 * returned {@code SQLWarning} object it is possible to obtain all of 280 * this connection's warning objects. 281 * 282 * @return the first warning as an SQLWarning object (may be {@code null}). 283 * @throws SQLException 284 * if there is a problem accessing the database or if the call 285 * has been made on a connection which has been previously 286 * closed. 287 */ getWarnings()288 public SQLWarning getWarnings() throws SQLException; 289 290 /** 291 * Returns a {@code boolean} indicating whether or not this connection is in 292 * the {@code closed} state. The {@code closed} state may be entered into as 293 * a consequence of a successful invocation of the {@link #close()} method 294 * or else if an error has occurred that prevents the connection from 295 * functioning normally. 296 * 297 * @return {@code true} if closed, otherwise {@code false}. 298 * @throws SQLException 299 * if there is a problem accessing the database. 300 */ isClosed()301 public boolean isClosed() throws SQLException; 302 303 /** 304 * Returns a {@code boolean} indicating whether or not this connection is 305 * currently in the {@code read-only} state. 306 * 307 * @return {@code true} if in read-only state, otherwise {@code false}. 308 * @throws SQLException 309 * if there is a problem accessing the database. 310 */ isReadOnly()311 public boolean isReadOnly() throws SQLException; 312 313 /** 314 * Returns a string representation of the input SQL statement 315 * {@code sql} expressed in the underlying system's native SQL 316 * syntax. 317 * 318 * @param sql 319 * the JDBC form of an SQL statement. 320 * @return the SQL statement in native database format. 321 * @throws SQLException 322 * if there is a problem accessing the database 323 */ nativeSQL(String sql)324 public String nativeSQL(String sql) throws SQLException; 325 326 /** 327 * Returns a new instance of {@code CallableStatement} that may be used for 328 * making stored procedure calls to the database. 329 * 330 * @param sql 331 * the SQL statement that calls the stored function 332 * @return a new instance of {@code CallableStatement} representing the SQL 333 * statement. {@code ResultSet}s emitted from this {@code 334 * CallableStatement} will default to type 335 * {@link ResultSet#TYPE_FORWARD_ONLY} and concurrency 336 * {@link ResultSet#CONCUR_READ_ONLY}. 337 * @throws SQLException 338 * if a problem occurs accessing the database. 339 */ prepareCall(String sql)340 public CallableStatement prepareCall(String sql) throws SQLException; 341 342 /** 343 * Returns a new instance of {@code CallableStatement} that may be used for 344 * making stored procedure calls to the database. {@code ResultSet}s emitted 345 * from this {@code CallableStatement} will satisfy the specified {@code 346 * resultSetType} and {@code resultSetConcurrency} values. 347 * 348 * @param sql 349 * the SQL statement 350 * @param resultSetType 351 * one of the following type specifiers: 352 * <ul> 353 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li> 354 * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li> 355 * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li> 356 * </ul> 357 * @param resultSetConcurrency 358 * one of the following concurrency mode specifiers: 359 * <ul> 360 * <li>{@link ResultSet#CONCUR_READ_ONLY}</li> 361 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> 362 * </ul> 363 * @return a new instance of {@code CallableStatement} representing the 364 * precompiled SQL statement. {@code ResultSet}s emitted from this 365 * {@code CallableStatement} will satisfy the specified {@code 366 * resultSetType} and {@code resultSetConcurrency} values. 367 * @throws SQLException 368 * if a problem occurs accessing the database 369 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency)370 public CallableStatement prepareCall(String sql, int resultSetType, 371 int resultSetConcurrency) throws SQLException; 372 373 /** 374 * Returns a new instance of {@code CallableStatement} that may be used for 375 * making stored procedure calls to the database. {@code ResultSet}s created 376 * from this {@code CallableStatement} will have characteristics determined 377 * by the specified type, concurrency and holdability arguments. 378 * 379 * @param sql 380 * the SQL statement 381 * @param resultSetType 382 * one of the following type specifiers: 383 * <ul> 384 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li> 385 * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li> 386 * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li> 387 * </ul> 388 * @param resultSetConcurrency 389 * one of the following concurrency mode specifiers: 390 * <ul> 391 * <li>{@link ResultSet#CONCUR_READ_ONLY}</li> 392 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> 393 * </ul> 394 * @param resultSetHoldability 395 * one of the following holdability mode specifiers: 396 * <ul> 397 * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> 398 * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li> 399 * </ul> 400 * @return a new instance of {@code CallableStatement} representing the 401 * precompiled SQL statement. {@code ResultSet}s emitted from this 402 * {@code CallableStatement} will satisfy the specified {@code 403 * resultSetType}, {@code resultSetConcurrency} and {@code 404 * resultSetHoldability} values. 405 * @throws SQLException 406 * if a problem occurs accessing the database. 407 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)408 public CallableStatement prepareCall(String sql, int resultSetType, 409 int resultSetConcurrency, int resultSetHoldability) 410 throws SQLException; 411 412 /** 413 * Returns a new instance of {@code PreparedStatement} that may be used any 414 * number of times to execute parameterized requests on the database server. 415 * <p> 416 * Subject to JDBC driver support, this operation will attempt to send the 417 * precompiled version of the statement to the database. If 418 * the driver does not support precompiled statements, the statement will 419 * not reach the database server until it is executed. This distinction 420 * determines the moment when {@code SQLException}s get raised. 421 * <p> 422 * By default, {@code ResultSet}s from the returned object will be 423 * {@link ResultSet#TYPE_FORWARD_ONLY} type with a 424 * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency. 425 * 426 * @param sql 427 * the SQL statement. 428 * @return the {@code PreparedStatement} containing the supplied SQL 429 * statement. 430 * @throws SQLException 431 * if there is a problem accessing the database. 432 */ prepareStatement(String sql)433 public PreparedStatement prepareStatement(String sql) throws SQLException; 434 435 /** 436 * Creates a default {@code PreparedStatement} that can retrieve 437 * automatically generated keys. Parameter {@code autoGeneratedKeys} may be 438 * used to tell the driver whether such keys should be made accessible. 439 * This is only relevant when the {@code sql} statement is an {@code insert} 440 * statement. 441 * <p> 442 * An SQL statement which may have {@code IN} parameters can be stored and 443 * precompiled in a {@code PreparedStatement}. The {@code PreparedStatement} 444 * can then be then be used to execute the statement multiple times in an 445 * efficient way. 446 * <p> 447 * Subject to JDBC driver support, this operation will attempt to send the 448 * precompiled version of the statement to the database. If 449 * the driver does not support precompiled statements, the statement will 450 * not reach the database server until it is executed. This distinction 451 * determines the moment when {@code SQLException}s get raised. 452 * <p> 453 * By default, {@code ResultSet}s from the returned object will be 454 * {@link ResultSet#TYPE_FORWARD_ONLY} type with a 455 * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency. 456 * 457 * @param sql 458 * the SQL statement. 459 * @param autoGeneratedKeys 460 * one of the following generated key options: 461 * <ul> 462 * <li>{@link Statement#RETURN_GENERATED_KEYS}</li> 463 * <li>{@link Statement#NO_GENERATED_KEYS}</li> 464 * </ul> 465 * @return a new {@code PreparedStatement} instance representing the input 466 * SQL statement. 467 * @throws SQLException 468 * if there is a problem accessing the database. 469 */ prepareStatement(String sql, int autoGeneratedKeys)470 public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) 471 throws SQLException; 472 473 /** 474 * Creates a default {@code PreparedStatement} that can retrieve the 475 * auto-generated keys designated by a supplied array. If {@code sql} is an 476 * SQL {@code INSERT} statement, the parameter {@code columnIndexes} is expected 477 * to hold the index values for each column in the statement's intended 478 * database table containing the autogenerated-keys of interest. Otherwise 479 * {@code columnIndexes} is ignored. 480 * <p> 481 * Subject to JDBC driver support, this operation will attempt to send the 482 * precompiled version of the statement to the database. If 483 * the driver does not support precompiled statements, the statement will 484 * not reach the database server until it is executed. This distinction 485 * determines the moment when {@code SQLException}s get raised. 486 * <p> 487 * By default, {@code ResultSet}s from the returned object will be 488 * {@link ResultSet#TYPE_FORWARD_ONLY} type with a 489 * {@link ResultSet#CONCUR_READ_ONLY} concurrency mode. 490 * 491 * @param sql 492 * the SQL statement. 493 * @param columnIndexes 494 * the indexes of the columns for which auto-generated keys 495 * should be made available. 496 * @return the PreparedStatement containing the supplied SQL statement. 497 * @throws SQLException 498 * if a problem occurs accessing the database. 499 */ prepareStatement(String sql, int[] columnIndexes)500 public PreparedStatement prepareStatement(String sql, int[] columnIndexes) 501 throws SQLException; 502 503 /** 504 * Creates a {@code PreparedStatement} that generates {@code ResultSet}s 505 * with the specified values of {@code resultSetType} and {@code 506 * resultSetConcurrency}. 507 * 508 * @param sql 509 * the SQL statement. It can contain one or more {@code '?'} 510 * {@code IN} parameter placeholders. 511 * @param resultSetType 512 * one of the following type specifiers: 513 * <ul> 514 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li> 515 * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li> 516 * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li> 517 * </ul> 518 * @param resultSetConcurrency 519 * one of the following concurrency mode specifiers: 520 * <ul> 521 * <li>{@link ResultSet#CONCUR_READ_ONLY}</li> 522 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> 523 * </ul> 524 * @return a new instance of {@code PreparedStatement} containing the SQL 525 * statement {@code sql}. {@code ResultSet}s emitted from this 526 * {@code PreparedStatement} will satisfy the specified {@code 527 * resultSetType} and {@code resultSetConcurrency} values. 528 * @throws SQLException 529 * if a problem occurs accessing the database. 530 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency)531 public PreparedStatement prepareStatement(String sql, int resultSetType, 532 int resultSetConcurrency) throws SQLException; 533 534 /** 535 * Creates a {@code PreparedStatement} that generates {@code ResultSet}s 536 * with the specified type, concurrency and holdability 537 * 538 * @param sql 539 * the SQL statement. It can contain one or more {@code '?' IN} 540 * parameter placeholders. 541 * @param resultSetType 542 * one of the following type specifiers: 543 * <ul> 544 * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li> 545 * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li> 546 * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li> 547 * </ul> 548 * @param resultSetConcurrency 549 * one of the following concurrency mode specifiers: 550 * <ul> 551 * <li>{@link ResultSet#CONCUR_READ_ONLY}</li> 552 * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> 553 * </ul> 554 * @param resultSetHoldability 555 * one of the following holdability mode specifiers: 556 * <ul> 557 * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> 558 * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li> 559 * </ul> 560 * @return a new instance of {@code PreparedStatement} containing the SQL 561 * statement {@code sql}. {@code ResultSet}s emitted from this 562 * {@code PreparedStatement} will satisfy the specified {@code 563 * resultSetType}, {@code resultSetConcurrency} and {@code 564 * resultSetHoldability} values. 565 * @throws SQLException 566 * if a problem occurs accessing the database. 567 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)568 public PreparedStatement prepareStatement(String sql, int resultSetType, 569 int resultSetConcurrency, int resultSetHoldability) 570 throws SQLException; 571 572 /** 573 * Creates a default {@code PreparedStatement} that can retrieve the 574 * auto-generated keys designated by a supplied array. If {@code sql} is an 575 * SQL {@code INSERT} statement, {@code columnNames} is expected to hold the 576 * names of each column in the statement's associated database table 577 * containing the autogenerated-keys of interest. Otherwise {@code 578 * columnNames} is ignored. 579 * <p> 580 * Subject to JDBC driver support, this operation will attempt to send the 581 * precompiled version of the statement to the database. Alternatively, if 582 * the driver is not capable of handling precompiled statements, the 583 * statement will not reach the database server until it is executed. This 584 * will have a bearing on precisely <i>when</i> {@code SQLException} 585 * instances get raised. 586 * <p> 587 * By default, ResultSets from the returned object will be 588 * {@link ResultSet#TYPE_FORWARD_ONLY} type with a 589 * {@link ResultSet#CONCUR_READ_ONLY} concurrency mode. 590 * 591 * @param sql 592 * the SQL statement. 593 * @param columnNames 594 * the names of the columns for which auto-generated keys should 595 * be made available. 596 * @return the PreparedStatement containing the supplied SQL statement. 597 * @throws SQLException 598 * if a problem occurs accessing the database. 599 */ prepareStatement(String sql, String[] columnNames)600 public PreparedStatement prepareStatement(String sql, String[] columnNames) 601 throws SQLException; 602 603 /** 604 * Releases the specified {@code savepoint} from the present transaction. Once removed, 605 * the {@code Savepoint} is considered invalid and should not be referenced 606 * further. 607 * 608 * @param savepoint 609 * the object targeted for removal. 610 * @throws SQLException 611 * if there is a problem with accessing the database or if 612 * {@code savepoint} is considered not valid in this 613 * transaction. 614 */ releaseSavepoint(Savepoint savepoint)615 public void releaseSavepoint(Savepoint savepoint) throws SQLException; 616 617 /** 618 * Rolls back all updates made so far in this transaction and 619 * relinquishes all acquired database locks. It is an error to invoke this 620 * operation when in auto-commit mode. 621 * 622 * @throws SQLException 623 * if there is a problem with the database or if the method is 624 * called while in auto-commit mode of operation. 625 */ rollback()626 public void rollback() throws SQLException; 627 628 /** 629 * Undoes all changes made after the supplied {@code Savepoint} object was 630 * set. This method should only be used when auto-commit mode is disabled. 631 * 632 * @param savepoint 633 * the Savepoint to roll back to 634 * @throws SQLException 635 * if there is a problem accessing the database. 636 */ rollback(Savepoint savepoint)637 public void rollback(Savepoint savepoint) throws SQLException; 638 639 /** 640 * Sets this connection's auto-commit mode {@code on} or {@code off}. 641 * <p> 642 * Putting a Connection into auto-commit mode means that all associated SQL 643 * statements are run and committed as separate transactions. 644 * By contrast, setting auto-commit to {@code off} means that associated SQL 645 * statements get grouped into transactions that need to be completed by 646 * explicit calls to either the {@link #commit()} or {@link #rollback()} 647 * methods. 648 * <p> 649 * Auto-commit is the default mode for new connection instances. 650 * <p> 651 * When in this mode, commits will automatically occur upon successful SQL 652 * statement completion or upon successful completion of an execute. 653 * Statements are not considered successfully completed until all associated 654 * {@code ResultSet}s and output parameters have been obtained or closed. 655 * <p> 656 * Calling this operation during an uncommitted transaction will result in 657 * it being committed. 658 * 659 * @param autoCommit 660 * {@code boolean} indication of whether to put the target 661 * connection into auto-commit mode ({@code true}) or not ( 662 * {@code false}). 663 * @throws SQLException 664 * if there is a problem accessing the database. 665 */ setAutoCommit(boolean autoCommit)666 public void setAutoCommit(boolean autoCommit) throws SQLException; 667 668 /** 669 * Sets the catalog name for this connection. This is used to select a 670 * subspace of the database for future work. If the driver does not support 671 * catalog names, this method is ignored. 672 * 673 * @param catalog 674 * the catalog name to use. 675 * @throws SQLException 676 * if there is a problem accessing the database. 677 */ setCatalog(String catalog)678 public void setCatalog(String catalog) throws SQLException; 679 680 /** 681 * Sets the holdability of the {@code ResultSet}s created by this Connection. 682 * 683 * @param holdability 684 * one of the following holdability mode specifiers: 685 * <ul> 686 * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li> 687 * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> 688 * <li> 689 * </ul> 690 * @throws SQLException 691 * if there is a problem accessing the database 692 */ setHoldability(int holdability)693 public void setHoldability(int holdability) throws SQLException; 694 695 /** 696 * Sets this connection to read-only mode. 697 * <p> 698 * This serves as a hint to the driver, which can enable database 699 * optimizations. 700 * 701 * @param readOnly 702 * {@code true} to set the Connection to read only mode. {@code 703 * false} disables read-only mode. 704 * @throws SQLException 705 * if there is a problem accessing the database. 706 */ setReadOnly(boolean readOnly)707 public void setReadOnly(boolean readOnly) throws SQLException; 708 709 /** 710 * Creates an unnamed {@code Savepoint} in the current transaction. 711 * 712 * @return a {@code Savepoint} object for this savepoint. 713 * @throws SQLException 714 * if there is a problem accessing the database. 715 */ setSavepoint()716 public Savepoint setSavepoint() throws SQLException; 717 718 /** 719 * Creates a named {@code Savepoint} in the current transaction. 720 * 721 * @param name 722 * the name to use for the new {@code Savepoint}. 723 * @return a {@code Savepoint} object for this savepoint. 724 * @throws SQLException 725 * if there is a problem accessing the database. 726 */ setSavepoint(String name)727 public Savepoint setSavepoint(String name) throws SQLException; 728 729 /** 730 * Sets the transaction isolation level for this Connection. 731 * <p> 732 * If this method is called during a transaction, the results are 733 * implementation defined. 734 * 735 * @param level 736 * the new transaction isolation level to use from the following 737 * list of possible values: 738 * <ul> 739 * <li>{@link #TRANSACTION_READ_COMMITTED} 740 * <li>{@link #TRANSACTION_READ_UNCOMMITTED} 741 * <li>{@link #TRANSACTION_REPEATABLE_READ} 742 * <li>{@link #TRANSACTION_SERIALIZABLE} 743 * </ul> 744 * @throws SQLException 745 * if there is a problem with the database or if the value of 746 * {@code level} is not one of the expected constant values. 747 */ setTransactionIsolation(int level)748 public void setTransactionIsolation(int level) throws SQLException; 749 750 /** 751 * Sets the {@code TypeMap} for this connection. The input {@code map} 752 * should contain mappings between complex Java and SQL types. 753 * 754 * @param map 755 * the new type map. 756 * @throws SQLException 757 * if there is a problem accessing the database or if {@code 758 * map} is not an instance of {@link Map}. 759 */ setTypeMap(Map<String, Class<?>> map)760 public void setTypeMap(Map<String, Class<?>> map) throws SQLException; 761 } 762