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