1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 package java.sql; 28 29 import java.util.Properties; 30 import java.util.concurrent.Executor; 31 32 /** 33 * <P>A connection (session) with a specific 34 * database. SQL statements are executed and results are returned 35 * within the context of a connection. 36 * <P> 37 * A <code>Connection</code> object's database is able to provide information 38 * describing its tables, its supported SQL grammar, its stored 39 * procedures, the capabilities of this connection, and so on. This 40 * information is obtained with the <code>getMetaData</code> method. 41 * 42 * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications 43 * should use the appropriate <code>Connection</code> method such as 44 * <code>setAutoCommit</code> or <code>setTransactionIsolation</code>. 45 * Applications should not invoke SQL commands directly to change the connection's 46 * configuration when there is a JDBC method available. By default a <code>Connection</code> object is in 47 * auto-commit mode, which means that it automatically commits changes 48 * after executing each statement. If auto-commit mode has been 49 * disabled, the method <code>commit</code> must be called explicitly in 50 * order to commit changes; otherwise, database changes will not be saved. 51 * <P> 52 * A new <code>Connection</code> object created using the JDBC 2.1 core API 53 * has an initially empty type map associated with it. A user may enter a 54 * custom mapping for a UDT in this type map. 55 * When a UDT is retrieved from a data source with the 56 * method <code>ResultSet.getObject</code>, the <code>getObject</code> method 57 * will check the connection's type map to see if there is an entry for that 58 * UDT. If so, the <code>getObject</code> method will map the UDT to the 59 * class indicated. If there is no entry, the UDT will be mapped using the 60 * standard mapping. 61 * <p> 62 * A user may create a new type map, which is a <code>java.util.Map</code> 63 * object, make an entry in it, and pass it to the <code>java.sql</code> 64 * methods that can perform custom mapping. In this case, the method 65 * will use the given type map instead of the one associated with 66 * the connection. 67 * <p> 68 * For example, the following code fragment specifies that the SQL 69 * type <code>ATHLETES</code> will be mapped to the class 70 * <code>Athletes</code> in the Java programming language. 71 * The code fragment retrieves the type map for the <code>Connection 72 * </code> object <code>con</code>, inserts the entry into it, and then sets 73 * the type map with the new entry as the connection's type map. 74 * <pre> 75 * java.util.Map map = con.getTypeMap(); 76 * map.put("mySchemaName.ATHLETES", Class.forName("Athletes")); 77 * con.setTypeMap(map); 78 * </pre> 79 * 80 * @see DriverManager#getConnection 81 * @see Statement 82 * @see ResultSet 83 * @see DatabaseMetaData 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 */ createStatement()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 */ prepareStatement(String sql)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 */ prepareCall(String sql)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 */ nativeSQL(String sql)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 */ setAutoCommit(boolean autoCommit)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 */ getAutoCommit()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 conection or this 247 * <code>Connection</code> object is in auto-commit mode 248 * @see #setAutoCommit 249 */ commit()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 */ rollback()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 * <P> 278 * 279 * @exception SQLException SQLException if a database access error occurs 280 */ close()281 void close() throws SQLException; 282 283 /** 284 * Retrieves whether this <code>Connection</code> object has been 285 * closed. A connection is closed if the method <code>close</code> 286 * has been called on it or if certain fatal errors have occurred. 287 * This method is guaranteed to return <code>true</code> only when 288 * it is called after the method <code>Connection.close</code> has 289 * been called. 290 * <P> 291 * This method generally cannot be called to determine whether a 292 * connection to a database is valid or invalid. A typical client 293 * can determine that a connection is invalid by catching any 294 * exceptions that might be thrown when an operation is attempted. 295 * 296 * @return <code>true</code> if this <code>Connection</code> object 297 * is closed; <code>false</code> if it is still open 298 * @exception SQLException if a database access error occurs 299 */ isClosed()300 boolean isClosed() throws SQLException; 301 302 //====================================================================== 303 // Advanced features: 304 305 /** 306 * Retrieves a <code>DatabaseMetaData</code> object that contains 307 * metadata about the database to which this 308 * <code>Connection</code> object represents a connection. 309 * The metadata includes information about the database's 310 * tables, its supported SQL grammar, its stored 311 * procedures, the capabilities of this connection, and so on. 312 * 313 * @return a <code>DatabaseMetaData</code> object for this 314 * <code>Connection</code> object 315 * @exception SQLException if a database access error occurs 316 * or this method is called on a closed connection 317 */ getMetaData()318 DatabaseMetaData getMetaData() throws SQLException; 319 320 /** 321 * Puts this connection in read-only mode as a hint to the driver to enable 322 * database optimizations. 323 * 324 * <P><B>Note:</B> This method cannot be called during a transaction. 325 * 326 * @param readOnly <code>true</code> enables read-only mode; 327 * <code>false</code> disables it 328 * @exception SQLException if a database access error occurs, this 329 * method is called on a closed connection or this 330 * method is called during a transaction 331 */ setReadOnly(boolean readOnly)332 void setReadOnly(boolean readOnly) throws SQLException; 333 334 /** 335 * Retrieves whether this <code>Connection</code> 336 * object is in read-only mode. 337 * 338 * @return <code>true</code> if this <code>Connection</code> object 339 * is read-only; <code>false</code> otherwise 340 * @exception SQLException SQLException if a database access error occurs 341 * or this method is called on a closed connection 342 */ isReadOnly()343 boolean isReadOnly() throws SQLException; 344 345 /** 346 * Sets the given catalog name in order to select 347 * a subspace of this <code>Connection</code> object's database 348 * in which to work. 349 * <P> 350 * If the driver does not support catalogs, it will 351 * silently ignore this request. 352 * <p> 353 * Calling {@code setCatalog} has no effect on previously created or prepared 354 * {@code Statement} objects. It is implementation defined whether a DBMS 355 * prepare operation takes place immediately when the {@code Connection} 356 * method {@code prepareStatement} or {@code prepareCall} is invoked. 357 * For maximum portability, {@code setCatalog} should be called before a 358 * {@code Statement} is created or prepared. 359 * 360 * @param catalog the name of a catalog (subspace in this 361 * <code>Connection</code> object's database) in which to work 362 * @exception SQLException if a database access error occurs 363 * or this method is called on a closed connection 364 * @see #getCatalog 365 */ setCatalog(String catalog)366 void setCatalog(String catalog) throws SQLException; 367 368 /** 369 * Retrieves this <code>Connection</code> object's current catalog name. 370 * 371 * @return the current catalog name or <code>null</code> if there is none 372 * @exception SQLException if a database access error occurs 373 * or this method is called on a closed connection 374 * @see #setCatalog 375 */ getCatalog()376 String getCatalog() throws SQLException; 377 378 /** 379 * A constant indicating that transactions are not supported. 380 */ 381 int TRANSACTION_NONE = 0; 382 383 /** 384 * A constant indicating that 385 * dirty reads, non-repeatable reads and phantom reads can occur. 386 * This level allows a row changed by one transaction to be read 387 * by another transaction before any changes in that row have been 388 * committed (a "dirty read"). If any of the changes are rolled back, 389 * the second transaction will have retrieved an invalid row. 390 */ 391 int TRANSACTION_READ_UNCOMMITTED = 1; 392 393 /** 394 * A constant indicating that 395 * dirty reads are prevented; non-repeatable reads and phantom 396 * reads can occur. This level only prohibits a transaction 397 * from reading a row with uncommitted changes in it. 398 */ 399 int TRANSACTION_READ_COMMITTED = 2; 400 401 /** 402 * A constant indicating that 403 * dirty reads and non-repeatable reads are prevented; phantom 404 * reads can occur. This level prohibits a transaction from 405 * reading a row with uncommitted changes in it, and it also 406 * prohibits the situation where one transaction reads a row, 407 * a second transaction alters the row, and the first transaction 408 * rereads the row, getting different values the second time 409 * (a "non-repeatable read"). 410 */ 411 int TRANSACTION_REPEATABLE_READ = 4; 412 413 /** 414 * A constant indicating that 415 * dirty reads, non-repeatable reads and phantom reads are prevented. 416 * This level includes the prohibitions in 417 * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the 418 * situation where one transaction reads all rows that satisfy 419 * a <code>WHERE</code> condition, a second transaction inserts a row that 420 * satisfies that <code>WHERE</code> condition, and the first transaction 421 * rereads for the same condition, retrieving the additional 422 * "phantom" row in the second read. 423 */ 424 int TRANSACTION_SERIALIZABLE = 8; 425 426 /** 427 * Attempts to change the transaction isolation level for this 428 * <code>Connection</code> object to the one given. 429 * The constants defined in the interface <code>Connection</code> 430 * are the possible transaction isolation levels. 431 * <P> 432 * <B>Note:</B> If this method is called during a transaction, the result 433 * is implementation-defined. 434 * 435 * @param level one of the following <code>Connection</code> constants: 436 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 437 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 438 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or 439 * <code>Connection.TRANSACTION_SERIALIZABLE</code>. 440 * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used 441 * because it specifies that transactions are not supported.) 442 * @exception SQLException if a database access error occurs, this 443 * method is called on a closed connection 444 * or the given parameter is not one of the <code>Connection</code> 445 * constants 446 * @see DatabaseMetaData#supportsTransactionIsolationLevel 447 * @see #getTransactionIsolation 448 */ setTransactionIsolation(int level)449 void setTransactionIsolation(int level) throws SQLException; 450 451 /** 452 * Retrieves this <code>Connection</code> object's current 453 * transaction isolation level. 454 * 455 * @return the current transaction isolation level, which will be one 456 * of the following constants: 457 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 458 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 459 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, 460 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or 461 * <code>Connection.TRANSACTION_NONE</code>. 462 * @exception SQLException if a database access error occurs 463 * or this method is called on a closed connection 464 * @see #setTransactionIsolation 465 */ getTransactionIsolation()466 int getTransactionIsolation() throws SQLException; 467 468 /** 469 * Retrieves the first warning reported by calls on this 470 * <code>Connection</code> object. If there is more than one 471 * warning, subsequent warnings will be chained to the first one 472 * and can be retrieved by calling the method 473 * <code>SQLWarning.getNextWarning</code> on the warning 474 * that was retrieved previously. 475 * <P> 476 * This method may not be 477 * called on a closed connection; doing so will cause an 478 * <code>SQLException</code> to be thrown. 479 * 480 * <P><B>Note:</B> Subsequent warnings will be chained to this 481 * SQLWarning. 482 * 483 * @return the first <code>SQLWarning</code> object or <code>null</code> 484 * if there are none 485 * @exception SQLException if a database access error occurs or 486 * this method is called on a closed connection 487 * @see SQLWarning 488 */ getWarnings()489 SQLWarning getWarnings() throws SQLException; 490 491 /** 492 * Clears all warnings reported for this <code>Connection</code> object. 493 * After a call to this method, the method <code>getWarnings</code> 494 * returns <code>null</code> until a new warning is 495 * reported for this <code>Connection</code> object. 496 * 497 * @exception SQLException SQLException if a database access error occurs 498 * or this method is called on a closed connection 499 */ clearWarnings()500 void clearWarnings() throws SQLException; 501 502 503 //--------------------------JDBC 2.0----------------------------- 504 505 /** 506 * Creates a <code>Statement</code> object that will generate 507 * <code>ResultSet</code> objects with the given type and concurrency. 508 * This method is the same as the <code>createStatement</code> method 509 * above, but it allows the default result set 510 * type and concurrency to be overridden. 511 * The holdability of the created result sets can be determined by 512 * calling {@link #getHoldability}. 513 * 514 * @param resultSetType a result set type; one of 515 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 516 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 517 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 518 * @param resultSetConcurrency a concurrency type; one of 519 * <code>ResultSet.CONCUR_READ_ONLY</code> or 520 * <code>ResultSet.CONCUR_UPDATABLE</code> 521 * @return a new <code>Statement</code> object that will generate 522 * <code>ResultSet</code> objects with the given type and 523 * concurrency 524 * @exception SQLException if a database access error occurs, this 525 * method is called on a closed connection 526 * or the given parameters are not <code>ResultSet</code> 527 * constants indicating type and concurrency 528 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 529 * this method or this method is not supported for the specified result 530 * set type and result set concurrency. 531 * @since 1.2 532 */ createStatement(int resultSetType, int resultSetConcurrency)533 Statement createStatement(int resultSetType, int resultSetConcurrency) 534 throws SQLException; 535 536 /** 537 * 538 * Creates a <code>PreparedStatement</code> object that will generate 539 * <code>ResultSet</code> objects with the given type and concurrency. 540 * This method is the same as the <code>prepareStatement</code> method 541 * above, but it allows the default result set 542 * type and concurrency to be overridden. 543 * The holdability of the created result sets can be determined by 544 * calling {@link #getHoldability}. 545 * 546 * @param sql a <code>String</code> object that is the SQL statement to 547 * be sent to the database; may contain one or more '?' IN 548 * parameters 549 * @param resultSetType a result set type; one of 550 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 551 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 552 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 553 * @param resultSetConcurrency a concurrency type; one of 554 * <code>ResultSet.CONCUR_READ_ONLY</code> or 555 * <code>ResultSet.CONCUR_UPDATABLE</code> 556 * @return a new PreparedStatement object containing the 557 * pre-compiled SQL statement that will produce <code>ResultSet</code> 558 * objects with the given type and concurrency 559 * @exception SQLException if a database access error occurs, this 560 * method is called on a closed connection 561 * or the given parameters are not <code>ResultSet</code> 562 * constants indicating type and concurrency 563 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 564 * this method or this method is not supported for the specified result 565 * set type and result set concurrency. 566 * @since 1.2 567 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency)568 PreparedStatement prepareStatement(String sql, int resultSetType, 569 int resultSetConcurrency) 570 throws SQLException; 571 572 /** 573 * Creates a <code>CallableStatement</code> object that will generate 574 * <code>ResultSet</code> objects with the given type and concurrency. 575 * This method is the same as the <code>prepareCall</code> method 576 * above, but it allows the default result set 577 * type and concurrency to be overridden. 578 * The holdability of the created result sets can be determined by 579 * calling {@link #getHoldability}. 580 * 581 * @param sql a <code>String</code> object that is the SQL statement to 582 * be sent to the database; may contain on or more '?' parameters 583 * @param resultSetType a result set type; one of 584 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 585 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 586 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 587 * @param resultSetConcurrency a concurrency type; one of 588 * <code>ResultSet.CONCUR_READ_ONLY</code> or 589 * <code>ResultSet.CONCUR_UPDATABLE</code> 590 * @return a new <code>CallableStatement</code> object containing the 591 * pre-compiled SQL statement that will produce <code>ResultSet</code> 592 * objects with the given type and concurrency 593 * @exception SQLException if a database access error occurs, this method 594 * is called on a closed connection 595 * or the given parameters are not <code>ResultSet</code> 596 * constants indicating type and concurrency 597 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 598 * this method or this method is not supported for the specified result 599 * set type and result set concurrency. 600 * @since 1.2 601 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency)602 CallableStatement prepareCall(String sql, int resultSetType, 603 int resultSetConcurrency) throws SQLException; 604 605 /** 606 * Retrieves the <code>Map</code> object associated with this 607 * <code>Connection</code> object. 608 * Unless the application has added an entry, the type map returned 609 * will be empty. 610 * <p> 611 * You must invoke <code>setTypeMap</code> after making changes to the 612 * <code>Map</code> object returned from 613 * <code>getTypeMap</code> as a JDBC driver may create an internal 614 * copy of the <code>Map</code> object passed to <code>setTypeMap</code>: 615 * <p> 616 * <pre> 617 * Map<String,Class<?>> myMap = con.getTypeMap(); 618 * myMap.put("mySchemaName.ATHLETES", Athletes.class); 619 * con.setTypeMap(myMap); 620 * </pre> 621 * @return the <code>java.util.Map</code> object associated 622 * with this <code>Connection</code> object 623 * @exception SQLException if a database access error occurs 624 * or this method is called on a closed connection 625 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 626 * this method 627 * @since 1.2 628 * @see #setTypeMap 629 */ getTypeMap()630 java.util.Map<String,Class<?>> getTypeMap() throws SQLException; 631 632 /** 633 * Installs the given <code>TypeMap</code> object as the type map for 634 * this <code>Connection</code> object. The type map will be used for the 635 * custom mapping of SQL structured types and distinct types. 636 *<p> 637 * You must set the the values for the <code>TypeMap</code> prior to 638 * callng <code>setMap</code> as a JDBC driver may create an internal copy 639 * of the <code>TypeMap</code>: 640 * <p> 641 * <pre> 642 * Map myMap<String,Class<?>> = new HashMap<String,Class<?>>(); 643 * myMap.put("mySchemaName.ATHLETES", Athletes.class); 644 * con.setTypeMap(myMap); 645 * </pre> 646 * @param map the <code>java.util.Map</code> object to install 647 * as the replacement for this <code>Connection</code> 648 * object's default type map 649 * @exception SQLException if a database access error occurs, this 650 * method is called on a closed connection or 651 * the given parameter is not a <code>java.util.Map</code> 652 * object 653 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 654 * this method 655 * @since 1.2 656 * @see #getTypeMap 657 */ setTypeMap(java.util.Map<String,Class<?>> map)658 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException; 659 660 //--------------------------JDBC 3.0----------------------------- 661 662 663 /** 664 * Changes the default holdability of <code>ResultSet</code> objects 665 * created using this <code>Connection</code> object to the given 666 * holdability. The default holdability of <code>ResultSet</code> objects 667 * can be be determined by invoking 668 * {@link DatabaseMetaData#getResultSetHoldability}. 669 * 670 * @param holdability a <code>ResultSet</code> holdability constant; one of 671 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 672 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 673 * @throws SQLException if a database access occurs, this method is called 674 * on a closed connection, or the given parameter 675 * is not a <code>ResultSet</code> constant indicating holdability 676 * @exception SQLFeatureNotSupportedException if the given holdability is not supported 677 * @see #getHoldability 678 * @see DatabaseMetaData#getResultSetHoldability 679 * @see ResultSet 680 * @since 1.4 681 */ setHoldability(int holdability)682 void setHoldability(int holdability) throws SQLException; 683 684 /** 685 * Retrieves the current holdability of <code>ResultSet</code> objects 686 * created using this <code>Connection</code> object. 687 * 688 * @return the holdability, one of 689 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 690 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 691 * @throws SQLException if a database access error occurs 692 * or this method is called on a closed connection 693 * @see #setHoldability 694 * @see DatabaseMetaData#getResultSetHoldability 695 * @see ResultSet 696 * @since 1.4 697 */ getHoldability()698 int getHoldability() throws SQLException; 699 700 /** 701 * Creates an unnamed savepoint in the current transaction and 702 * returns the new <code>Savepoint</code> object that represents it. 703 * 704 *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 705 *savepoint. 706 * 707 * @return the new <code>Savepoint</code> object 708 * @exception SQLException if a database access error occurs, 709 * this method is called while participating in a distributed transaction, 710 * this method is called on a closed connection 711 * or this <code>Connection</code> object is currently in 712 * auto-commit mode 713 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 714 * this method 715 * @see Savepoint 716 * @since 1.4 717 */ setSavepoint()718 Savepoint setSavepoint() throws SQLException; 719 720 /** 721 * Creates a savepoint with the given name in the current transaction 722 * and returns the new <code>Savepoint</code> object that represents it. 723 * 724 * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 725 *savepoint. 726 * 727 * @param name a <code>String</code> containing the name of the savepoint 728 * @return the new <code>Savepoint</code> object 729 * @exception SQLException if a database access error occurs, 730 * this method is called while participating in a distributed transaction, 731 * this method is called on a closed connection 732 * or this <code>Connection</code> object is currently in 733 * auto-commit mode 734 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 735 * this method 736 * @see Savepoint 737 * @since 1.4 738 */ setSavepoint(String name)739 Savepoint setSavepoint(String name) throws SQLException; 740 741 /** 742 * Undoes all changes made after the given <code>Savepoint</code> object 743 * was set. 744 * <P> 745 * This method should be used only when auto-commit has been disabled. 746 * 747 * @param savepoint the <code>Savepoint</code> object to roll back to 748 * @exception SQLException if a database access error occurs, 749 * this method is called while participating in a distributed transaction, 750 * this method is called on a closed connection, 751 * the <code>Savepoint</code> object is no longer valid, 752 * or this <code>Connection</code> object is currently in 753 * auto-commit mode 754 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 755 * this method 756 * @see Savepoint 757 * @see #rollback 758 * @since 1.4 759 */ rollback(Savepoint savepoint)760 void rollback(Savepoint savepoint) throws SQLException; 761 762 /** 763 * Removes the specified <code>Savepoint</code> and subsequent <code>Savepoint</code> objects from the current 764 * transaction. Any reference to the savepoint after it have been removed 765 * will cause an <code>SQLException</code> to be thrown. 766 * 767 * @param savepoint the <code>Savepoint</code> object to be removed 768 * @exception SQLException if a database access error occurs, this 769 * method is called on a closed connection or 770 * the given <code>Savepoint</code> object is not a valid 771 * savepoint in the current transaction 772 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 773 * this method 774 * @since 1.4 775 */ releaseSavepoint(Savepoint savepoint)776 void releaseSavepoint(Savepoint savepoint) throws SQLException; 777 778 /** 779 * Creates a <code>Statement</code> object that will generate 780 * <code>ResultSet</code> objects with the given type, concurrency, 781 * and holdability. 782 * This method is the same as the <code>createStatement</code> method 783 * above, but it allows the default result set 784 * type, concurrency, and holdability to be overridden. 785 * 786 * @param resultSetType one of the following <code>ResultSet</code> 787 * constants: 788 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 789 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 790 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 791 * @param resultSetConcurrency one of the following <code>ResultSet</code> 792 * constants: 793 * <code>ResultSet.CONCUR_READ_ONLY</code> or 794 * <code>ResultSet.CONCUR_UPDATABLE</code> 795 * @param resultSetHoldability one of the following <code>ResultSet</code> 796 * constants: 797 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 798 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 799 * @return a new <code>Statement</code> object that will generate 800 * <code>ResultSet</code> objects with the given type, 801 * concurrency, and holdability 802 * @exception SQLException if a database access error occurs, this 803 * method is called on a closed connection 804 * or the given parameters are not <code>ResultSet</code> 805 * constants indicating type, concurrency, and holdability 806 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 807 * this method or this method is not supported for the specified result 808 * set type, result set holdability and result set concurrency. 809 * @see ResultSet 810 * @since 1.4 811 */ createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)812 Statement createStatement(int resultSetType, int resultSetConcurrency, 813 int resultSetHoldability) throws SQLException; 814 815 /** 816 * Creates a <code>PreparedStatement</code> object that will generate 817 * <code>ResultSet</code> objects with the given type, concurrency, 818 * and holdability. 819 * <P> 820 * This method is the same as the <code>prepareStatement</code> method 821 * above, but it allows the default result set 822 * type, concurrency, and holdability to be overridden. 823 * 824 * @param sql a <code>String</code> object that is the SQL statement to 825 * be sent to the database; may contain one or more '?' IN 826 * parameters 827 * @param resultSetType one of the following <code>ResultSet</code> 828 * constants: 829 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 830 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 831 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 832 * @param resultSetConcurrency one of the following <code>ResultSet</code> 833 * constants: 834 * <code>ResultSet.CONCUR_READ_ONLY</code> or 835 * <code>ResultSet.CONCUR_UPDATABLE</code> 836 * @param resultSetHoldability one of the following <code>ResultSet</code> 837 * constants: 838 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 839 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 840 * @return a new <code>PreparedStatement</code> object, containing the 841 * pre-compiled SQL statement, that will generate 842 * <code>ResultSet</code> objects with the given type, 843 * concurrency, and holdability 844 * @exception SQLException if a database access error occurs, this 845 * method is called on a closed connection 846 * or the given parameters are not <code>ResultSet</code> 847 * constants indicating type, concurrency, and holdability 848 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 849 * this method or this method is not supported for the specified result 850 * set type, result set holdability and result set concurrency. 851 * @see ResultSet 852 * @since 1.4 853 */ prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)854 PreparedStatement prepareStatement(String sql, int resultSetType, 855 int resultSetConcurrency, int resultSetHoldability) 856 throws SQLException; 857 858 /** 859 * Creates a <code>CallableStatement</code> object that will generate 860 * <code>ResultSet</code> objects with the given type and concurrency. 861 * This method is the same as the <code>prepareCall</code> method 862 * above, but it allows the default result set 863 * type, result set concurrency type and holdability to be overridden. 864 * 865 * @param sql a <code>String</code> object that is the SQL statement to 866 * be sent to the database; may contain on or more '?' parameters 867 * @param resultSetType one of the following <code>ResultSet</code> 868 * constants: 869 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 870 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 871 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 872 * @param resultSetConcurrency one of the following <code>ResultSet</code> 873 * constants: 874 * <code>ResultSet.CONCUR_READ_ONLY</code> or 875 * <code>ResultSet.CONCUR_UPDATABLE</code> 876 * @param resultSetHoldability one of the following <code>ResultSet</code> 877 * constants: 878 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or 879 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code> 880 * @return a new <code>CallableStatement</code> object, containing the 881 * pre-compiled SQL statement, that will generate 882 * <code>ResultSet</code> objects with the given type, 883 * concurrency, and holdability 884 * @exception SQLException if a database access error occurs, this 885 * method is called on a closed connection 886 * or the given parameters are not <code>ResultSet</code> 887 * constants indicating type, concurrency, and holdability 888 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 889 * this method or this method is not supported for the specified result 890 * set type, result set holdability and result set concurrency. 891 * @see ResultSet 892 * @since 1.4 893 */ prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)894 CallableStatement prepareCall(String sql, int resultSetType, 895 int resultSetConcurrency, 896 int resultSetHoldability) throws SQLException; 897 898 899 /** 900 * Creates a default <code>PreparedStatement</code> object that has 901 * the capability to retrieve auto-generated keys. The given constant 902 * tells the driver whether it should make auto-generated keys 903 * available for retrieval. This parameter is ignored if the SQL statement 904 * is not an <code>INSERT</code> statement, or an SQL statement able to return 905 * auto-generated keys (the list of such statements is vendor-specific). 906 * <P> 907 * <B>Note:</B> This method is optimized for handling 908 * parametric SQL statements that benefit from precompilation. If 909 * the driver supports precompilation, 910 * the method <code>prepareStatement</code> will send 911 * the statement to the database for precompilation. Some drivers 912 * may not support precompilation. In this case, the statement may 913 * not be sent to the database until the <code>PreparedStatement</code> 914 * object is executed. This has no direct effect on users; however, it does 915 * affect which methods throw certain SQLExceptions. 916 * <P> 917 * Result sets created using the returned <code>PreparedStatement</code> 918 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 919 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 920 * The holdability of the created result sets can be determined by 921 * calling {@link #getHoldability}. 922 * 923 * @param sql an SQL statement that may contain one or more '?' IN 924 * parameter placeholders 925 * @param autoGeneratedKeys a flag indicating whether auto-generated keys 926 * should be returned; one of 927 * <code>Statement.RETURN_GENERATED_KEYS</code> or 928 * <code>Statement.NO_GENERATED_KEYS</code> 929 * @return a new <code>PreparedStatement</code> object, containing the 930 * pre-compiled SQL statement, that will have the capability of 931 * returning auto-generated keys 932 * @exception SQLException if a database access error occurs, this 933 * method is called on a closed connection 934 * or the given parameter is not a <code>Statement</code> 935 * constant indicating whether auto-generated keys should be 936 * returned 937 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 938 * this method with a constant of Statement.RETURN_GENERATED_KEYS 939 * @since 1.4 940 */ prepareStatement(String sql, int autoGeneratedKeys)941 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) 942 throws SQLException; 943 944 /** 945 * Creates a default <code>PreparedStatement</code> object capable 946 * of returning the auto-generated keys designated by the given array. 947 * This array contains the indexes of the columns in the target 948 * table that contain the auto-generated keys that should be made 949 * available. The driver will ignore the array if the SQL statement 950 * is not an <code>INSERT</code> statement, or an SQL statement able to return 951 * auto-generated keys (the list of such statements is vendor-specific). 952 *<p> 953 * An SQL statement with or without IN parameters can be 954 * pre-compiled and stored in a <code>PreparedStatement</code> object. This 955 * object can then be used to efficiently execute this statement 956 * multiple times. 957 * <P> 958 * <B>Note:</B> This method is optimized for handling 959 * parametric SQL statements that benefit from precompilation. If 960 * the driver supports precompilation, 961 * the method <code>prepareStatement</code> will send 962 * the statement to the database for precompilation. Some drivers 963 * may not support precompilation. In this case, the statement may 964 * not be sent to the database until the <code>PreparedStatement</code> 965 * object is executed. This has no direct effect on users; however, it does 966 * affect which methods throw certain SQLExceptions. 967 * <P> 968 * Result sets created using the returned <code>PreparedStatement</code> 969 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 970 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 971 * The holdability of the created result sets can be determined by 972 * calling {@link #getHoldability}. 973 * 974 * @param sql an SQL statement that may contain one or more '?' IN 975 * parameter placeholders 976 * @param columnIndexes an array of column indexes indicating the columns 977 * that should be returned from the inserted row or rows 978 * @return a new <code>PreparedStatement</code> object, containing the 979 * pre-compiled statement, that is capable of returning the 980 * auto-generated keys designated by the given array of column 981 * indexes 982 * @exception SQLException if a database access error occurs 983 * or this method is called on a closed connection 984 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 985 * this method 986 * 987 * @since 1.4 988 */ prepareStatement(String sql, int columnIndexes[])989 PreparedStatement prepareStatement(String sql, int columnIndexes[]) 990 throws SQLException; 991 992 /** 993 * Creates a default <code>PreparedStatement</code> object capable 994 * of returning the auto-generated keys designated by the given array. 995 * This array contains the names of the columns in the target 996 * table that contain the auto-generated keys that should be returned. 997 * The driver will ignore the array if the SQL statement 998 * is not an <code>INSERT</code> statement, or an SQL statement able to return 999 * auto-generated keys (the list of such statements is vendor-specific). 1000 * <P> 1001 * An SQL statement with or without IN parameters can be 1002 * pre-compiled and stored in a <code>PreparedStatement</code> object. This 1003 * object can then be used to efficiently execute this statement 1004 * multiple times. 1005 * <P> 1006 * <B>Note:</B> This method is optimized for handling 1007 * parametric SQL statements that benefit from precompilation. If 1008 * the driver supports precompilation, 1009 * the method <code>prepareStatement</code> will send 1010 * the statement to the database for precompilation. Some drivers 1011 * may not support precompilation. In this case, the statement may 1012 * not be sent to the database until the <code>PreparedStatement</code> 1013 * object is executed. This has no direct effect on users; however, it does 1014 * affect which methods throw certain SQLExceptions. 1015 * <P> 1016 * Result sets created using the returned <code>PreparedStatement</code> 1017 * object will by default be type <code>TYPE_FORWARD_ONLY</code> 1018 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 1019 * The holdability of the created result sets can be determined by 1020 * calling {@link #getHoldability}. 1021 * 1022 * @param sql an SQL statement that may contain one or more '?' IN 1023 * parameter placeholders 1024 * @param columnNames an array of column names indicating the columns 1025 * that should be returned from the inserted row or rows 1026 * @return a new <code>PreparedStatement</code> object, containing the 1027 * pre-compiled statement, that is capable of returning the 1028 * auto-generated keys designated by the given array of column 1029 * names 1030 * @exception SQLException if a database access error occurs 1031 * or this method is called on a closed connection 1032 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1033 * this method 1034 * 1035 * @since 1.4 1036 */ prepareStatement(String sql, String columnNames[])1037 PreparedStatement prepareStatement(String sql, String columnNames[]) 1038 throws SQLException; 1039 1040 /** 1041 * Constructs an object that implements the <code>Clob</code> interface. The object 1042 * returned initially contains no data. The <code>setAsciiStream</code>, 1043 * <code>setCharacterStream</code> and <code>setString</code> methods of 1044 * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>. 1045 * @return An object that implements the <code>Clob</code> interface 1046 * @throws SQLException if an object that implements the 1047 * <code>Clob</code> interface can not be constructed, this method is 1048 * called on a closed connection or a database access error occurs. 1049 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1050 * this data type 1051 * 1052 * @since 1.6 1053 */ createClob()1054 Clob createClob() throws SQLException; 1055 1056 /** 1057 * Constructs an object that implements the <code>Blob</code> interface. The object 1058 * returned initially contains no data. The <code>setBinaryStream</code> and 1059 * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to 1060 * the <code>Blob</code>. 1061 * @return An object that implements the <code>Blob</code> interface 1062 * @throws SQLException if an object that implements the 1063 * <code>Blob</code> interface can not be constructed, this method is 1064 * called on a closed connection or a database access error occurs. 1065 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1066 * this data type 1067 * 1068 * @since 1.6 1069 */ createBlob()1070 Blob createBlob() throws SQLException; 1071 1072 /** 1073 * Constructs an object that implements the <code>NClob</code> interface. The object 1074 * returned initially contains no data. The <code>setAsciiStream</code>, 1075 * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may 1076 * be used to add data to the <code>NClob</code>. 1077 * @return An object that implements the <code>NClob</code> interface 1078 * @throws SQLException if an object that implements the 1079 * <code>NClob</code> interface can not be constructed, this method is 1080 * called on a closed connection or a database access error occurs. 1081 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1082 * this data type 1083 * 1084 * @since 1.6 1085 */ createNClob()1086 NClob createNClob() throws SQLException; 1087 1088 /** 1089 * Constructs an object that implements the <code>SQLXML</code> interface. The object 1090 * returned initially contains no data. The <code>createXmlStreamWriter</code> object and 1091 * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code> 1092 * object. 1093 * @return An object that implements the <code>SQLXML</code> interface 1094 * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not 1095 * be constructed, this method is 1096 * called on a closed connection or a database access error occurs. 1097 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1098 * this data type 1099 * @since 1.6 1100 */ createSQLXML()1101 SQLXML createSQLXML() throws SQLException; 1102 1103 /** 1104 * Returns true if the connection has not been closed and is still valid. 1105 * The driver shall submit a query on the connection or use some other 1106 * mechanism that positively verifies the connection is still valid when 1107 * this method is called. 1108 * <p> 1109 * The query submitted by the driver to validate the connection shall be 1110 * executed in the context of the current transaction. 1111 * 1112 * @param timeout - The time in seconds to wait for the database operation 1113 * used to validate the connection to complete. If 1114 * the timeout period expires before the operation 1115 * completes, this method returns false. A value of 1116 * 0 indicates a timeout is not applied to the 1117 * database operation. 1118 * <p> 1119 * @return true if the connection is valid, false otherwise 1120 * @exception SQLException if the value supplied for <code>timeout</code> 1121 * is less then 0 1122 * @since 1.6 1123 * <p> 1124 * @see java.sql.DatabaseMetaData#getClientInfoProperties 1125 */ isValid(int timeout)1126 boolean isValid(int timeout) throws SQLException; 1127 1128 /** 1129 * Sets the value of the client info property specified by name to the 1130 * value specified by value. 1131 * <p> 1132 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code> 1133 * method to determine the client info properties supported by the driver 1134 * and the maximum length that may be specified for each property. 1135 * <p> 1136 * The driver stores the value specified in a suitable location in the 1137 * database. For example in a special register, session parameter, or 1138 * system table column. For efficiency the driver may defer setting the 1139 * value in the database until the next time a statement is executed or 1140 * prepared. Other than storing the client information in the appropriate 1141 * place in the database, these methods shall not alter the behavior of 1142 * the connection in anyway. The values supplied to these methods are 1143 * used for accounting, diagnostics and debugging purposes only. 1144 * <p> 1145 * The driver shall generate a warning if the client info name specified 1146 * is not recognized by the driver. 1147 * <p> 1148 * If the value specified to this method is greater than the maximum 1149 * length for the property the driver may either truncate the value and 1150 * generate a warning or generate a <code>SQLClientInfoException</code>. If the driver 1151 * generates a <code>SQLClientInfoException</code>, the value specified was not set on the 1152 * connection. 1153 * <p> 1154 * The following are standard client info properties. Drivers are not 1155 * required to support these properties however if the driver supports a 1156 * client info property that can be described by one of the standard 1157 * properties, the standard property name should be used. 1158 * <p> 1159 * <ul> 1160 * <li>ApplicationName - The name of the application currently utilizing 1161 * the connection</li> 1162 * <li>ClientUser - The name of the user that the application using 1163 * the connection is performing work for. This may 1164 * not be the same as the user name that was used 1165 * in establishing the connection.</li> 1166 * <li>ClientHostname - The hostname of the computer the application 1167 * using the connection is running on.</li> 1168 * </ul> 1169 * <p> 1170 * @param name The name of the client info property to set 1171 * @param value The value to set the client info property to. If the 1172 * value is null, the current value of the specified 1173 * property is cleared. 1174 * <p> 1175 * @throws SQLClientInfoException if the database server returns an error while 1176 * setting the client info value on the database server or this method 1177 * is called on a closed connection 1178 * <p> 1179 * @since 1.6 1180 */ setClientInfo(String name, String value)1181 void setClientInfo(String name, String value) 1182 throws SQLClientInfoException; 1183 1184 /** 1185 * Sets the value of the connection's client info properties. The 1186 * <code>Properties</code> object contains the names and values of the client info 1187 * properties to be set. The set of client info properties contained in 1188 * the properties list replaces the current set of client info properties 1189 * on the connection. If a property that is currently set on the 1190 * connection is not present in the properties list, that property is 1191 * cleared. Specifying an empty properties list will clear all of the 1192 * properties on the connection. See <code>setClientInfo (String, String)</code> for 1193 * more information. 1194 * <p> 1195 * If an error occurs in setting any of the client info properties, a 1196 * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code> 1197 * contains information indicating which client info properties were not set. 1198 * The state of the client information is unknown because 1199 * some databases do not allow multiple client info properties to be set 1200 * atomically. For those databases, one or more properties may have been 1201 * set before the error occurred. 1202 * <p> 1203 * 1204 * @param properties the list of client info properties to set 1205 * <p> 1206 * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String) 1207 * @since 1.6 1208 * <p> 1209 * @throws SQLClientInfoException if the database server returns an error while 1210 * setting the clientInfo values on the database server or this method 1211 * is called on a closed connection 1212 * <p> 1213 */ setClientInfo(Properties properties)1214 void setClientInfo(Properties properties) 1215 throws SQLClientInfoException; 1216 1217 /** 1218 * Returns the value of the client info property specified by name. This 1219 * method may return null if the specified client info property has not 1220 * been set and does not have a default value. This method will also 1221 * return null if the specified client info property name is not supported 1222 * by the driver. 1223 * <p> 1224 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code> 1225 * method to determine the client info properties supported by the driver. 1226 * <p> 1227 * @param name The name of the client info property to retrieve 1228 * <p> 1229 * @return The value of the client info property specified 1230 * <p> 1231 * @throws SQLException if the database server returns an error when 1232 * fetching the client info value from the database 1233 *or this method is called on a closed connection 1234 * <p> 1235 * @since 1.6 1236 * <p> 1237 * @see java.sql.DatabaseMetaData#getClientInfoProperties 1238 */ getClientInfo(String name)1239 String getClientInfo(String name) 1240 throws SQLException; 1241 1242 /** 1243 * Returns a list containing the name and current value of each client info 1244 * property supported by the driver. The value of a client info property 1245 * may be null if the property has not been set and does not have a 1246 * default value. 1247 * <p> 1248 * @return A <code>Properties</code> object that contains the name and current value of 1249 * each of the client info properties supported by the driver. 1250 * <p> 1251 * @throws SQLException if the database server returns an error when 1252 * fetching the client info values from the database 1253 * or this method is called on a closed connection 1254 * <p> 1255 * @since 1.6 1256 */ getClientInfo()1257 Properties getClientInfo() 1258 throws SQLException; 1259 1260 /** 1261 * Factory method for creating Array objects. 1262 *<p> 1263 * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object 1264 * that maps to a primitive data type, then it is implementation-defined 1265 * whether the <code>Array</code> object is an array of that primitive 1266 * data type or an array of <code>Object</code>. 1267 * <p> 1268 * <b>Note: </b>The JDBC driver is responsible for mapping the elements 1269 * <code>Object</code> array to the default JDBC SQL type defined in 1270 * java.sql.Types for the given class of <code>Object</code>. The default 1271 * mapping is specified in Appendix B of the JDBC specification. If the 1272 * resulting JDBC type is not the appropriate type for the given typeName then 1273 * it is implementation defined whether an <code>SQLException</code> is 1274 * thrown or the driver supports the resulting conversion. 1275 * 1276 * @param typeName the SQL name of the type the elements of the array map to. The typeName is a 1277 * 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 1278 * is the value returned by <code>Array.getBaseTypeName</code> 1279 * @param elements the elements that populate the returned object 1280 * @return an Array object whose elements map to the specified SQL type 1281 * @throws SQLException if a database error occurs, the JDBC type is not 1282 * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection 1283 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type 1284 * @since 1.6 1285 */ createArrayOf(String typeName, Object[] elements)1286 Array createArrayOf(String typeName, Object[] elements) throws 1287 SQLException; 1288 1289 /** 1290 * Factory method for creating Struct objects. 1291 * 1292 * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code> 1293 * object maps to. The typeName is the name of a user-defined type that 1294 * has been defined for this database. It is the value returned by 1295 * <code>Struct.getSQLTypeName</code>. 1296 1297 * @param attributes the attributes that populate the returned object 1298 * @return a Struct object that maps to the given SQL type and is populated with the given attributes 1299 * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection 1300 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type 1301 * @since 1.6 1302 */ createStruct(String typeName, Object[] attributes)1303 Struct createStruct(String typeName, Object[] attributes) 1304 throws SQLException; 1305 1306 } 1307