src/share/classes/java/sql/Connection.java

Print this page




 257      * @exception SQLException if a database access error occurs,
 258      * this method is called while participating in a distributed transaction,
 259      * this method is called on a closed connection or this
 260      *            <code>Connection</code> object is in auto-commit mode
 261      * @see #setAutoCommit
 262      */
 263     void rollback() throws SQLException;
 264 
 265     /**
 266      * Releases this <code>Connection</code> object's database and JDBC resources
 267      * immediately instead of waiting for them to be automatically released.
 268      * <P>
 269      * Calling the method <code>close</code> on a <code>Connection</code>
 270      * object that is already closed is a no-op.
 271      * <P>
 272      * It is <b>strongly recommended</b> that an application explicitly
 273      * commits or rolls back an active transaction prior to calling the
 274      * <code>close</code> method.  If the <code>close</code> method is called
 275      * and there is an active transaction, the results are implementation-defined.
 276      *
 277      * @exception SQLException SQLException if a database access error occurs
 278      */
 279     void close() throws SQLException;
 280 
 281     /**
 282      * Retrieves whether this <code>Connection</code> object has been
 283      * closed.  A connection is closed if the method <code>close</code>
 284      * has been called on it or if certain fatal errors have occurred.
 285      * This method is guaranteed to return <code>true</code> only when
 286      * it is called after the method <code>Connection.close</code> has
 287      * been called.
 288      * <P>
 289      * This method generally cannot be called to determine whether a
 290      * connection to a database is valid or invalid.  A typical client
 291      * can determine that a connection is invalid by catching any
 292      * exceptions that might be thrown when an operation is attempted.
 293      *
 294      * @return <code>true</code> if this <code>Connection</code> object
 295      *         is closed; <code>false</code> if it is still open
 296      * @exception SQLException if a database access error occurs
 297      */


 318     /**
 319      * Puts this connection in read-only mode as a hint to the driver to enable
 320      * database optimizations.
 321      *
 322      * <P><B>Note:</B> This method cannot be called during a transaction.
 323      *
 324      * @param readOnly <code>true</code> enables read-only mode;
 325      *        <code>false</code> disables it
 326      * @exception SQLException if a database access error occurs, this
 327      *  method is called on a closed connection or this
 328      *            method is called during a transaction
 329      */
 330     void setReadOnly(boolean readOnly) throws SQLException;
 331 
 332     /**
 333      * Retrieves whether this <code>Connection</code>
 334      * object is in read-only mode.
 335      *
 336      * @return <code>true</code> if this <code>Connection</code> object
 337      *         is read-only; <code>false</code> otherwise
 338      * @exception SQLException SQLException if a database access error occurs
 339      * or this method is called on a closed connection
 340      */
 341     boolean isReadOnly() throws SQLException;
 342 
 343     /**
 344      * Sets the given catalog name in order to select
 345      * a subspace of this <code>Connection</code> object's database
 346      * in which to work.
 347      * <P>
 348      * If the driver does not support catalogs, it will
 349      * silently ignore this request.
 350      * <p>
 351      * Calling {@code setCatalog} has no effect on previously created or prepared
 352      * {@code Statement} objects. It is implementation defined whether a DBMS
 353      * prepare operation takes place immediately when the {@code Connection}
 354      * method {@code prepareStatement} or {@code prepareCall} is invoked.
 355      * For maximum portability, {@code setCatalog} should be called before a
 356      * {@code Statement} is created or prepared.
 357      *
 358      * @param catalog the name of a catalog (subspace in this


 475      * called on a closed connection; doing so will cause an
 476      * <code>SQLException</code> to be thrown.
 477      *
 478      * <P><B>Note:</B> Subsequent warnings will be chained to this
 479      * SQLWarning.
 480      *
 481      * @return the first <code>SQLWarning</code> object or <code>null</code>
 482      *         if there are none
 483      * @exception SQLException if a database access error occurs or
 484      *            this method is called on a closed connection
 485      * @see SQLWarning
 486      */
 487     SQLWarning getWarnings() throws SQLException;
 488 
 489     /**
 490      * Clears all warnings reported for this <code>Connection</code> object.
 491      * After a call to this method, the method <code>getWarnings</code>
 492      * returns <code>null</code> until a new warning is
 493      * reported for this <code>Connection</code> object.
 494      *
 495      * @exception SQLException SQLException if a database access error occurs
 496      * or this method is called on a closed connection
 497      */
 498     void clearWarnings() throws SQLException;
 499 
 500 
 501     //--------------------------JDBC 2.0-----------------------------
 502 
 503     /**
 504      * Creates a <code>Statement</code> object that will generate
 505      * <code>ResultSet</code> objects with the given type and concurrency.
 506      * This method is the same as the <code>createStatement</code> method
 507      * above, but it allows the default result set
 508      * type and concurrency to be overridden.
 509      * The holdability of the created result sets can be determined by
 510      * calling {@link #getHoldability}.
 511      *
 512      * @param resultSetType a result set type; one of
 513      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
 514      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
 515      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>


 615      *      Map&lt;String,Class&lt;?&gt;&gt; myMap = con.getTypeMap();
 616      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
 617      *      con.setTypeMap(myMap);
 618      * </pre>
 619      * @return the <code>java.util.Map</code> object associated
 620      *         with this <code>Connection</code> object
 621      * @exception SQLException if a database access error occurs
 622      * or this method is called on a closed connection
 623      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 624      * this method
 625      * @since 1.2
 626      * @see #setTypeMap
 627      */
 628     java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
 629 
 630     /**
 631      * Installs the given <code>TypeMap</code> object as the type map for
 632      * this <code>Connection</code> object.  The type map will be used for the
 633      * custom mapping of SQL structured types and distinct types.
 634      * <p>
 635      * You must set the the values for the <code>TypeMap</code> prior to
 636      * callng <code>setMap</code> as a JDBC driver may create an internal copy
 637      * of the <code>TypeMap</code>:
 638      *
 639      * <pre>
 640      *      Map myMap&lt;String,Class&lt;?&gt;&gt; = new HashMap&lt;String,Class&lt;?&gt;&gt;();
 641      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
 642      *      con.setTypeMap(myMap);
 643      * </pre>
 644      * @param map the <code>java.util.Map</code> object to install
 645      *        as the replacement for this <code>Connection</code>
 646      *        object's default type map
 647      * @exception SQLException if a database access error occurs, this
 648      * method is called on a closed connection or
 649      *        the given parameter is not a <code>java.util.Map</code>
 650      *        object
 651      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 652      * this method
 653      * @since 1.2
 654      * @see #getTypeMap
 655      */
 656     void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
 657 
 658     //--------------------------JDBC 3.0-----------------------------
 659 
 660 
 661     /**
 662      * Changes the default holdability of <code>ResultSet</code> objects
 663      * created using this <code>Connection</code> object to the given
 664      * holdability.  The default holdability of <code>ResultSet</code> objects
 665      * can be be determined by invoking
 666      * {@link DatabaseMetaData#getResultSetHoldability}.
 667      *
 668      * @param holdability a <code>ResultSet</code> holdability constant; one of
 669      *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 670      *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
 671      * @throws SQLException if a database access occurs, this method is called
 672      * on a closed connection, or the given parameter
 673      *         is not a <code>ResultSet</code> constant indicating holdability
 674      * @exception SQLFeatureNotSupportedException if the given holdability is not supported
 675      * @see #getHoldability
 676      * @see DatabaseMetaData#getResultSetHoldability
 677      * @see ResultSet
 678      * @since 1.4
 679      */
 680     void setHoldability(int holdability) throws SQLException;
 681 
 682     /**
 683      * Retrieves the current holdability of <code>ResultSet</code> objects
 684      * created using this <code>Connection</code> object.
 685      *




 257      * @exception SQLException if a database access error occurs,
 258      * this method is called while participating in a distributed transaction,
 259      * this method is called on a closed connection or this
 260      *            <code>Connection</code> object is in auto-commit mode
 261      * @see #setAutoCommit
 262      */
 263     void rollback() throws SQLException;
 264 
 265     /**
 266      * Releases this <code>Connection</code> object's database and JDBC resources
 267      * immediately instead of waiting for them to be automatically released.
 268      * <P>
 269      * Calling the method <code>close</code> on a <code>Connection</code>
 270      * object that is already closed is a no-op.
 271      * <P>
 272      * It is <b>strongly recommended</b> that an application explicitly
 273      * commits or rolls back an active transaction prior to calling the
 274      * <code>close</code> method.  If the <code>close</code> method is called
 275      * and there is an active transaction, the results are implementation-defined.
 276      *
 277      * @exception SQLException if a database access error occurs
 278      */
 279     void close() throws SQLException;
 280 
 281     /**
 282      * Retrieves whether this <code>Connection</code> object has been
 283      * closed.  A connection is closed if the method <code>close</code>
 284      * has been called on it or if certain fatal errors have occurred.
 285      * This method is guaranteed to return <code>true</code> only when
 286      * it is called after the method <code>Connection.close</code> has
 287      * been called.
 288      * <P>
 289      * This method generally cannot be called to determine whether a
 290      * connection to a database is valid or invalid.  A typical client
 291      * can determine that a connection is invalid by catching any
 292      * exceptions that might be thrown when an operation is attempted.
 293      *
 294      * @return <code>true</code> if this <code>Connection</code> object
 295      *         is closed; <code>false</code> if it is still open
 296      * @exception SQLException if a database access error occurs
 297      */


 318     /**
 319      * Puts this connection in read-only mode as a hint to the driver to enable
 320      * database optimizations.
 321      *
 322      * <P><B>Note:</B> This method cannot be called during a transaction.
 323      *
 324      * @param readOnly <code>true</code> enables read-only mode;
 325      *        <code>false</code> disables it
 326      * @exception SQLException if a database access error occurs, this
 327      *  method is called on a closed connection or this
 328      *            method is called during a transaction
 329      */
 330     void setReadOnly(boolean readOnly) throws SQLException;
 331 
 332     /**
 333      * Retrieves whether this <code>Connection</code>
 334      * object is in read-only mode.
 335      *
 336      * @return <code>true</code> if this <code>Connection</code> object
 337      *         is read-only; <code>false</code> otherwise
 338      * @exception SQLException if a database access error occurs
 339      * or this method is called on a closed connection
 340      */
 341     boolean isReadOnly() throws SQLException;
 342 
 343     /**
 344      * Sets the given catalog name in order to select
 345      * a subspace of this <code>Connection</code> object's database
 346      * in which to work.
 347      * <P>
 348      * If the driver does not support catalogs, it will
 349      * silently ignore this request.
 350      * <p>
 351      * Calling {@code setCatalog} has no effect on previously created or prepared
 352      * {@code Statement} objects. It is implementation defined whether a DBMS
 353      * prepare operation takes place immediately when the {@code Connection}
 354      * method {@code prepareStatement} or {@code prepareCall} is invoked.
 355      * For maximum portability, {@code setCatalog} should be called before a
 356      * {@code Statement} is created or prepared.
 357      *
 358      * @param catalog the name of a catalog (subspace in this


 475      * called on a closed connection; doing so will cause an
 476      * <code>SQLException</code> to be thrown.
 477      *
 478      * <P><B>Note:</B> Subsequent warnings will be chained to this
 479      * SQLWarning.
 480      *
 481      * @return the first <code>SQLWarning</code> object or <code>null</code>
 482      *         if there are none
 483      * @exception SQLException if a database access error occurs or
 484      *            this method is called on a closed connection
 485      * @see SQLWarning
 486      */
 487     SQLWarning getWarnings() throws SQLException;
 488 
 489     /**
 490      * Clears all warnings reported for this <code>Connection</code> object.
 491      * After a call to this method, the method <code>getWarnings</code>
 492      * returns <code>null</code> until a new warning is
 493      * reported for this <code>Connection</code> object.
 494      *
 495      * @exception SQLException if a database access error occurs
 496      * or this method is called on a closed connection
 497      */
 498     void clearWarnings() throws SQLException;
 499 
 500 
 501     //--------------------------JDBC 2.0-----------------------------
 502 
 503     /**
 504      * Creates a <code>Statement</code> object that will generate
 505      * <code>ResultSet</code> objects with the given type and concurrency.
 506      * This method is the same as the <code>createStatement</code> method
 507      * above, but it allows the default result set
 508      * type and concurrency to be overridden.
 509      * The holdability of the created result sets can be determined by
 510      * calling {@link #getHoldability}.
 511      *
 512      * @param resultSetType a result set type; one of
 513      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
 514      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
 515      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>


 615      *      Map&lt;String,Class&lt;?&gt;&gt; myMap = con.getTypeMap();
 616      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
 617      *      con.setTypeMap(myMap);
 618      * </pre>
 619      * @return the <code>java.util.Map</code> object associated
 620      *         with this <code>Connection</code> object
 621      * @exception SQLException if a database access error occurs
 622      * or this method is called on a closed connection
 623      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 624      * this method
 625      * @since 1.2
 626      * @see #setTypeMap
 627      */
 628     java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
 629 
 630     /**
 631      * Installs the given <code>TypeMap</code> object as the type map for
 632      * this <code>Connection</code> object.  The type map will be used for the
 633      * custom mapping of SQL structured types and distinct types.
 634      * <p>
 635      * You must set the values for the <code>TypeMap</code> prior to
 636      * callng <code>setMap</code> as a JDBC driver may create an internal copy
 637      * of the <code>TypeMap</code>:
 638      *
 639      * <pre>
 640      *      Map myMap&lt;String,Class&lt;?&gt;&gt; = new HashMap&lt;String,Class&lt;?&gt;&gt;();
 641      *      myMap.put("mySchemaName.ATHLETES", Athletes.class);
 642      *      con.setTypeMap(myMap);
 643      * </pre>
 644      * @param map the <code>java.util.Map</code> object to install
 645      *        as the replacement for this <code>Connection</code>
 646      *        object's default type map
 647      * @exception SQLException if a database access error occurs, this
 648      * method is called on a closed connection or
 649      *        the given parameter is not a <code>java.util.Map</code>
 650      *        object
 651      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 652      * this method
 653      * @since 1.2
 654      * @see #getTypeMap
 655      */
 656     void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
 657 
 658     //--------------------------JDBC 3.0-----------------------------
 659 
 660 
 661     /**
 662      * Changes the default holdability of <code>ResultSet</code> objects
 663      * created using this <code>Connection</code> object to the given
 664      * holdability.  The default holdability of <code>ResultSet</code> objects
 665      * can be determined by invoking
 666      * {@link DatabaseMetaData#getResultSetHoldability}.
 667      *
 668      * @param holdability a <code>ResultSet</code> holdability constant; one of
 669      *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
 670      *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
 671      * @throws SQLException if a database access occurs, this method is called
 672      * on a closed connection, or the given parameter
 673      *         is not a <code>ResultSet</code> constant indicating holdability
 674      * @exception SQLFeatureNotSupportedException if the given holdability is not supported
 675      * @see #getHoldability
 676      * @see DatabaseMetaData#getResultSetHoldability
 677      * @see ResultSet
 678      * @since 1.4
 679      */
 680     void setHoldability(int holdability) throws SQLException;
 681 
 682     /**
 683      * Retrieves the current holdability of <code>ResultSet</code> objects
 684      * created using this <code>Connection</code> object.
 685      *