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