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