Save This Page
Home » openjdk-7 » java » sql » [javadoc | source]
    1   /*
    2    * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.sql;
   27   
   28   import java.util.Properties;
   29   import java.util.concurrent.Executor;
   30   
   31   /**
   32    * <P>A connection (session) with a specific
   33    * database. SQL statements are executed and results are returned
   34    * within the context of a connection.
   35    * <P>
   36    * A <code>Connection</code> object's database is able to provide information
   37    * describing its tables, its supported SQL grammar, its stored
   38    * procedures, the capabilities of this connection, and so on. This
   39    * information is obtained with the <code>getMetaData</code> method.
   40    *
   41    * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications
   42    *  should use the appropriate <code>Connection</code> method such as
   43    *  <code>setAutoCommit</code> or <code>setTransactionIsolation</code>.
   44    *  Applications should not invoke SQL commands directly to change the connection's
   45    *   configuration when there is a JDBC method available.  By default a <code>Connection</code> object is in
   46    * auto-commit mode, which means that it automatically commits changes
   47    * after executing each statement. If auto-commit mode has been
   48    * disabled, the method <code>commit</code> must be called explicitly in
   49    * order to commit changes; otherwise, database changes will not be saved.
   50    * <P>
   51    * A new <code>Connection</code> object created using the JDBC 2.1 core API
   52    * has an initially empty type map associated with it. A user may enter a
   53    * custom mapping for a UDT in this type map.
   54    * When a UDT is retrieved from a data source with the
   55    * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
   56    * will check the connection's type map to see if there is an entry for that
   57    * UDT.  If so, the <code>getObject</code> method will map the UDT to the
   58    * class indicated.  If there is no entry, the UDT will be mapped using the
   59    * standard mapping.
   60    * <p>
   61    * A user may create a new type map, which is a <code>java.util.Map</code>
   62    * object, make an entry in it, and pass it to the <code>java.sql</code>
   63    * methods that can perform custom mapping.  In this case, the method
   64    * will use the given type map instead of the one associated with
   65    * the connection.
   66    * <p>
   67    * For example, the following code fragment specifies that the SQL
   68    * type <code>ATHLETES</code> will be mapped to the class
   69    * <code>Athletes</code> in the Java programming language.
   70    * The code fragment retrieves the type map for the <code>Connection
   71    * </code> object <code>con</code>, inserts the entry into it, and then sets
   72    * the type map with the new entry as the connection's type map.
   73    * <pre>
   74    *      java.util.Map map = con.getTypeMap();
   75    *      map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
   76    *      con.setTypeMap(map);
   77    * </pre>
   78    *
   79    * @see DriverManager#getConnection
   80    * @see Statement
   81    * @see ResultSet
   82    * @see DatabaseMetaData
   83    */
   84   public interface Connection  extends Wrapper, AutoCloseable {
   85   
   86       /**
   87        * Creates a <code>Statement</code> object for sending
   88        * SQL statements to the database.
   89        * SQL statements without parameters are normally
   90        * executed using <code>Statement</code> objects. If the same SQL statement
   91        * is executed many times, it may be more efficient to use a
   92        * <code>PreparedStatement</code> object.
   93        * <P>
   94        * Result sets created using the returned <code>Statement</code>
   95        * object will by default be type <code>TYPE_FORWARD_ONLY</code>
   96        * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
   97        * The holdability of the created result sets can be determined by
   98        * calling {@link #getHoldability}.
   99        *
  100        * @return a new default <code>Statement</code> object
  101        * @exception SQLException if a database access error occurs
  102        * or this method is called on a closed connection
  103        */
  104       Statement createStatement() throws SQLException;
  105   
  106       /**
  107        * Creates a <code>PreparedStatement</code> object for sending
  108        * parameterized SQL statements to the database.
  109        * <P>
  110        * A SQL statement with or without IN parameters can be
  111        * pre-compiled and stored in a <code>PreparedStatement</code> object. This
  112        * object can then be used to efficiently execute this statement
  113        * multiple times.
  114        *
  115        * <P><B>Note:</B> This method is optimized for handling
  116        * parametric SQL statements that benefit from precompilation. If
  117        * the driver supports precompilation,
  118        * the method <code>prepareStatement</code> will send
  119        * the statement to the database for precompilation. Some drivers
  120        * may not support precompilation. In this case, the statement may
  121        * not be sent to the database until the <code>PreparedStatement</code>
  122        * object is executed.  This has no direct effect on users; however, it does
  123        * affect which methods throw certain <code>SQLException</code> objects.
  124        * <P>
  125        * Result sets created using the returned <code>PreparedStatement</code>
  126        * object will by default be type <code>TYPE_FORWARD_ONLY</code>
  127        * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
  128        * The holdability of the created result sets can be determined by
  129        * calling {@link #getHoldability}.
  130        *
  131        * @param sql an SQL statement that may contain one or more '?' IN
  132        * parameter placeholders
  133        * @return a new default <code>PreparedStatement</code> object containing the
  134        * pre-compiled SQL statement
  135        * @exception SQLException if a database access error occurs
  136        * or this method is called on a closed connection
  137        */
  138       PreparedStatement prepareStatement(String sql)
  139           throws SQLException;
  140   
  141       /**
  142        * Creates a <code>CallableStatement</code> object for calling
  143        * database stored procedures.
  144        * The <code>CallableStatement</code> object provides
  145        * methods for setting up its IN and OUT parameters, and
  146        * methods for executing the call to a stored procedure.
  147        *
  148        * <P><B>Note:</B> This method is optimized for handling stored
  149        * procedure call statements. Some drivers may send the call
  150        * statement to the database when the method <code>prepareCall</code>
  151        * is done; others
  152        * may wait until the <code>CallableStatement</code> object
  153        * is executed. This has no
  154        * direct effect on users; however, it does affect which method
  155        * throws certain SQLExceptions.
  156        * <P>
  157        * Result sets created using the returned <code>CallableStatement</code>
  158        * object will by default be type <code>TYPE_FORWARD_ONLY</code>
  159        * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
  160        * The holdability of the created result sets can be determined by
  161        * calling {@link #getHoldability}.
  162        *
  163        * @param sql an SQL statement that may contain one or more '?'
  164        * parameter placeholders. Typically this statement is specified using JDBC
  165        * call escape syntax.
  166        * @return a new default <code>CallableStatement</code> object containing the
  167        * pre-compiled SQL statement
  168        * @exception SQLException if a database access error occurs
  169        * or this method is called on a closed connection
  170        */
  171       CallableStatement prepareCall(String sql) throws SQLException;
  172   
  173       /**
  174        * Converts the given SQL statement into the system's native SQL grammar.
  175        * A driver may convert the JDBC SQL grammar into its system's
  176        * native SQL grammar prior to sending it. This method returns the
  177        * native form of the statement that the driver would have sent.
  178        *
  179        * @param sql an SQL statement that may contain one or more '?'
  180        * parameter placeholders
  181        * @return the native form of this statement
  182        * @exception SQLException if a database access error occurs
  183        * or this method is called on a closed connection
  184        */
  185       String nativeSQL(String sql) throws SQLException;
  186   
  187       /**
  188        * Sets this connection's auto-commit mode to the given state.
  189        * If a connection is in auto-commit mode, then all its SQL
  190        * statements will be executed and committed as individual
  191        * transactions.  Otherwise, its SQL statements are grouped into
  192        * transactions that are terminated by a call to either
  193        * the method <code>commit</code> or the method <code>rollback</code>.
  194        * By default, new connections are in auto-commit
  195        * mode.
  196        * <P>
  197        * The commit occurs when the statement completes. The time when the statement
  198        * completes depends on the type of SQL Statement:
  199        * <ul>
  200        * <li>For DML statements, such as Insert, Update or Delete, and DDL statements,
  201        * the statement is complete as soon as it has finished executing.
  202        * <li>For Select statements, the statement is complete when the associated result
  203        * set is closed.
  204        * <li>For <code>CallableStatement</code> objects or for statements that return
  205        * multiple results, the statement is complete
  206        * when all of the associated result sets have been closed, and all update
  207        * counts and output parameters have been retrieved.
  208        *</ul>
  209        * <P>
  210        * <B>NOTE:</B>  If this method is called during a transaction and the
  211        * auto-commit mode is changed, the transaction is committed.  If
  212        * <code>setAutoCommit</code> is called and the auto-commit mode is
  213        * not changed, the call is a no-op.
  214        *
  215        * @param autoCommit <code>true</code> to enable auto-commit mode;
  216        *         <code>false</code> to disable it
  217        * @exception SQLException if a database access error occurs,
  218        *  setAutoCommit(true) is called while participating in a distributed transaction,
  219        * or this method is called on a closed connection
  220        * @see #getAutoCommit
  221        */
  222       void setAutoCommit(boolean autoCommit) throws SQLException;
  223   
  224       /**
  225        * Retrieves the current auto-commit mode for this <code>Connection</code>
  226        * object.
  227        *
  228        * @return the current state of this <code>Connection</code> object's
  229        *         auto-commit mode
  230        * @exception SQLException if a database access error occurs
  231        * or this method is called on a closed connection
  232        * @see #setAutoCommit
  233        */
  234       boolean getAutoCommit() throws SQLException;
  235   
  236       /**
  237        * Makes all changes made since the previous
  238        * commit/rollback permanent and releases any database locks
  239        * currently held by this <code>Connection</code> object.
  240        * This method should be
  241        * used only when auto-commit mode has been disabled.
  242        *
  243        * @exception SQLException if a database access error occurs,
  244        * this method is called while participating in a distributed transaction,
  245        * if this method is called on a closed conection or this
  246        *            <code>Connection</code> object is in auto-commit mode
  247        * @see #setAutoCommit
  248        */
  249       void commit() throws SQLException;
  250   
  251       /**
  252        * Undoes all changes made in the current transaction
  253        * and releases any database locks currently held
  254        * by this <code>Connection</code> object. This method should be
  255        * used only when auto-commit mode has been disabled.
  256        *
  257        * @exception SQLException if a database access error occurs,
  258        * this method is called while participating in a distributed transaction,
  259        * this method is called on a closed connection or this
  260        *            <code>Connection</code> object is in auto-commit mode
  261        * @see #setAutoCommit
  262        */
  263       void rollback() throws SQLException;
  264   
  265       /**
  266        * Releases this <code>Connection</code> object's database and JDBC resources
  267        * immediately instead of waiting for them to be automatically released.
  268        * <P>
  269        * Calling the method <code>close</code> on a <code>Connection</code>
  270        * object that is already closed is a no-op.
  271        * <P>
  272        * It is <b>strongly recommended</b> that an application explicitly
  273        * commits or rolls back an active transaction prior to calling the
  274        * <code>close</code> method.  If the <code>close</code> method is called
  275        * and there is an active transaction, the results are implementation-defined.
  276        * <P>
  277        *
  278        * @exception SQLException 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 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 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        * <p>
  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 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        * <p>
  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 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            * <p>
 1118            * @return true if the connection is valid, false otherwise
 1119            * @exception SQLException if the value supplied for <code>timeout</code>
 1120            * is less then 0
 1121            * @since 1.6
 1122            * <p>
 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            * <p>
 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            * <p>
 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            * <p>
 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            * <p>
 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        * <p>
 1202        *
 1203        * @param properties                the list of client info properties to set
 1204        * <p>
 1205        * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
 1206        * @since 1.6
 1207        * <p>
 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        * <p>
 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            * <p>
 1226            * @param name          The name of the client info property to retrieve
 1227            * <p>
 1228            * @return                      The value of the client info property specified
 1229            * <p>
 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            * <p>
 1234            * @since 1.6
 1235            * <p>
 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            * <p>
 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            * <p>
 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            * <p>
 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   }

Save This Page
Home » openjdk-7 » java » sql » [javadoc | source]