diff options
Diffstat (limited to 'src/share/classes/java/sql/Statement.java')
| -rw-r--r-- | src/share/classes/java/sql/Statement.java | 312 |
1 files changed, 310 insertions, 2 deletions
diff --git a/src/share/classes/java/sql/Statement.java b/src/share/classes/java/sql/Statement.java index d249a2f46a..584f17c0a1 100644 --- a/src/share/classes/java/sql/Statement.java +++ b/src/share/classes/java/sql/Statement.java @@ -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 @@ public interface Statement extends Wrapper, AutoCloseable { * 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 interface Statement extends Wrapper, AutoCloseable { */ 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"); + } } + |