jdk-sandbox: comparison jdk/src/share/classes/java/sql/Statement.java

equal deleted inserted replaced

-:874f52171965
+:a4ae668f6125
 /*
-* Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
+* Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * <code>ResultSet</code> object if an open one exists.
 *
 * @see Connection#createStatement
 * @see ResultSet
 */
-public interface Statement extends Wrapper {
+public interface Statement extends Wrapper, AutoCloseable {
 /**
 * Executes the given SQL statement, which returns a single
 * <code>ResultSet</code> object.
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql an SQL statement to be sent to the database, typically a
 *        static SQL <code>SELECT</code> statement
 * @return a <code>ResultSet</code> object that contains the data produced
 *         by the given query; never <code>null</code>
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the given
+* this method is called on a closed <code>Statement</code>, the given
 *            SQL statement produces anything other than a single
-*            <code>ResultSet</code> object
+*            <code>ResultSet</code> object, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 */
 ResultSet executeQuery(String sql) throws SQLException;
 /**
 * Executes the given SQL statement, which may be an <code>INSERT</code>,
 * <code>UPDATE</code>, or <code>DELETE</code> statement or an
 * SQL statement that returns nothing, such as an SQL DDL statement.
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
 * <code>DELETE</code>; or an SQL statement that returns nothing,
 * such as a DDL statement.
 *
 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
 *         or (2) 0 for SQL statements that return nothing
 *
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the given
+* this method is called on a closed <code>Statement</code>, the given
-*            SQL statement produces a <code>ResultSet</code> object
+* SQL statement produces a <code>ResultSet</code> object, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 */
 int executeUpdate(String sql) throws SQLException;
 /**
 * Releases this <code>Statement</code> object's database
 int getQueryTimeout() throws SQLException;
 /**
 * Sets the number of seconds the driver will wait for a
 * <code>Statement</code> object to execute to the given number of seconds.
-* If the limit is exceeded, an <code>SQLException</code> is thrown. A JDBC
+*By default there is no limit on the amount of time allowed for a running
-* driver must apply this limit to the <code>execute</code>,
+* statement to complete. If the limit is exceeded, an
-* <code>executeQuery</code> and <code>executeUpdate</code> methods. JDBC driver
+* <code>SQLTimeoutException</code> is thrown.
-* implementations may also apply this limit to <code>ResultSet</code> methods
+* A JDBC driver must apply this limit to the <code>execute</code>,
+* <code>executeQuery</code> and <code>executeUpdate</code> methods.
+* <p>
+* <strong>Note:</strong> JDBC driver implementations may also apply this
+* limit to {@code ResultSet} methods
 * (consult your driver vendor documentation for details).
+* <p>
+* <strong>Note:</strong> In the case of {@code Statement} batching, it is
+* implementation defined as to whether the time-out is applied to
+* individual SQL commands added via the {@code addBatch} method or to
+* the entire batch of SQL commands invoked by the {@code executeBatch}
+* method (consult your driver vendor documentation for details).
 *
 * @param seconds the new query timeout limit in seconds; zero means
 *        there is no limit
 * @exception SQLException if a database access error occurs,
 * this method is called on a closed <code>Statement</code>
 * The <code>execute</code> method executes an SQL statement and indicates the
 * form of the first result.  You must then use the methods
 * <code>getResultSet</code> or <code>getUpdateCount</code>
 * to retrieve the result, and <code>getMoreResults</code> to
 * move to any subsequent result(s).
-*
+* <p>
+*<strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql any SQL statement
 * @return <code>true</code> if the first result is a <code>ResultSet</code>
 *         object; <code>false</code> if it is an update count or there are
 *         no results
-* @exception SQLException if a database access error occurs or
+* @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code>
+* this method is called on a closed <code>Statement</code>,
+* the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @see #getResultSet
 * @see #getUpdateCount
 * @see #getMoreResults
 */
 boolean execute(String sql) throws SQLException;
 /**
 * Adds the given SQL command to the current list of commmands for this
 * <code>Statement</code> object. The commands in this list can be
 * executed as a batch by calling the method <code>executeBatch</code>.
 * <P>
-*
+*<strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql typically this is a SQL <code>INSERT</code> or
 * <code>UPDATE</code> statement
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the
+* this method is called on a closed <code>Statement</code>, the
-* driver does not support batch updates
+* driver does not support batch updates, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @see #executeBatch
 * @see DatabaseMetaData#supportsBatchUpdates
 * @since 1.2
 */
 void addBatch( String sql ) throws SQLException;
 * @exception SQLException if a database access error occurs,
 * this method is called on a closed <code>Statement</code> or the
 * driver does not support batch statements. Throws {@link BatchUpdateException}
 * (a subclass of <code>SQLException</code>) if one of the commands sent to the
 * database fails to execute properly or attempts to return a result set.
-*
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 *
 * @see #addBatch
 * @see DatabaseMetaData#supportsBatchUpdates
 * @since 1.3
 */
 * auto-generated keys produced by this <code>Statement</code> object
 * should be made available for retrieval.  The driver will ignore the
 * flag if the SQL statement
 * is not an <code>INSERT</code> statement, or an SQL statement able to return
 * auto-generated keys (the list of such statements is vendor-specific).
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
 * <code>DELETE</code>; or an SQL statement that returns nothing,
 * such as a DDL statement.
 *
 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
 *         or (2) 0 for SQL statements that return nothing
 *
 * @exception SQLException if a database access error occurs,
 *  this method is called on a closed <code>Statement</code>, the given
-*            SQL statement returns a <code>ResultSet</code> object, or
+*            SQL statement returns a <code>ResultSet</code> object,
-*            the given constant is not one of those allowed
+*            the given constant is not one of those allowed, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 * this method with a constant of Statement.RETURN_GENERATED_KEYS
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @since 1.4
 */
 int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException;
 /**
 * for retrieval.   This array contains the indexes of the columns in the
 * target table that contain the auto-generated keys that should be made
 * available. The driver will ignore the array if the SQL statement
 * is not an <code>INSERT</code> statement, or an SQL statement able to return
 * auto-generated keys (the list of such statements is vendor-specific).
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
 * <code>DELETE</code>; or an SQL statement that returns nothing,
 * such as a DDL statement.
 *
 * @param columnIndexes an array of column indexes indicating the columns
 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
 *         or (2) 0 for SQL statements that return nothing
 *
 * @exception SQLException if a database access error occurs,
 * this method is called on a closed <code>Statement</code>, the SQL
-*            statement returns a <code>ResultSet</code> object, or the
+* statement returns a <code>ResultSet</code> object,the second argument
-*            second argument supplied to this method is not an <code>int</code> array
+* supplied to this method is not an
-*            whose elements are valid column indexes
+* <code>int</code> array whose elements are valid column indexes, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @since 1.4
 */
 int executeUpdate(String sql, int columnIndexes[]) throws SQLException;
 /**
 * for retrieval.   This array contains the names of the columns in the
 * target table that contain the auto-generated keys that should be made
 * available. The driver will ignore the array if the SQL statement
 * is not an <code>INSERT</code> statement, or an SQL statement able to return
 * auto-generated keys (the list of such statements is vendor-specific).
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
 * <code>DELETE</code>; or an SQL statement that returns nothing,
 * such as a DDL statement.
 * @param columnNames an array of the names of the columns that should be
 *        returned from the inserted row
 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
 *         or <code>DELETE</code> statements, or 0 for SQL statements
 *         that return nothing
 * @exception SQLException if a database access error occurs,
 *  this method is called on a closed <code>Statement</code>, the SQL
-*            statement returns a <code>ResultSet</code> object, or the
+*            statement returns a <code>ResultSet</code> object, the
 *            second argument supplied to this method is not a <code>String</code> array
-*            whose elements are valid column names
+*            whose elements are valid column names, the method is called on a
-*
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @since 1.4
 */
 int executeUpdate(String sql, String columnNames[]) throws SQLException;
 /**
 * The <code>execute</code> method executes an SQL statement and indicates the
 * form of the first result.  You must then use the methods
 * <code>getResultSet</code> or <code>getUpdateCount</code>
 * to retrieve the result, and <code>getMoreResults</code> to
 * move to any subsequent result(s).
-*
+*<p>
+*<strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql any SQL statement
 * @param autoGeneratedKeys a constant indicating whether auto-generated
 *        keys should be made available for retrieval using the method
 *        <code>getGeneratedKeys</code>; one of the following constants:
 *        <code>Statement.RETURN_GENERATED_KEYS</code> or
 *        <code>Statement.NO_GENERATED_KEYS</code>
 * @return <code>true</code> if the first result is a <code>ResultSet</code>
 *         object; <code>false</code> if it is an update count or there are
 *         no results
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the second
+* this method is called on a closed <code>Statement</code>, the second
 *         parameter supplied to this method is not
 *         <code>Statement.RETURN_GENERATED_KEYS</code> or
-*         <code>Statement.NO_GENERATED_KEYS</code>.
+*         <code>Statement.NO_GENERATED_KEYS</code>,
+* the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 * this method with a constant of Statement.RETURN_GENERATED_KEYS
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @see #getResultSet
 * @see #getUpdateCount
 * @see #getMoreResults
 * @see #getGeneratedKeys
 *
 * The <code>execute</code> method executes an SQL statement and indicates the
 * form of the first result.  You must then use the methods
 * <code>getResultSet</code> or <code>getUpdateCount</code>
 * to retrieve the result, and <code>getMoreResults</code> to
 * move to any subsequent result(s).
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql any SQL statement
 * @param columnIndexes an array of the indexes of the columns in the
 *        inserted row that should be  made available for retrieval by a
 *        call to the method <code>getGeneratedKeys</code>
 * @return <code>true</code> if the first result is a <code>ResultSet</code>
 *         object; <code>false</code> if it is an update count or there
 *         are no results
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the
+* this method is called on a closed <code>Statement</code>, the
 *            elements in the <code>int</code> array passed to this method
-*            are not valid column indexes
+*            are not valid column indexes, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @see #getResultSet
 * @see #getUpdateCount
 * @see #getMoreResults
 *
 * @since 1.4
 * The <code>execute</code> method executes an SQL statement and indicates the
 * form of the first result.  You must then use the methods
 * <code>getResultSet</code> or <code>getUpdateCount</code>
 * to retrieve the result, and <code>getMoreResults</code> to
 * move to any subsequent result(s).
-*
+*<p>
+* <strong>Note:</strong>This method cannot be called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>.
 * @param sql any SQL statement
 * @param columnNames an array of the names of the columns in the inserted
 *        row that should be made available for retrieval by a call to the
 *        method <code>getGeneratedKeys</code>
 * @return <code>true</code> if the next result is a <code>ResultSet</code>
 *         object; <code>false</code> if it is an update count or there
 *         are no more results
 * @exception SQLException if a database access error occurs,
-* this method is called on a closed <code>Statement</code> or the
+* this method is called on a closed <code>Statement</code>,the
 *          elements of the <code>String</code> array passed to this
-*          method are not valid column names
+*          method are not valid column names, the method is called on a
+* <code>PreparedStatement</code> or <code>CallableStatement</code>
 * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
+* @throws SQLTimeoutException when the driver has determined that the
+* timeout value that was specified by the {@code setQueryTimeout}
+* method has been exceeded and has at least attempted to cancel
+* the currently running {@code Statement}
 * @see #getResultSet
 * @see #getUpdateCount
 * @see #getMoreResults
 * @see #getGeneratedKeys
 *
 * @see java.sql.Statement#setPoolable(boolean) setPoolable(boolean)
 */
 boolean isPoolable()
 throws SQLException;
+//--------------------------JDBC 4.1 -----------------------------
+/**
+* Specifies that this {@code Statement} will be closed when all its
+* dependent result sets are closed. If execution of the {@code Statement}
+* does not produce any result sets, this method has no effect.
+* <p>
+* <strong>Note:</strong> Multiple calls to {@code closeOnCompletion} do
+* not toggle the effect on this {@code Statement}. However, a call to
+* {@code closeOnCompletion} does effect both the subsequent execution of
+* statements, and statements that currently have open, dependent,
+* result sets.
+*
+* @throws SQLException if this method is called on a closed
+* {@code Statement}
+* @since 1.7
+*/
+public void closeOnCompletion() throws SQLException;
+/**
+* Returns a value indicating whether this {@code Statement} will be
+* closed when all dependent objects such as resultsets are closed.
+* @return {@code true} if the {@code Statement} will be closed when all
+* of its dependent objects are closed; {@code false} otherwise
+* @throws SQLException if this method is called on a closed
+* {@code Statement}
+* @since 1.7
+*/
+public boolean isCloseOnCompletion() throws SQLException;
 }

changeset 6540	a4ae668f6125
parent 5506	202f599c92aa
child 6684	2708e0ba15a8