--- a/jdk/src/share/classes/java/sql/Statement.java Sat Jan 19 10:11:19 2013 -0500
+++ b/jdk/src/share/classes/java/sql/Statement.java Sat Jan 19 10:53:14 2013 -0500
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, 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
@@ -183,7 +183,15 @@
* Sets escape processing on or off.
* If escape scanning is on (the default), the driver will do
* escape substitution before sending the SQL statement to the database.
- *
+ *<p>
+ * The {@code Connection} and {@code DataSource} property
+ * {@code escapeProcessing} may be used to change the default escape processing
+ * behavior. A value of true (the default) enables escape Processing for
+ * all {@code Statement} objects. A value of false disables escape processing
+ * for all {@code Statement} objects. The {@code setEscapeProcessing}
+ * method may be used to specify the escape processing behavior for an
+ * individual {@code Statement} object.
+ * <p>
* Note: Since prepared statements have usually been parsed prior
* to making this call, disabling escape processing for
* <code>PreparedStatements</code> objects will have no effect.
@@ -1060,4 +1068,304 @@
*/
public boolean isCloseOnCompletion() throws SQLException;
+
+ //--------------------------JDBC 4.2 -----------------------------
+
+ /**
+ * Retrieves the current result as an update count; if the result
+ * is a <code>ResultSet</code> object or there are no more results, -1
+ * is returned. This method should be called only once per result.
+ * <p>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ *<p>
+ * The default implementation will throw {@code UnsupportedOperationException}
+ *
+ * @return the current result as an update count; -1 if the current result
+ * is a <code>ResultSet</code> object or there are no more results
+ * @exception SQLException if a database access error occurs or
+ * this method is called on a closed <code>Statement</code>
+ * @see #execute
+ * @since 1.8
+ */
+ default long getLargeUpdateCount() throws SQLException {
+ throw new UnsupportedOperationException("getLargeUpdateCount not implemented");
+ }
+
+ /**
+ * Sets the limit for the maximum number of rows that any
+ * <code>ResultSet</code> object generated by this <code>Statement</code>
+ * object can contain to the given number.
+ * If the limit is exceeded, the excess
+ * rows are silently dropped.
+ * <p>
+ * This method should be used when the row limit may exceed
+ * {@link Integer.MAX_VALUE}.
+ *<p>
+ * The default implementation will throw {@code UnsupportedOperationException}
+ *
+ * @param max the new max rows limit; zero means there is no limit
+ * @exception SQLException if a database access error occurs,
+ * this method is called on a closed <code>Statement</code>
+ * or the condition max >= 0 is not satisfied
+ * @see #getMaxRows
+ * @since 1.8
+ */
+ default void setLargeMaxRows(long max) throws SQLException {
+ throw new UnsupportedOperationException("setLargeMaxRows not implemented");
+ }
+
+ /**
+ * Retrieves the maximum number of rows that a
+ * <code>ResultSet</code> object produced by this
+ * <code>Statement</code> object can contain. If this limit is exceeded,
+ * the excess rows are silently dropped.
+ * <p>
+ * This method should be used when the returned row limit may exceed
+ * {@link Integer.MAX_VALUE}.
+ *<p>
+ * The default implementation will return {@code 0}
+ *
+ * @return the current maximum number of rows for a <code>ResultSet</code>
+ * object produced by this <code>Statement</code> object;
+ * zero means there is no limit
+ * @exception SQLException if a database access error occurs or
+ * this method is called on a closed <code>Statement</code>
+ * @see #setMaxRows
+ * @since 1.8
+ */
+ default long getLargeMaxRows() throws SQLException {
+ return 0;
+ }
+
+ /**
+ * Submits a batch of commands to the database for execution and
+ * if all commands execute successfully, returns an array of update counts.
+ * The <code>long</code> elements of the array that is returned are ordered
+ * to correspond to the commands in the batch, which are ordered
+ * according to the order in which they were added to the batch.
+ * The elements in the array returned by the method {@code executeLargeBatch}
+ * may be one of the following:
+ * <OL>
+ * <LI>A number greater than or equal to zero -- indicates that the
+ * command was processed successfully and is an update count giving the
+ * number of rows in the database that were affected by the command's
+ * execution
+ * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
+ * processed successfully but that the number of rows affected is
+ * unknown
+ * <P>
+ * If one of the commands in a batch update fails to execute properly,
+ * this method throws a <code>BatchUpdateException</code>, and a JDBC
+ * driver may or may not continue to process the remaining commands in
+ * the batch. However, the driver's behavior must be consistent with a
+ * particular DBMS, either always continuing to process commands or never
+ * continuing to process commands. If the driver continues processing
+ * after a failure, the array returned by the method
+ * <code>BatchUpdateException.getLargeUpdateCounts</code>
+ * will contain as many elements as there are commands in the batch, and
+ * at least one of the elements will be the following:
+ * <P>
+ * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
+ * to execute successfully and occurs only if a driver continues to
+ * process commands after a command fails
+ * </OL>
+ * <p>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ *<p>
+ * The default implementation will throw {@code UnsupportedOperationException}
+ *
+ * @return an array of update counts containing one element for each
+ * command in the batch. The elements of the array are ordered according
+ * to the order in which commands were added to the batch.
+ * @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.8
+ */
+ default long[] executeLargeBatch() throws SQLException {
+ throw new UnsupportedOperationException("executeLargeBatch not implemented");
+ }
+
+ /**
+ * 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>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ * <p>
+ * <strong>Note:</strong>This method cannot be called on a
+ * <code>PreparedStatement</code> or <code>CallableStatement</code>.
+ *<p>
+ * The default implementation will throw {@code UnsupportedOperationException}
+ *
+ * @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>, the given
+ * 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}
+ * @since 1.8
+ */
+ default long executeLargeUpdate(String sql) throws SQLException {
+ throw new UnsupportedOperationException("executeLargeUpdate not implemented");
+ }
+
+ /**
+ * Executes the given SQL statement and signals the driver with the
+ * given flag about whether the
+ * 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>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ * <p>
+ * <strong>Note:</strong>This method cannot be called on a
+ * <code>PreparedStatement</code> or <code>CallableStatement</code>.
+ *<p>
+ * The default implementation will throw {@code SQLFeatureNotSupportedException}
+ *
+ * @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
+ * should be made available for retrieval;
+ * one of the following constants:
+ * <code>Statement.RETURN_GENERATED_KEYS</code>
+ * <code>Statement.NO_GENERATED_KEYS</code>
+ * @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,
+ * 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.8
+ */
+ default long executeLargeUpdate(String sql, int autoGeneratedKeys)
+ throws SQLException {
+ throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
+ }
+
+ /**
+ * Executes the given SQL statement and signals the driver that the
+ * auto-generated keys indicated in the given array should be made available
+ * 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>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ * <p>
+ * <strong>Note:</strong>This method cannot be called on a
+ * <code>PreparedStatement</code> or <code>CallableStatement</code>.
+ *<p>
+ * The default implementation will throw {@code SQLFeatureNotSupportedException}
+ *
+ * @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
+ * that should be returned from the inserted row
+ * @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,the second argument
+ * supplied to this method is not an
+ * <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.8
+ */
+ default long executeLargeUpdate(String sql, int columnIndexes[]) throws SQLException {
+ throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
+ }
+
+ /**
+ * Executes the given SQL statement and signals the driver that the
+ * auto-generated keys indicated in the given array should be made available
+ * 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>
+ * This method should be used when the returned row count may exceed
+ * {@link Integer.MAX_VALUE}.
+ * <p>
+ * <strong>Note:</strong>This method cannot be called on a
+ * <code>PreparedStatement</code> or <code>CallableStatement</code>.
+ *<p>
+ * The default implementation will throw {@code SQLFeatureNotSupportedException}
+ *
+ * @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, the
+ * second argument supplied to this method is not a <code>String</code> array
+ * 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.8
+ */
+ default long executeLargeUpdate(String sql, String columnNames[])
+ throws SQLException {
+ throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
+ }
}
+