1 /* 2 * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.sql; 27 28 import java.util.Properties; 29 import java.util.concurrent.Executor; 30 31 /** 32 * <P>A connection (session) with a specific 33 * database. SQL statements are executed and results are returned 34 * within the context of a connection. 35 * <P> 36 * A <code>Connection</code> object's database is able to provide information 37 * describing its tables, its supported SQL grammar, its stored 38 * procedures, the capabilities of this connection, and so on. This 39 * information is obtained with the <code>getMetaData</code> method. 40 * 41 * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications 42 * should use the appropriate <code>Connection</code> method such as 43 * <code>setAutoCommit</code> or <code>setTransactionIsolation</code>. 44 * Applications should not invoke SQL commands directly to change the connection's 45 * configuration when there is a JDBC method available. By default a <code>Connection</code> object is in 46 * auto-commit mode, which means that it automatically commits changes 47 * after executing each statement. If auto-commit mode has been 48 * disabled, the method <code>commit</code> must be called explicitly in 49 * order to commit changes; otherwise, database changes will not be saved. 50 * <P> 51 * A new <code>Connection</code> object created using the JDBC 2.1 core API 52 * has an initially empty type map associated with it. A user may enter a 53 * custom mapping for a UDT in this type map. 54 * When a UDT is retrieved from a data source with the 55 * method <code>ResultSet.getObject</code>, the <code>getObject</code> method 56 * will check the connection's type map to see if there is an entry for that 57 * UDT. If so, the <code>getObject</code> method will map the UDT to the 58 * class indicated. If there is no entry, the UDT will be mapped using the 59 * standard mapping. 60 * <p> 61 * A user may create a new type map, which is a <code>java.util.Map</code> 62 * object, make an entry in it, and pass it to the <code>java.sql</code> 63 * methods that can perform custom mapping. In this case, the method 64 * will use the given type map instead of the one associated with 65 * the connection. 66 * <p> 67 * For example, the following code fragment specifies that the SQL 68 * type <code>ATHLETES</code> will be mapped to the class 69 * <code>Athletes</code> in the Java programming language. 70 * The code fragment retrieves the type map for the <code>Connection 71 * </code> object <code>con</code>, inserts the entry into it, and then sets 72 * the type map with the new entry as the connection's type map. 73 * <pre> 74 * java.util.Map map = con.getTypeMap(); 75 * map.put("mySchemaName.ATHLETES", Class.forName("Athletes")); 76 * con.setTypeMap(map); 77 * </pre> 78 * 79 * @see DriverManager#getConnection 80 * @see Statement 81 * @see ResultSet 82 * @see DatabaseMetaData 83 * @since 1.1 84 */ 85 public interface Connection extends Wrapper, AutoCloseable { 86 87 /** 88 * Creates a <code>Statement</code> object for sending 89 * SQL statements to the database. 90 * SQL statements without parameters are normally 91 * executed using <code>Statement</code> objects. If the same SQL statement 92 * is executed many times, it may be more efficient to use a 93 * <code>PreparedStatement</code> object. 94 * <P> 95 * Result sets created using the returned <code>Statement</code> 96 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 97 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 98 * The holdability of the created result sets can be determined by 99 * calling {@link #getHoldability}. 100 * 101 * @return a new default <code>Statement</code> object 102 * @exception SQLException if a database access error occurs 103 * or this method is called on a closed connection 104 */ 105 Statement createStatement() throws SQLException; 106 107 /** 108 * Creates a <code>PreparedStatement</code> object for sending 109 * parameterized SQL statements to the database. 110 * <P> 111 * A SQL statement with or without IN parameters can be 112 * pre-compiled and stored in a <code>PreparedStatement</code> object. This 113 * object can then be used to efficiently execute this statement 114 * multiple times. 115 * 116 * <P><B>Note:</B> This method is optimized for handling 117 * parametric SQL statements that benefit from precompilation. If 118 * the driver supports precompilation, 119 * the method <code>prepareStatement</code> will send 120 * the statement to the database for precompilation. Some drivers 121 * may not support precompilation. In this case, the statement may 122 * not be sent to the database until the <code>PreparedStatement</code> 123 * object is executed. This has no direct effect on users; however, it does 124 * affect which methods throw certain <code>SQLException</code> objects. 125 * <P> 126 * Result sets created using the returned <code>PreparedStatement</code> 127 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 128 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 129 * The holdability of the created result sets can be determined by 130 * calling {@link #getHoldability}. 131 * 132 * @param sql an SQL statement that may contain one or more '?' IN 133 * parameter placeholders 134 * @return a new default <code>PreparedStatement</code> object containing the 135 * pre-compiled SQL statement 136 * @exception SQLException if a database access error occurs 137 * or this method is called on a closed connection 138 */ 139 PreparedStatement prepareStatement(String sql) 140 throws SQLException; 141 142 /** 143 * Creates a <code>CallableStatement</code> object for calling 144 * database stored procedures. 145 * The <code>CallableStatement</code> object provides 146 * methods for setting up its IN and OUT parameters, and 147 * methods for executing the call to a stored procedure. 148 * 149 * <P><B>Note:</B> This method is optimized for handling stored 150 * procedure call statements. Some drivers may send the call 151 * statement to the database when the method <code>prepareCall</code> 152 * is done; others 153 * may wait until the <code>CallableStatement</code> object 154 * is executed. This has no 155 * direct effect on users; however, it does affect which method 156 * throws certain SQLExceptions. 157 * <P> 158 * Result sets created using the returned <code>CallableStatement</code> 159 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 160 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 161 * The holdability of the created result sets can be determined by 162 * calling {@link #getHoldability}. 163 * 164 * @param sql an SQL statement that may contain one or more '?' 165 * parameter placeholders. Typically this statement is specified using JDBC 166 * call escape syntax. 167 * @return a new default <code>CallableStatement</code> object containing the 168 * pre-compiled SQL statement 169 * @exception SQLException if a database access error occurs 170 * or this method is called on a closed connection 171 */ 172 CallableStatement prepareCall(String sql) throws SQLException; 173 174 /** 175 * Converts the given SQL statement into the system's native SQL grammar. 176 * A driver may convert the JDBC SQL grammar into its system's 177 * native SQL grammar prior to sending it. This method returns the 178 * native form of the statement that the driver would have sent. 179 * 180 * @param sql an SQL statement that may contain one or more '?' 181 * parameter placeholders 182 * @return the native form of this statement 183 * @exception SQLException if a database access error occurs 184 * or this method is called on a closed connection 185 */ 186 String nativeSQL(String sql) throws SQLException; 187 188 /** 189 * Sets this connection's auto-commit mode to the given state. 190 * If a connection is in auto-commit mode, then all its SQL 191 * statements will be executed and committed as individual 192 * transactions. Otherwise, its SQL statements are grouped into 193 * transactions that are terminated by a call to either 194 * the method <code>commit</code> or the method <code>rollback</code>. 195 * By default, new connections are in auto-commit 196 * mode. 197 * <P> 198 * The commit occurs when the statement completes. The time when the statement 199 * completes depends on the type of SQL Statement: 200 * <ul> 201 * <li>For DML statements, such as Insert, Update or Delete, and DDL statements, 202 * the statement is complete as soon as it has finished executing. 203 * <li>For Select statements, the statement is complete when the associated result 204 * set is closed. 205 * <li>For <code>CallableStatement</code> objects or for statements that return 206 * multiple results, the statement is complete 207 * when all of the associated result sets have been closed, and all update 208 * counts and output parameters have been retrieved. 209 *</ul> 210 * <P> 211 * <B>NOTE:</B> If this method is called during a transaction and the 212 * auto-commit mode is changed, the transaction is committed. If 213 * <code>setAutoCommit</code> is called and the auto-commit mode is 214 * not changed, the call is a no-op. 215 * 216 * @param autoCommit <code>true</code> to enable auto-commit mode; 217 * <code>false</code> to disable it 218 * @exception SQLException if a database access error occurs, 219 * setAutoCommit(true) is called while participating in a distributed transaction, 220 * or this method is called on a closed connection 221 * @see #getAutoCommit 222 */ 223 void setAutoCommit(boolean autoCommit) throws SQLException; 224 225 /** 226 * Retrieves the current auto-commit mode for this <code>Connection</code> 227 * object. 228 * 229 * @return the current state of this <code>Connection</code> object's 230 * auto-commit mode 231 * @exception SQLException if a database access error occurs 232 * or this method is called on a closed connection 233 * @see #setAutoCommit 234 */ 235 boolean getAutoCommit() throws SQLException; 236 237 /** 238 * Makes all changes made since the previous 239 * commit/rollback permanent and releases any database locks 240 * currently held by this <code>Connection</code> object. 241 * This method should be 242 * used only when auto-commit mode has been disabled. 243 * 244 * @exception SQLException if a database access error occurs, 245 * this method is called while participating in a distributed transaction, 246 * if this method is called on a closed connection or this 247 * <code>Connection</code> object is in auto-commit mode 248 * @see #setAutoCommit 249 */ 250 void commit() throws SQLException; 251 252 /** 253 * Undoes all changes made in the current transaction 254 * and releases any database locks currently held 255 * by this <code>Connection</code> object. This method should be 256 * used only when auto-commit mode has been disabled. 257 * 258 * @exception SQLException if a database access error occurs, 259 * this method is called while participating in a distributed transaction, 260 * this method is called on a closed connection or this 261 * <code>Connection</code> object is in auto-commit mode 262 * @see #setAutoCommit 263 */ 264 void rollback() throws SQLException; 265 266 /** 267 * Releases this <code>Connection</code> object's database and JDBC resources 268 * immediately instead of waiting for them to be automatically released. 269 * <P> 270 * Calling the method <code>close</code> on a <code>Connection</code> 271 * object that is already closed is a no-op. 272 * <P> 273 * It is <b>strongly recommended</b> that an application explicitly 274 * commits or rolls back an active transaction prior to calling the 275 * <code>close</code> method. If the <code>close</code> method is called 276 * and there is an active transaction, the results are implementation-defined. 277 * 278 * @exception SQLException if a database access error occurs 279 */ 280 void close() throws SQLException; 281 282 /** 283 * Retrieves whether this <code>Connection</code> object has been 284 * closed. A connection is closed if the method <code>close</code> 285 * has been called on it or if certain fatal errors have occurred. 286 * This method is guaranteed to return <code>true</code> only when 287 * it is called after the method <code>Connection.close</code> has 288 * been called. 289 * <P> 290 * This method generally cannot be called to determine whether a 291 * connection to a database is valid or invalid. A typical client 292 * can determine that a connection is invalid by catching any 293 * exceptions that might be thrown when an operation is attempted. 294 * 295 * @return <code>true</code> if this <code>Connection</code> object 296 * is closed; <code>false</code> if it is still open 297 * @exception SQLException if a database access error occurs 298 */ 299 boolean isClosed() throws SQLException; 300 301 //====================================================================== 302 // Advanced features: 303 304 /** 305 * Retrieves a <code>DatabaseMetaData</code> object that contains 306 * metadata about the database to which this 307 * <code>Connection</code> object represents a connection. 308 * The metadata includes information about the database's 309 * tables, its supported SQL grammar, its stored 310 * procedures, the capabilities of this connection, and so on. 311 * 312 * @return a <code>DatabaseMetaData</code> object for this 313 * <code>Connection</code> object 314 * @exception SQLException if a database access error occurs 315 * or this method is called on a closed connection 316 */ 317 DatabaseMetaData getMetaData() throws SQLException; 318 319 /** 320 * Puts this connection in read-only mode as a hint to the driver to enable 321 * database optimizations. 322 * 323 * <P><B>Note:</B> This method cannot be called during a transaction. 324 * 325 * @param readOnly <code>true</code> enables read-only mode; 326 * <code>false</code> disables it 327 * @exception SQLException if a database access error occurs, this 328 * method is called on a closed connection or this 329 * method is called during a transaction 330 */ 331 void setReadOnly(boolean readOnly) throws SQLException; 332 333 /** 334 * Retrieves whether this <code>Connection</code> 335 * object is in read-only mode. 336 * 337 * @return <code>true</code> if this <code>Connection</code> object 338 * is read-only; <code>false</code> otherwise 339 * @exception SQLException if a database access error occurs 340 * or this method is called on a closed connection 341 */ 342 boolean isReadOnly() throws SQLException; 343 344 /** 345 * Sets the given catalog name in order to select 346 * a subspace of this <code>Connection</code> object's database 347 * in which to work. 348 * <P> 349 * If the driver does not support catalogs, it will 350 * silently ignore this request. 351 * <p> 352 * Calling {@code setCatalog} has no effect on previously created or prepared 353 * {@code Statement} objects. It is implementation defined whether a DBMS 354 * prepare operation takes place immediately when the {@code Connection} 355 * method {@code prepareStatement} or {@code prepareCall} is invoked. 356 * For maximum portability, {@code setCatalog} should be called before a 357 * {@code Statement} is created or prepared. 358 * 359 * @param catalog the name of a catalog (subspace in this 360 * <code>Connection</code> object's database) in which to work 361 * @exception SQLException if a database access error occurs 362 * or this method is called on a closed connection 363 * @see #getCatalog 364 */ 365 void setCatalog(String catalog) throws SQLException; 366 367 /** 368 * Retrieves this <code>Connection</code> object's current catalog name. 369 * 370 * @return the current catalog name or <code>null</code> if there is none 371 * @exception SQLException if a database access error occurs 372 * or this method is called on a closed connection 373 * @see #setCatalog 374 */ 375 String getCatalog() throws SQLException; 376 377 /** 378 * A constant indicating that transactions are not supported. 379 */ 380 int TRANSACTION_NONE = 0; 381 382 /** 383 * A constant indicating that 384 * dirty reads, non-repeatable reads and phantom reads can occur. 385 * This level allows a row changed by one transaction to be read 386 * by another transaction before any changes in that row have been 387 * committed (a "dirty read"). If any of the changes are rolled back, 388 * the second transaction will have retrieved an invalid row. 389 */ 390 int TRANSACTION_READ_UNCOMMITTED = 1; 391 392 /** 393 * A constant indicating that 394 * dirty reads are prevented; non-repeatable reads and phantom 395 * reads can occur. This level only prohibits a transaction 396 * from reading a row with uncommitted changes in it. 397 */ 398 int TRANSACTION_READ_COMMITTED = 2; 399 400 /** 401 * A constant indicating that 402 * dirty reads and non-repeatable reads are prevented; phantom 403 * reads can occur. This level prohibits a transaction from 404 * reading a row with uncommitted changes in it, and it also 405 * prohibits the situation where one transaction reads a row, 406 * a second transaction alters the row, and the first transaction 407 * rereads the row, getting different values the second time 408 * (a "non-repeatable read"). 409 */ 410 int TRANSACTION_REPEATABLE_READ = 4; 411 412 /** 413 * A constant indicating that 414 * dirty reads, non-repeatable reads and phantom reads are prevented. 415 * This level includes the prohibitions in 416 * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the 417 * situation where one transaction reads all rows that satisfy 418 * a <code>WHERE</code> condition, a second transaction inserts a row that 419 * satisfies that <code>WHERE</code> condition, and the first transaction 420 * rereads for the same condition, retrieving the additional 421 * "phantom" row in the second read. 422 */ 423 int TRANSACTION_SERIALIZABLE = 8; 424 425 /** 426 * Attempts to change the transaction isolation level for this 427 * <code>Connection</code> object to the one given. 428 * The constants defined in the interface <code>Connection</code> 429 * are the possible transaction isolation levels. 430 * <P> 431 * <B>Note:</B> If this method is called during a transaction, the result 432 * is implementation-defined. 433 * 434 * @param level one of the following <code>Connection</code> constants: 435 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 436 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 437 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or 438 * <code>Connection.TRANSACTION_SERIALIZABLE</code>. 439 * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used 440 * because it specifies that transactions are not supported.) 441 * @exception SQLException if a database access error occurs, this 442 * method is called on a closed connection 443 * or the given parameter is not one of the <code>Connection</code> 444 * constants 445 * @see DatabaseMetaData#supportsTransactionIsolationLevel 446 * @see #getTransactionIsolation 447 */ 448 void setTransactionIsolation(int level) throws SQLException; 449 450 /** 451 * Retrieves this <code>Connection</code> object's current 452 * transaction isolation level. 453 * 454 * @return the current transaction isolation level, which will be one 455 * of the following constants: 456 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 457 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 458 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, 459 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or 460 * <code>Connection.TRANSACTION_NONE</code>. 461 * @exception SQLException if a database access error occurs 462 * or this method is called on a closed connection 463 * @see #setTransactionIsolation 464 */ 465 int getTransactionIsolation() throws SQLException; 466 467 /** 468 * Retrieves the first warning reported by calls on this 469 * <code>Connection</code> object. If there is more than one 470 * warning, subsequent warnings will be chained to the first one 471 * and can be retrieved by calling the method 472 * <code>SQLWarning.getNextWarning</code> on the warning 473 * that was retrieved previously. 474 * <P> 475 * This method may not be 476 * called on a closed connection; doing so will cause an 477 * <code>SQLException</code> to be thrown. 478 * 479 * <P><B>Note:</B> Subsequent warnings will be chained to this 480 * SQLWarning. 481 * 482 * @return the first <code>SQLWarning</code> object or <code>null</code> 483 * if there are none 484 * @exception SQLException if a database access error occurs or 485 * this method is called on a closed connection 486 * @see SQLWarning 487 */ 488 SQLWarning getWarnings() throws SQLException; 489 490 /** 491 * Clears all warnings reported for this <code>Connection</code> object. 492 * After a call to this method, the method <code>getWarnings</code> 493 * returns <code>null</code> until a new warning is 494 * reported for this <code>Connection</code> object. 495 * 496 * @exception SQLException if a database access error occurs 497 * or this method is called on a closed connection 498 */ 499 void clearWarnings() throws SQLException; 500 501 502 //--------------------------JDBC 2.0----------------------------- 503 504 /** 505 * Creates a <code>Statement</code> object that will generate 506 * <code>ResultSet</code> objects with the given type and concurrency. 507 * This method is the same as the <code>createStatement</code> method 508 * above, but it allows the default result set 509 * type and concurrency to be overridden. 510 * The holdability of the created result sets can be determined by 511 * calling {@link #getHoldability}. 512 * 513 * @param resultSetType a result set type; one of 514 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 515 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 516 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 517 * @param resultSetConcurrency a concurrency type; one of 518 * <code>ResultSet.CONCUR_READ_ONLY</code> or 519 * <code>ResultSet.CONCUR_UPDATABLE</code> 520 * @return a new <code>Statement</code> object that will generate 521 * <code>ResultSet</code> objects with the given type and 522 * concurrency 523 * @exception SQLException if a database access error occurs, this 524 * method is called on a closed connection 525 * or the given parameters are not <code>ResultSet</code> 526 * constants indicating type and concurrency 527 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 528 * this method or this method is not supported for the specified result 529 * set type and result set concurrency. 530 * @since 1.2 531 */ 532 Statement createStatement(int resultSetType, int resultSetConcurrency) 533 throws SQLException; 534 535 /** 536 * 537 * Creates a <code>PreparedStatement</code> object that will generate 538 * <code>ResultSet</code> objects with the given type and concurrency. 539 * This method is the same as the <code>prepareStatement</code> method 540 * above, but it allows the default result set 541 * type and concurrency to be overridden. 542 * The holdability of the created result sets can be determined by 543 * calling {@link #getHoldability}. 544 * 545 * @param sql a <code>String</code> object that is the SQL statement to 546 * be sent to the database; may contain one or more '?' IN 547 * parameters 548 * @param resultSetType a result set type; one of 549 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 550 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 551 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 552 * @param resultSetConcurrency a concurrency type; one of 553 * <code>ResultSet.CONCUR_READ_ONLY</code> or 554 * <code>ResultSet.CONCUR_UPDATABLE</code> 555 * @return a new PreparedStatement object containing the 556 * pre-compiled SQL statement that will produce <code>ResultSet</code> 557 * objects with the given type and concurrency 558 * @exception SQLException if a database access error occurs, this 559 * method is called on a closed connection 560 * or the given parameters are not <code>ResultSet</code> 561 * constants indicating type and concurrency 562 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 563 * this method or this method is not supported for the specified result 564 * set type and result set concurrency. 565 * @since 1.2 566 */ 567 PreparedStatement prepareStatement(String sql, int resultSetType, 568 int resultSetConcurrency) 569 throws SQLException; 570 571 /** 572 * Creates a <code>CallableStatement</code> object that will generate 573 * <code>ResultSet</code> objects with the given type and concurrency. 574 * This method is the same as the <code>prepareCall</code> method 575 * above, but it allows the default result set 576 * type and concurrency to be overridden. 577 * The holdability of the created result sets can be determined by 578 * calling {@link #getHoldability}. 579 * 580 * @param sql a <code>String</code> object that is the SQL statement to 581 * be sent to the database; may contain on or more '?' parameters 582 * @param resultSetType a result set type; one of 583 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 584 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 585 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 586 * @param resultSetConcurrency a concurrency type; one of 587 * <code>ResultSet.CONCUR_READ_ONLY</code> or 588 * <code>ResultSet.CONCUR_UPDATABLE</code> 589 * @return a new <code>CallableStatement</code> object containing the 590 * pre-compiled SQL statement that will produce <code>ResultSet</code> 591 * objects with the given type and concurrency 592 * @exception SQLException if a database access error occurs, this method 593 * is called on a closed connection 594 * or the given parameters are not <code>ResultSet</code> 595 * constants indicating type and concurrency 596 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 597 * this method or this method is not supported for the specified result 598 * set type and result set concurrency. 599 * @since 1.2 600 */ 601 CallableStatement prepareCall(String sql, int resultSetType, 602 int resultSetConcurrency) throws SQLException; 603 604 /** 605 * Retrieves the <code>Map</code> object associated with this 606 * <code>Connection</code> object. 607 * Unless the application has added an entry, the type map returned 608 * will be empty. 609 * <p> 610 * You must invoke <code>setTypeMap</code> after making changes to the 611 * <code>Map</code> object returned from 612 * <code>getTypeMap</code> as a JDBC driver may create an internal 613 * copy of the <code>Map</code> object passed to <code>setTypeMap</code>: 614 * 615 * <pre> 616 * Map<String,Class<?>> myMap = con.getTypeMap(); 617 * myMap.put("mySchemaName.ATHLETES", Athletes.class); 618 * con.setTypeMap(myMap); 619 * </pre> 620 * @return the <code>java.util.Map</code> object associated 621 * with this <code>Connection</code> object 622 * @exception SQLException if a database access error occurs 623 * or this method is called on a closed connection 624 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 625 * this method 626 * @since 1.2 627 * @see #setTypeMap 628 */ 629 java.util.Map<String,Class<?>> getTypeMap() throws SQLException; 630 631 /** 632 * Installs the given <code>TypeMap</code> object as the type map for 633 * this <code>Connection</code> object. The type map will be used for the 634 * custom mapping of SQL structured types and distinct types. 635 * <p> 636 * You must set the values for the <code>TypeMap</code> prior to 637 * callng <code>setMap</code> as a JDBC driver may create an internal copy 638 * of the <code>TypeMap</code>: 639 * 640 * <pre> 641 * Map myMap<String,Class<?>> = new HashMap<String,Class<?>>(); 642 * myMap.put("mySchemaName.ATHLETES", Athletes.class); 643 * con.setTypeMap(myMap); 644 * </pre> 645 * @param map the <code>java.util.Map</code> object to install 646 * as the replacement for this <code>Connection</code> 647 * object's default type map 648 * @exception SQLException if a database access error occurs, this 649 * method is called on a closed connection or 650 * the given parameter is not a <code>java.util.Map</code> 651 * object 652 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 653 * this method 654 * @since 1.2 655 * @see #getTypeMap 656 */ 657 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException; 658 659 //--------------------------JDBC 3.0----------------------------- 660 661 662 /** 663 * Changes the default holdability of <code>ResultSet</code> objects 664 * created using this <code>Connection</code> object to the given 665 * holdability. The default holdability of <code>ResultSet</code> objects 666 * can be determined by invoking 667 * {@link DatabaseMetaData#getResultSetHoldability}. 668 * 669 * @param holdability a <code>ResultSet</code> holdability constant; one of 670 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 671 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 672 * @throws SQLException if a database access occurs, this method is called 673 * on a closed connection, or the given parameter 674 * is not a <code>ResultSet</code> constant indicating holdability 675 * @exception SQLFeatureNotSupportedException if the given holdability is not supported 676 * @see #getHoldability 677 * @see DatabaseMetaData#getResultSetHoldability 678 * @see ResultSet 679 * @since 1.4 680 */ 681 void setHoldability(int holdability) throws SQLException; 682 683 /** 684 * Retrieves the current holdability of <code>ResultSet</code> objects 685 * created using this <code>Connection</code> object. 686 * 687 * @return the holdability, one of 688 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 689 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 690 * @throws SQLException if a database access error occurs 691 * or this method is called on a closed connection 692 * @see #setHoldability 693 * @see DatabaseMetaData#getResultSetHoldability 694 * @see ResultSet 695 * @since 1.4 696 */ 697 int getHoldability() throws SQLException; 698 699 /** 700 * Creates an unnamed savepoint in the current transaction and 701 * returns the new <code>Savepoint</code> object that represents it. 702 * 703 *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 704 *savepoint. 705 * 706 * @return the new <code>Savepoint</code> object 707 * @exception SQLException if a database access error occurs, 708 * this method is called while participating in a distributed transaction, 709 * this method is called on a closed connection 710 * or this <code>Connection</code> object is currently in 711 * auto-commit mode 712 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 713 * this method 714 * @see Savepoint 715 * @since 1.4 716 */ 717 Savepoint setSavepoint() throws SQLException; 718 719 /** 720 * Creates a savepoint with the given name in the current transaction 721 * and returns the new <code>Savepoint</code> object that represents it. 722 * 723 * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 724 *savepoint. 725 * 726 * @param name a <code>String</code> containing the name of the savepoint 727 * @return the new <code>Savepoint</code> object 728 * @exception SQLException if a database access error occurs, 729 * this method is called while participating in a distributed transaction, 730 * this method is called on a closed connection 731 * or this <code>Connection</code> object is currently in 732 * auto-commit mode 733 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 734 * this method 735 * @see Savepoint 736 * @since 1.4 737 */ 738 Savepoint setSavepoint(String name) throws SQLException; 739 740 /** 741 * Undoes all changes made after the given <code>Savepoint</code> object 742 * was set. 743 * <P> 744 * This method should be used only when auto-commit has been disabled. 745 * 746 * @param savepoint the <code>Savepoint</code> object to roll back to 747 * @exception SQLException if a database access error occurs, 748 * this method is called while participating in a distributed transaction, 749 * this method is called on a closed connection, 750 * the <code>Savepoint</code> object is no longer valid, 751 * or this <code>Connection</code> object is currently in 752 * auto-commit mode 753 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 754 * this method 755 * @see Savepoint 756 * @see #rollback 757 * @since 1.4 758 */ 759 void rollback(Savepoint savepoint) throws SQLException; 760 761 /** 762 * Removes the specified <code>Savepoint</code> and subsequent <code>Savepoint</code> objects from the current 763 * transaction. Any reference to the savepoint after it have been removed 764 * will cause an <code>SQLException</code> to be thrown. 765 * 766 * @param savepoint the <code>Savepoint</code> object to be removed 767 * @exception SQLException if a database access error occurs, this 768 * method is called on a closed connection or 769 * the given <code>Savepoint</code> object is not a valid 770 * savepoint in the current transaction 771 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 772 * this method 773 * @since 1.4 774 */ 775 void releaseSavepoint(Savepoint savepoint) throws SQLException; 776 777 /** 778 * Creates a <code>Statement</code> object that will generate 779 * <code>ResultSet</code> objects with the given type, concurrency, 780 * and holdability. 781 * This method is the same as the <code>createStatement</code> method 782 * above, but it allows the default result set 783 * type, concurrency, and holdability to be overridden. 784 * 785 * @param resultSetType one of the following <code>ResultSet</code> 786 * constants: 787 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 788 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 789 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 790 * @param resultSetConcurrency one of the following <code>ResultSet</code> 791 * constants: 792 * <code>ResultSet.CONCUR_READ_ONLY</code> or 793 * <code>ResultSet.CONCUR_UPDATABLE</code> 794 * @param resultSetHoldability one of the following <code>ResultSet</code> 795 * constants: 796 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 797 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 798 * @return a new <code>Statement</code> object that will generate 799 * <code>ResultSet</code> objects with the given type, 800 * concurrency, and holdability 801 * @exception SQLException if a database access error occurs, this 802 * method is called on a closed connection 803 * or the given parameters are not <code>ResultSet</code> 804 * constants indicating type, concurrency, and holdability 805 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 806 * this method or this method is not supported for the specified result 807 * set type, result set holdability and result set concurrency. 808 * @see ResultSet 809 * @since 1.4 810 */ 811 Statement createStatement(int resultSetType, int resultSetConcurrency, 812 int resultSetHoldability) throws SQLException; 813 814 /** 815 * Creates a <code>PreparedStatement</code> object that will generate 816 * <code>ResultSet</code> objects with the given type, concurrency, 817 * and holdability. 818 * <P> 819 * This method is the same as the <code>prepareStatement</code> method 820 * above, but it allows the default result set 821 * type, concurrency, and holdability to be overridden. 822 * 823 * @param sql a <code>String</code> object that is the SQL statement to 824 * be sent to the database; may contain one or more '?' IN 825 * parameters 826 * @param resultSetType one of the following <code>ResultSet</code> 827 * constants: 828 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 829 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 830 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 831 * @param resultSetConcurrency one of the following <code>ResultSet</code> 832 * constants: 833 * <code>ResultSet.CONCUR_READ_ONLY</code> or 834 * <code>ResultSet.CONCUR_UPDATABLE</code> 835 * @param resultSetHoldability one of the following <code>ResultSet</code> 836 * constants: 837 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 838 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 839 * @return a new <code>PreparedStatement</code> object, containing the 840 * pre-compiled SQL statement, that will generate 841 * <code>ResultSet</code> objects with the given type, 842 * concurrency, and holdability 843 * @exception SQLException if a database access error occurs, this 844 * method is called on a closed connection 845 * or the given parameters are not <code>ResultSet</code> 846 * constants indicating type, concurrency, and holdability 847 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 848 * this method or this method is not supported for the specified result 849 * set type, result set holdability and result set concurrency. 850 * @see ResultSet 851 * @since 1.4 852 */ 853 PreparedStatement prepareStatement(String sql, int resultSetType, 854 int resultSetConcurrency, int resultSetHoldability) 855 throws SQLException; 856 857 /** 858 * Creates a <code>CallableStatement</code> object that will generate 859 * <code>ResultSet</code> objects with the given type and concurrency. 860 * This method is the same as the <code>prepareCall</code> method 861 * above, but it allows the default result set 862 * type, result set concurrency type and holdability to be overridden. 863 * 864 * @param sql a <code>String</code> object that is the SQL statement to 865 * be sent to the database; may contain on or more '?' parameters 866 * @param resultSetType one of the following <code>ResultSet</code> 867 * constants: 868 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 869 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 870 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 871 * @param resultSetConcurrency one of the following <code>ResultSet</code> 872 * constants: 873 * <code>ResultSet.CONCUR_READ_ONLY</code> or 874 * <code>ResultSet.CONCUR_UPDATABLE</code> 875 * @param resultSetHoldability one of the following <code>ResultSet</code> 876 * constants: 877 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 878 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 879 * @return a new <code>CallableStatement</code> object, containing the 880 * pre-compiled SQL statement, that will generate 881 * <code>ResultSet</code> objects with the given type, 882 * concurrency, and holdability 883 * @exception SQLException if a database access error occurs, this 884 * method is called on a closed connection 885 * or the given parameters are not <code>ResultSet</code> 886 * constants indicating type, concurrency, and holdability 887 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 888 * this method or this method is not supported for the specified result 889 * set type, result set holdability and result set concurrency. 890 * @see ResultSet 891 * @since 1.4 892 */ 893 CallableStatement prepareCall(String sql, int resultSetType, 894 int resultSetConcurrency, 895 int resultSetHoldability) throws SQLException; 896 897 898 /** 899 * Creates a default <code>PreparedStatement</code> object that has 900 * the capability to retrieve auto-generated keys. The given constant 901 * tells the driver whether it should make auto-generated keys 902 * available for retrieval. This parameter is ignored if the SQL statement 903 * is not an <code>INSERT</code> statement, or an SQL statement able to return 904 * auto-generated keys (the list of such statements is vendor-specific). 905 * <P> 906 * <B>Note:</B> This method is optimized for handling 907 * parametric SQL statements that benefit from precompilation. If 908 * the driver supports precompilation, 909 * the method <code>prepareStatement</code> will send 910 * the statement to the database for precompilation. Some drivers 911 * may not support precompilation. In this case, the statement may 912 * not be sent to the database until the <code>PreparedStatement</code> 913 * object is executed. This has no direct effect on users; however, it does 914 * affect which methods throw certain SQLExceptions. 915 * <P> 916 * Result sets created using the returned <code>PreparedStatement</code> 917 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 918 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 919 * The holdability of the created result sets can be determined by 920 * calling {@link #getHoldability}. 921 * 922 * @param sql an SQL statement that may contain one or more '?' IN 923 * parameter placeholders 924 * @param autoGeneratedKeys a flag indicating whether auto-generated keys 925 * should be returned; one of 926 * <code>Statement.RETURN_GENERATED_KEYS</code> or 927 * <code>Statement.NO_GENERATED_KEYS</code> 928 * @return a new <code>PreparedStatement</code> object, containing the 929 * pre-compiled SQL statement, that will have the capability of 930 * returning auto-generated keys 931 * @exception SQLException if a database access error occurs, this 932 * method is called on a closed connection 933 * or the given parameter is not a <code>Statement</code> 934 * constant indicating whether auto-generated keys should be 935 * returned 936 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 937 * this method with a constant of Statement.RETURN_GENERATED_KEYS 938 * @since 1.4 939 */ 940 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) 941 throws SQLException; 942 943 /** 944 * Creates a default <code>PreparedStatement</code> object capable 945 * of returning the auto-generated keys designated by the given array. 946 * This array contains the indexes of the columns in the target 947 * table that contain the auto-generated keys that should be made 948 * available. The driver will ignore the array if the SQL statement 949 * is not an <code>INSERT</code> statement, or an SQL statement able to return 950 * auto-generated keys (the list of such statements is vendor-specific). 951 *<p> 952 * An SQL statement with or without IN parameters can be 953 * pre-compiled and stored in a <code>PreparedStatement</code> object. This 954 * object can then be used to efficiently execute this statement 955 * multiple times. 956 * <P> 957 * <B>Note:</B> This method is optimized for handling 958 * parametric SQL statements that benefit from precompilation. If 959 * the driver supports precompilation, 960 * the method <code>prepareStatement</code> will send 961 * the statement to the database for precompilation. Some drivers 962 * may not support precompilation. In this case, the statement may 963 * not be sent to the database until the <code>PreparedStatement</code> 964 * object is executed. This has no direct effect on users; however, it does 965 * affect which methods throw certain SQLExceptions. 966 * <P> 967 * Result sets created using the returned <code>PreparedStatement</code> 968 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 969 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 970 * The holdability of the created result sets can be determined by 971 * calling {@link #getHoldability}. 972 * 973 * @param sql an SQL statement that may contain one or more '?' IN 974 * parameter placeholders 975 * @param columnIndexes an array of column indexes indicating the columns 976 * that should be returned from the inserted row or rows 977 * @return a new <code>PreparedStatement</code> object, containing the 978 * pre-compiled statement, that is capable of returning the 979 * auto-generated keys designated by the given array of column 980 * indexes 981 * @exception SQLException if a database access error occurs 982 * or this method is called on a closed connection 983 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 984 * this method 985 * 986 * @since 1.4 987 */ 988 PreparedStatement prepareStatement(String sql, int columnIndexes[]) 989 throws SQLException; 990 991 /** 992 * Creates a default <code>PreparedStatement</code> object capable 993 * of returning the auto-generated keys designated by the given array. 994 * This array contains the names of the columns in the target 995 * table that contain the auto-generated keys that should be returned. 996 * The driver will ignore the array if the SQL statement 997 * is not an <code>INSERT</code> statement, or an SQL statement able to return 998 * auto-generated keys (the list of such statements is vendor-specific). 999 * <P> 1000 * An SQL statement with or without IN parameters can be 1001 * pre-compiled and stored in a <code>PreparedStatement</code> object. This 1002 * object can then be used to efficiently execute this statement 1003 * multiple times. 1004 * <P> 1005 * <B>Note:</B> This method is optimized for handling 1006 * parametric SQL statements that benefit from precompilation. If 1007 * the driver supports precompilation, 1008 * the method <code>prepareStatement</code> will send 1009 * the statement to the database for precompilation. Some drivers 1010 * may not support precompilation. In this case, the statement may 1011 * not be sent to the database until the <code>PreparedStatement</code> 1012 * object is executed. This has no direct effect on users; however, it does 1013 * affect which methods throw certain SQLExceptions. 1014 * <P> 1015 * Result sets created using the returned <code>PreparedStatement</code> 1016 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 1017 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 1018 * The holdability of the created result sets can be determined by 1019 * calling {@link #getHoldability}. 1020 * 1021 * @param sql an SQL statement that may contain one or more '?' IN 1022 * parameter placeholders 1023 * @param columnNames an array of column names indicating the columns 1024 * that should be returned from the inserted row or rows 1025 * @return a new <code>PreparedStatement</code> object, containing the 1026 * pre-compiled statement, that is capable of returning the 1027 * auto-generated keys designated by the given array of column 1028 * names 1029 * @exception SQLException if a database access error occurs 1030 * or this method is called on a closed connection 1031 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1032 * this method 1033 * 1034 * @since 1.4 1035 */ 1036 PreparedStatement prepareStatement(String sql, String columnNames[]) 1037 throws SQLException; 1038 1039 /** 1040 * Constructs an object that implements the <code>Clob</code> interface. The object 1041 * returned initially contains no data. The <code>setAsciiStream</code>, 1042 * <code>setCharacterStream</code> and <code>setString</code> methods of 1043 * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>. 1044 * @return An object that implements the <code>Clob</code> interface 1045 * @throws SQLException if an object that implements the 1046 * <code>Clob</code> interface can not be constructed, this method is 1047 * called on a closed connection or a database access error occurs. 1048 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1049 * this data type 1050 * 1051 * @since 1.6 1052 */ 1053 Clob createClob() throws SQLException; 1054 1055 /** 1056 * Constructs an object that implements the <code>Blob</code> interface. The object 1057 * returned initially contains no data. The <code>setBinaryStream</code> and 1058 * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to 1059 * the <code>Blob</code>. 1060 * @return An object that implements the <code>Blob</code> interface 1061 * @throws SQLException if an object that implements the 1062 * <code>Blob</code> interface can not be constructed, this method is 1063 * called on a closed connection or a database access error occurs. 1064 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1065 * this data type 1066 * 1067 * @since 1.6 1068 */ 1069 Blob createBlob() throws SQLException; 1070 1071 /** 1072 * Constructs an object that implements the <code>NClob</code> interface. The object 1073 * returned initially contains no data. The <code>setAsciiStream</code>, 1074 * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may 1075 * be used to add data to the <code>NClob</code>. 1076 * @return An object that implements the <code>NClob</code> interface 1077 * @throws SQLException if an object that implements the 1078 * <code>NClob</code> interface can not be constructed, this method is 1079 * called on a closed connection or a database access error occurs. 1080 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1081 * this data type 1082 * 1083 * @since 1.6 1084 */ 1085 NClob createNClob() throws SQLException; 1086 1087 /** 1088 * Constructs an object that implements the <code>SQLXML</code> interface. The object 1089 * returned initially contains no data. The <code>createXmlStreamWriter</code> object and 1090 * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code> 1091 * object. 1092 * @return An object that implements the <code>SQLXML</code> interface 1093 * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not 1094 * be constructed, this method is 1095 * called on a closed connection or a database access error occurs. 1096 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1097 * this data type 1098 * @since 1.6 1099 */ 1100 SQLXML createSQLXML() throws SQLException; 1101 1102 /** 1103 * Returns true if the connection has not been closed and is still valid. 1104 * The driver shall submit a query on the connection or use some other 1105 * mechanism that positively verifies the connection is still valid when 1106 * this method is called. 1107 * <p> 1108 * The query submitted by the driver to validate the connection shall be 1109 * executed in the context of the current transaction. 1110 * 1111 * @param timeout - The time in seconds to wait for the database operation 1112 * used to validate the connection to complete. If 1113 * the timeout period expires before the operation 1114 * completes, this method returns false. A value of 1115 * 0 indicates a timeout is not applied to the 1116 * database operation. 1117 * 1118 * @return true if the connection is valid, false otherwise 1119 * @exception SQLException if the value supplied for <code>timeout</code> 1120 * is less than 0 1121 * @since 1.6 1122 * 1123 * @see java.sql.DatabaseMetaData#getClientInfoProperties 1124 */ 1125 boolean isValid(int timeout) throws SQLException; 1126 1127 /** 1128 * Sets the value of the client info property specified by name to the 1129 * value specified by value. 1130 * <p> 1131 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code> 1132 * method to determine the client info properties supported by the driver 1133 * and the maximum length that may be specified for each property. 1134 * <p> 1135 * The driver stores the value specified in a suitable location in the 1136 * database. For example in a special register, session parameter, or 1137 * system table column. For efficiency the driver may defer setting the 1138 * value in the database until the next time a statement is executed or 1139 * prepared. Other than storing the client information in the appropriate 1140 * place in the database, these methods shall not alter the behavior of 1141 * the connection in anyway. The values supplied to these methods are 1142 * used for accounting, diagnostics and debugging purposes only. 1143 * <p> 1144 * The driver shall generate a warning if the client info name specified 1145 * is not recognized by the driver. 1146 * <p> 1147 * If the value specified to this method is greater than the maximum 1148 * length for the property the driver may either truncate the value and 1149 * generate a warning or generate a <code>SQLClientInfoException</code>. If the driver 1150 * generates a <code>SQLClientInfoException</code>, the value specified was not set on the 1151 * connection. 1152 * <p> 1153 * The following are standard client info properties. Drivers are not 1154 * required to support these properties however if the driver supports a 1155 * client info property that can be described by one of the standard 1156 * properties, the standard property name should be used. 1157 * 1158 * <ul> 1159 * <li>ApplicationName - The name of the application currently utilizing 1160 * the connection</li> 1161 * <li>ClientUser - The name of the user that the application using 1162 * the connection is performing work for. This may 1163 * not be the same as the user name that was used 1164 * in establishing the connection.</li> 1165 * <li>ClientHostname - The hostname of the computer the application 1166 * using the connection is running on.</li> 1167 * </ul> 1168 * 1169 * @param name The name of the client info property to set 1170 * @param value The value to set the client info property to. If the 1171 * value is null, the current value of the specified 1172 * property is cleared. 1173 * 1174 * @throws SQLClientInfoException if the database server returns an error while 1175 * setting the client info value on the database server or this method 1176 * is called on a closed connection 1177 * 1178 * @since 1.6 1179 */ 1180 void setClientInfo(String name, String value) 1181 throws SQLClientInfoException; 1182 1183 /** 1184 * Sets the value of the connection's client info properties. The 1185 * <code>Properties</code> object contains the names and values of the client info 1186 * properties to be set. The set of client info properties contained in 1187 * the properties list replaces the current set of client info properties 1188 * on the connection. If a property that is currently set on the 1189 * connection is not present in the properties list, that property is 1190 * cleared. Specifying an empty properties list will clear all of the 1191 * properties on the connection. See <code>setClientInfo (String, String)</code> for 1192 * more information. 1193 * <p> 1194 * If an error occurs in setting any of the client info properties, a 1195 * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code> 1196 * contains information indicating which client info properties were not set. 1197 * The state of the client information is unknown because 1198 * some databases do not allow multiple client info properties to be set 1199 * atomically. For those databases, one or more properties may have been 1200 * set before the error occurred. 1201 * 1202 * 1203 * @param properties the list of client info properties to set 1204 * 1205 * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String) 1206 * @since 1.6 1207 * 1208 * @throws SQLClientInfoException if the database server returns an error while 1209 * setting the clientInfo values on the database server or this method 1210 * is called on a closed connection 1211 * 1212 */ 1213 void setClientInfo(Properties properties) 1214 throws SQLClientInfoException; 1215 1216 /** 1217 * Returns the value of the client info property specified by name. This 1218 * method may return null if the specified client info property has not 1219 * been set and does not have a default value. This method will also 1220 * return null if the specified client info property name is not supported 1221 * by the driver. 1222 * <p> 1223 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code> 1224 * method to determine the client info properties supported by the driver. 1225 * 1226 * @param name The name of the client info property to retrieve 1227 * 1228 * @return The value of the client info property specified 1229 * 1230 * @throws SQLException if the database server returns an error when 1231 * fetching the client info value from the database 1232 * or this method is called on a closed connection 1233 * 1234 * @since 1.6 1235 * 1236 * @see java.sql.DatabaseMetaData#getClientInfoProperties 1237 */ 1238 String getClientInfo(String name) 1239 throws SQLException; 1240 1241 /** 1242 * Returns a list containing the name and current value of each client info 1243 * property supported by the driver. The value of a client info property 1244 * may be null if the property has not been set and does not have a 1245 * default value. 1246 * 1247 * @return A <code>Properties</code> object that contains the name and current value of 1248 * each of the client info properties supported by the driver. 1249 * 1250 * @throws SQLException if the database server returns an error when 1251 * fetching the client info values from the database 1252 * or this method is called on a closed connection 1253 * 1254 * @since 1.6 1255 */ 1256 Properties getClientInfo() 1257 throws SQLException; 1258 1259 /** 1260 * Factory method for creating Array objects. 1261 *<p> 1262 * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object 1263 * that maps to a primitive data type, then it is implementation-defined 1264 * whether the <code>Array</code> object is an array of that primitive 1265 * data type or an array of <code>Object</code>. 1266 * <p> 1267 * <b>Note: </b>The JDBC driver is responsible for mapping the elements 1268 * <code>Object</code> array to the default JDBC SQL type defined in 1269 * java.sql.Types for the given class of <code>Object</code>. The default 1270 * mapping is specified in Appendix B of the JDBC specification. If the 1271 * resulting JDBC type is not the appropriate type for the given typeName then 1272 * it is implementation defined whether an <code>SQLException</code> is 1273 * thrown or the driver supports the resulting conversion. 1274 * 1275 * @param typeName the SQL name of the type the elements of the array map to. The typeName is a 1276 * database-specific name which may be the name of a built-in type, a user-defined type or a standard SQL type supported by this database. This 1277 * is the value returned by <code>Array.getBaseTypeName</code> 1278 * @param elements the elements that populate the returned object 1279 * @return an Array object whose elements map to the specified SQL type 1280 * @throws SQLException if a database error occurs, the JDBC type is not 1281 * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection 1282 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type 1283 * @since 1.6 1284 */ 1285 Array createArrayOf(String typeName, Object[] elements) throws 1286 SQLException; 1287 1288 /** 1289 * Factory method for creating Struct objects. 1290 * 1291 * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code> 1292 * object maps to. The typeName is the name of a user-defined type that 1293 * has been defined for this database. It is the value returned by 1294 * <code>Struct.getSQLTypeName</code>. 1295 1296 * @param attributes the attributes that populate the returned object 1297 * @return a Struct object that maps to the given SQL type and is populated with the given attributes 1298 * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection 1299 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type 1300 * @since 1.6 1301 */ 1302 Struct createStruct(String typeName, Object[] attributes) 1303 throws SQLException; 1304 1305 //--------------------------JDBC 4.1 ----------------------------- 1306 1307 /** 1308 * Sets the given schema name to access. 1309 * <P> 1310 * If the driver does not support schemas, it will 1311 * silently ignore this request. 1312 * <p> 1313 * Calling {@code setSchema} has no effect on previously created or prepared 1314 * {@code Statement} objects. It is implementation defined whether a DBMS 1315 * prepare operation takes place immediately when the {@code Connection} 1316 * method {@code prepareStatement} or {@code prepareCall} is invoked. 1317 * For maximum portability, {@code setSchema} should be called before a 1318 * {@code Statement} is created or prepared. 1319 * 1320 * @param schema the name of a schema in which to work 1321 * @exception SQLException if a database access error occurs 1322 * or this method is called on a closed connection 1323 * @see #getSchema 1324 * @since 1.7 1325 */ 1326 void setSchema(String schema) throws SQLException; 1327 1328 /** 1329 * Retrieves this <code>Connection</code> object's current schema name. 1330 * 1331 * @return the current schema name or <code>null</code> if there is none 1332 * @exception SQLException if a database access error occurs 1333 * or this method is called on a closed connection 1334 * @see #setSchema 1335 * @since 1.7 1336 */ 1337 String getSchema() throws SQLException; 1338 1339 /** 1340 * Terminates an open connection. Calling <code>abort</code> results in: 1341 * <ul> 1342 * <li>The connection marked as closed 1343 * <li>Closes any physical connection to the database 1344 * <li>Releases resources used by the connection 1345 * <li>Insures that any thread that is currently accessing the connection 1346 * will either progress to completion or throw an <code>SQLException</code>. 1347 * </ul> 1348 * <p> 1349 * Calling <code>abort</code> marks the connection closed and releases any 1350 * resources. Calling <code>abort</code> on a closed connection is a 1351 * no-op. 1352 * <p> 1353 * It is possible that the aborting and releasing of the resources that are 1354 * held by the connection can take an extended period of time. When the 1355 * <code>abort</code> method returns, the connection will have been marked as 1356 * closed and the <code>Executor</code> that was passed as a parameter to abort 1357 * may still be executing tasks to release resources. 1358 * <p> 1359 * This method checks to see that there is an <code>SQLPermission</code> 1360 * object before allowing the method to proceed. If a 1361 * <code>SecurityManager</code> exists and its 1362 * <code>checkPermission</code> method denies calling <code>abort</code>, 1363 * this method throws a 1364 * <code>java.lang.SecurityException</code>. 1365 * @param executor The <code>Executor</code> implementation which will 1366 * be used by <code>abort</code>. 1367 * @throws java.sql.SQLException if a database access error occurs or 1368 * the {@code executor} is {@code null}, 1369 * @throws java.lang.SecurityException if a security manager exists and its 1370 * <code>checkPermission</code> method denies calling <code>abort</code> 1371 * @see SecurityManager#checkPermission 1372 * @see Executor 1373 * @since 1.7 1374 */ 1375 void abort(Executor executor) throws SQLException; 1376 1377 /** 1378 * 1379 * Sets the maximum period a <code>Connection</code> or 1380 * objects created from the <code>Connection</code> 1381 * will wait for the database to reply to any one request. If any 1382 * request remains unanswered, the waiting method will 1383 * return with a <code>SQLException</code>, and the <code>Connection</code> 1384 * or objects created from the <code>Connection</code> will be marked as 1385 * closed. Any subsequent use of 1386 * the objects, with the exception of the <code>close</code>, 1387 * <code>isClosed</code> or <code>Connection.isValid</code> 1388 * methods, will result in a <code>SQLException</code>. 1389 * <p> 1390 * <b>Note</b>: This method is intended to address a rare but serious 1391 * condition where network partitions can cause threads issuing JDBC calls 1392 * to hang uninterruptedly in socket reads, until the OS TCP-TIMEOUT 1393 * (typically 10 minutes). This method is related to the 1394 * {@link #abort abort() } method which provides an administrator 1395 * thread a means to free any such threads in cases where the 1396 * JDBC connection is accessible to the administrator thread. 1397 * The <code>setNetworkTimeout</code> method will cover cases where 1398 * there is no administrator thread, or it has no access to the 1399 * connection. This method is severe in it's effects, and should be 1400 * given a high enough value so it is never triggered before any more 1401 * normal timeouts, such as transaction timeouts. 1402 * <p> 1403 * JDBC driver implementations may also choose to support the 1404 * {@code setNetworkTimeout} method to impose a limit on database 1405 * response time, in environments where no network is present. 1406 * <p> 1407 * Drivers may internally implement some or all of their API calls with 1408 * multiple internal driver-database transmissions, and it is left to the 1409 * driver implementation to determine whether the limit will be 1410 * applied always to the response to the API call, or to any 1411 * single request made during the API call. 1412 * <p> 1413 * 1414 * This method can be invoked more than once, such as to set a limit for an 1415 * area of JDBC code, and to reset to the default on exit from this area. 1416 * Invocation of this method has no impact on already outstanding 1417 * requests. 1418 * <p> 1419 * The {@code Statement.setQueryTimeout()} timeout value is independent of the 1420 * timeout value specified in {@code setNetworkTimeout}. If the query timeout 1421 * expires before the network timeout then the 1422 * statement execution will be canceled. If the network is still 1423 * active the result will be that both the statement and connection 1424 * are still usable. However if the network timeout expires before 1425 * the query timeout or if the statement timeout fails due to network 1426 * problems, the connection will be marked as closed, any resources held by 1427 * the connection will be released and both the connection and 1428 * statement will be unusable. 1429 * <p> 1430 * When the driver determines that the {@code setNetworkTimeout} timeout 1431 * value has expired, the JDBC driver marks the connection 1432 * closed and releases any resources held by the connection. 1433 * <p> 1434 * 1435 * This method checks to see that there is an <code>SQLPermission</code> 1436 * object before allowing the method to proceed. If a 1437 * <code>SecurityManager</code> exists and its 1438 * <code>checkPermission</code> method denies calling 1439 * <code>setNetworkTimeout</code>, this method throws a 1440 * <code>java.lang.SecurityException</code>. 1441 * 1442 * @param executor The <code>Executor</code> implementation which will 1443 * be used by <code>setNetworkTimeout</code>. 1444 * @param milliseconds The time in milliseconds to wait for the database 1445 * operation 1446 * to complete. If the JDBC driver does not support milliseconds, the 1447 * JDBC driver will round the value up to the nearest second. If the 1448 * timeout period expires before the operation 1449 * completes, a SQLException will be thrown. 1450 * A value of 0 indicates that there is not timeout for database operations. 1451 * @throws java.sql.SQLException if a database access error occurs, this 1452 * method is called on a closed connection, 1453 * the {@code executor} is {@code null}, 1454 * or the value specified for <code>seconds</code> is less than 0. 1455 * @throws java.lang.SecurityException if a security manager exists and its 1456 * <code>checkPermission</code> method denies calling 1457 * <code>setNetworkTimeout</code>. 1458 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1459 * this method 1460 * @see SecurityManager#checkPermission 1461 * @see Statement#setQueryTimeout 1462 * @see #getNetworkTimeout 1463 * @see #abort 1464 * @see Executor 1465 * @since 1.7 1466 */ 1467 void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException; 1468 1469 1470 /** 1471 * Retrieves the number of milliseconds the driver will 1472 * wait for a database request to complete. 1473 * If the limit is exceeded, a 1474 * <code>SQLException</code> is thrown. 1475 * 1476 * @return the current timeout limit in milliseconds; zero means there is 1477 * no limit 1478 * @throws SQLException if a database access error occurs or 1479 * this method is called on a closed <code>Connection</code> 1480 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1481 * this method 1482 * @see #setNetworkTimeout 1483 * @since 1.7 1484 */ 1485 int getNetworkTimeout() throws SQLException; 1486 1487 // JDBC 4.3 1488 1489 /** 1490 * Hints to the driver that a request, an independent unit of work, is beginning 1491 * on this connection. Each request is independent of all other requests 1492 * with regard to state local to the connection either on the client or the 1493 * server. Work done between {@code beginRequest}, {@code endRequest} 1494 * pairs does not depend on any other work done on the connection either as 1495 * part of another request or outside of any request. A request may include multiple 1496 * transactions. There may be dependencies on committed database state as 1497 * that is not local to the connection. 1498 * <p> 1499 * Local state is defined as any state associated with a Connection that is 1500 * local to the current Connection either in the client or the database that 1501 * is not transparently reproducible. 1502 * <p> 1503 * Calls to {@code beginRequest} and {@code endRequest} are not nested. 1504 * Multiple calls to {@code beginRequest} without an intervening call 1505 * to {@code endRequest} is not an error. The first {@code beginRequest} call 1506 * marks the start of the request and subsequent calls are treated as 1507 * a no-op 1508 * <p> 1509 * Use of {@code beginRequest} and {@code endRequest} is optional, vendor 1510 * specific and should largely be transparent. In particular 1511 * implementations may detect conditions that indicate dependence on 1512 * other work such as an open transaction. It is recommended though not 1513 * required that implementations throw a {@code SQLException} if there is an active 1514 * transaction and {@code beginRequest} is called. 1515 * Using these methods may improve performance or provide other benefits. 1516 * Consult your vendors documentation for additional information. 1517 * <p> 1518 * It is recommended to 1519 * enclose each unit of work in {@code beginRequest}, {@code endRequest} 1520 * pairs such that there is no open transaction at the beginning or end of 1521 * the request and no dependency on local state that crosses request 1522 * boundaries. Committed database state is not local. 1523 * 1524 * @implSpec 1525 * The default implementation is a no-op. 1526 * <p> 1527 * @apiNote 1528 * This method is to be used by Connection pooling managers. 1529 * <p> 1530 * The pooling manager should call {@code beginRequest} on the underlying connection 1531 * prior to returning a connection to the caller. 1532 * <p> 1533 * The pooling manager does not need to call {@code beginRequest} if: 1534 * <ul> 1535 * <li>The connection pool caches {@code PooledConnection} objects</li> 1536 * <li>Returns a logical connection handle when {@code getConnection} is 1537 * called by the application</li> 1538 * <li>The pool manager calls {@code Connection.close} on the logical connection handle 1539 * prior to returning the {@code PooledConnection} back to the cache</li> 1540 * </ul> 1541 * @throws SQLException if an error occurs 1542 * @since 9 1543 * @see endRequest 1544 * @see javax.sql.PooledConnection 1545 */ 1546 default void beginRequest() throws SQLException { 1547 // Default method takes no action 1548 } 1549 1550 /** 1551 * Hints to the driver that a request, an independent unit of work, 1552 * has completed. Calls to {@code beginRequest} 1553 * and {@code endRequest} are not nested. Multiple 1554 * calls to {@code endRequest} without an intervening call to {@code beginRequest} 1555 * is not an error. The first {@code endRequest} call 1556 * marks the request completed and subsequent calls are treated as 1557 * a no-op. If {@code endRequest} is called without an initial call to 1558 * {@code beginRequest} is a no-op. 1559 *<p> 1560 * The exact behavior of this method is vendor specific. In particular 1561 * implementations may detect conditions that indicate dependence on 1562 * other work such as an open transaction. It is recommended though not 1563 * required that implementations throw a {@code SQLException} if there is an active 1564 * transaction and {@code endRequest} is called. 1565 * 1566 * @implSpec 1567 * The default implementation is a no-op. 1568 * @apiNote 1569 * 1570 * This method is to be used by Connection pooling managers. 1571 * <p> 1572 * The pooling manager should call {@code endRequest} on the underlying connection 1573 * when the applications returns the connection back to the connection pool. 1574 * <p> 1575 * The pooling manager does not need to call {@code endRequest} if: 1576 * <ul> 1577 * <li>The connection pool caches {@code PooledConnection} objects</li> 1578 * <li>Returns a logical connection handle when {@code getConnection} is 1579 * called by the application</li> 1580 * <li>The pool manager calls {@code Connection.close} on the logical connection handle 1581 * prior to returning the {@code PooledConnection} back to the cache</li> 1582 * </ul> 1583 * @throws SQLException if an error occurs 1584 * @since 9 1585 * @see beginRequest 1586 * @see javax.sql.PooledConnection 1587 */ 1588 default void endRequest() throws SQLException { 1589 // Default method takes no action 1590 } 1591 1592 /** 1593 * Sets and validates the sharding keys for this connection. 1594 * @implSpec 1595 * The default implementation will throw a 1596 * {@code SQLFeatureNotSupportedException}. 1597 * 1598 * @apiNote 1599 * This method validates that the sharding keys are valid for the 1600 * {@code Connection}. The timeout value indicates how long the driver 1601 * should wait for the {@code Connection} to verify that the sharding key 1602 * is valid before {@code setShardingKeyIfValid} returns false. 1603 * @param shardingKey the sharding key to be validated against this connection 1604 * @param superShardingKey the super sharding key to be validated against this 1605 * connection. The super sharding key may be {@code null}. 1606 * @param timeout time in seconds before which the validation process is expected to 1607 * be completed, otherwise the validation process is aborted. A value of 0 indicates 1608 * the validation process will not time out. 1609 * @return true if the connection is valid and the sharding keys are valid 1610 * and set on this connection; false if the sharding keys are not valid or 1611 * the timeout period expires before the operation completes. 1612 * @throws SQLException if an error occurs while performing this validation; 1613 * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified 1614 * without a {@code shardingKey}; 1615 * this method is called on a closed {@code connection}; or 1616 * the {@code timeout} value is less than 0. 1617 * @throws SQLFeatureNotSupportedException if the driver does not support sharding 1618 * @since 9 1619 * @see ShardingKey 1620 * @see ShardingKeyBuilder 1621 */ 1622 default boolean setShardingKeyIfValid(ShardingKey shardingKey, 1623 ShardingKey superShardingKey, int timeout) 1624 throws SQLException { 1625 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented"); 1626 } 1627 1628 /** 1629 * Sets and validates the sharding key for this connection. 1630 * @implSpec 1631 * The default implementation will throw a 1632 * {@code SQLFeatureNotSupportedException}. 1633 * @apiNote 1634 * This method validates that the sharding key is valid for the 1635 * {@code Connection}. The timeout value indicates how long the driver 1636 * should wait for the {@code Connection} to verify that the sharding key 1637 * is valid before {@code setShardingKeyIfValid} returns false. 1638 * @param shardingKey the sharding key to be validated against this connection 1639 * @param timeout time in seconds before which the validation process is expected to 1640 * be completed,else the validation process is aborted. A value of 0 indicates 1641 * the validation process will not time out. 1642 * @return true if the connection is valid and the sharding key is valid to be 1643 * set on this connection; false if the sharding key is not valid or 1644 * the timeout period expires before the operation completes. 1645 * @throws SQLException if there is an error while performing this validation; 1646 * this method is called on a closed {@code connection}; the {@code shardingkey} 1647 * is {@code null}; or the {@code timeout} value is less than 0. 1648 * @throws SQLFeatureNotSupportedException if the driver does not support sharding 1649 * @since 9 1650 * @see ShardingKey 1651 * @see ShardingKeyBuilder 1652 */ 1653 default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout) 1654 throws SQLException { 1655 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented"); 1656 } 1657 1658 /** 1659 * Specifies a shardingKey and superShardingKey to use with this Connection 1660 * @implSpec 1661 * The default implementation will throw a 1662 * {@code SQLFeatureNotSupportedException}. 1663 * @apiNote 1664 * This method sets the specified sharding keys but does not require a 1665 * round trip to the database to validate that the sharding keys are valid 1666 * for the {@code Connection}. 1667 * @param shardingKey the sharding key to set on this connection. 1668 * @param superShardingKey the super sharding key to set on this connection. 1669 * The super sharding key may be {@code null} 1670 * @throws SQLException if an error occurs setting the sharding keys; 1671 * this method is called on a closed {@code connection}; 1672 * the {@code shardingkey} is {@code null}; or 1673 * a {@code superSharedingKey} is specified without a {@code shardingKey} 1674 * @throws SQLFeatureNotSupportedException if the driver does not support sharding 1675 * @since 9 1676 * @see ShardingKey 1677 * @see ShardingKeyBuilder 1678 */ 1679 default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey) 1680 throws SQLException { 1681 throw new SQLFeatureNotSupportedException("setShardingKey not implemented"); 1682 } 1683 1684 /** 1685 * Specifies a shardingKey to use with this Connection 1686 * @implSpec 1687 * The default implementation will throw a 1688 * {@code SQLFeatureNotSupportedException}. 1689 * @apiNote 1690 * This method sets the specified sharding key but does not require a 1691 * round trip to the database to validate that the sharding key is valid 1692 * for the {@code Connection}. 1693 * @param shardingKey the sharding key to set on this connection. 1694 * @throws SQLException if an error occurs setting the sharding key; 1695 * this method is called on a closed {@code connection}; or the 1696 * {@code shardkingKey} is {@code null} 1697 * @throws SQLFeatureNotSupportedException if the driver does not support sharding 1698 * @since 9 1699 * @see ShardingKey 1700 * @see ShardingKeyBuilder 1701 */ 1702 default void setShardingKey(ShardingKey shardingKey) 1703 throws SQLException { 1704 throw new SQLFeatureNotSupportedException("setShardingKey not implemented"); 1705 } 1706 }