/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package java.sql; /** * Interface used for executing static SQL statements to retrieve query results. * The resulting table rows are returned as {@code ResultSet}s. For any given * {@code Statement} object, only one {@code ResultSet} can be opened at one * time. A call to any of the execution methods of {@code Statement} will cause * any previously created {@code ResultSet} object for that {@code Statement} to * be closed implicitly. *

* To have multiple {@code ResultSet} objects opened concurrently, multiple * {@code Statement} objects must be created and then executed. *

* To obtain such an executable statement one needs to invoke {@code * Connection#createStatement}. * * @see ResultSet * @see Connection#createStatement */ public interface Statement extends Wrapper, AutoCloseable { /** * Passing this constant to {@link #getMoreResults} implies that all {@code * ResultSet} objects previously kept open should be closed. */ public static final int CLOSE_ALL_RESULTS = 3; /** * Passing this constant to {@link #getMoreResults} implies that the current * {@code ResultSet} object should be closed. */ public static final int CLOSE_CURRENT_RESULT = 1; /** * Indicates that an error was encountered during execution of a batch * statement. */ public static final int EXECUTE_FAILED = -3; /** * Passing this constant to getMoreResults implies that the current * {@code ResultSet} object should not be closed. */ public static final int KEEP_CURRENT_RESULT = 2; /** * Indicates that generated keys should not be accessible for retrieval. */ public static final int NO_GENERATED_KEYS = 2; /** * Indicates that generated keys should be accessible for retrieval. */ public static final int RETURN_GENERATED_KEYS = 1; /** * Indicates that a batch statement was executed with a successful result, * but a count of the number of rows it affected is unavailable. */ public static final int SUCCESS_NO_INFO = -2; /** * Adds a specified SQL command to the list of commands for this {@code * Statement}. *

* The list of commands is executed by invoking the {@code executeBatch} * method. * * @param sql * the SQL command as a String. Typically an {@code INSERT} or * {@code UPDATE} statement. * @throws SQLException * if an error occurs accessing the database or the database * does not support batch updates. */ public void addBatch(String sql) throws SQLException; /** * Cancels this statement's execution if both the database and the JDBC * driver support aborting an SQL statement in flight. This method can be * used by one thread to stop a statement that is executed on another * thread. * * @throws SQLException * if an error occurs accessing the database. */ public void cancel() throws SQLException; /** * Clears the current list of SQL commands for this statement. * * @throws SQLException * if an error occurs accessing the database or the database * does not support batch updates. */ public void clearBatch() throws SQLException; /** * Clears all {@code SQLWarnings} from this statement. * * @throws SQLException * if an error occurs accessing the database. */ public void clearWarnings() throws SQLException; /** * Releases this statement's database and JDBC driver resources. *

* Using this method to release these resources as soon as possible is * strongly recommended. *

* One should not rely on the resources being automatically released when * finalized during garbage collection. Doing so can result in unpredictable * behavior for the application. * * @throws SQLException * if an error occurs accessing the database. */ public void close() throws SQLException; /** * Executes a supplied SQL statement. This may return multiple {@code * ResultSet}s. *

* Use the {@code getResultSet} or {@code getUpdateCount} methods to get the * first result and {@code getMoreResults} to get any subsequent results. * * @param sql * the SQL statement to execute * @return {@code true} if the first result is a {@code ResultSet}, {@code * false} if the first result is an update count or if there is no * result. * @throws SQLException * if an error occurs accessing the database. */ public boolean execute(String sql) throws SQLException; /** * Executes a supplied SQL statement. This may return multiple {@code * ResultSet}s. This method allows control of whether auto-generated Keys * should be made available for retrieval, if the SQL statement is an * {@code INSERT} statement. *

* Use the {@code getResultSet} or {@code getUpdateCount} methods to get the * first result and {@code getMoreResults} to get any subsequent results. * * @param sql * the SQL statement to execute. * @param autoGeneratedKeys * a flag indicating whether to make auto generated keys * available for retrieval. This parameter must be one of {@code * Statement.NO_GENERATED_KEYS} or {@code * Statement.RETURN_GENERATED_KEYS}. * @return {@code true} if results exists and the first result is a {@code * ResultSet}, {@code false} if the first result is an update count * or if there is no result. * @throws SQLException * if an error occurs accessing the database. */ public boolean execute(String sql, int autoGeneratedKeys) throws SQLException; /** * Executes the supplied SQL statement. This may return multiple {@code * ResultSet}s. This method allows retrieval of auto generated keys * specified by the supplied array of column indexes, if the SQL statement * is an {@code INSERT} statement. *

* Use the {@code getResultSet} or {@code getUpdateCount} methods to get the * first result and {@code getMoreResults} to get any subsequent results. * * @param sql * the SQL statement to execute. * @param columnIndexes * an array of indexes of the columns in the inserted row which * should be made available for retrieval via the {@code * getGeneratedKeys} method. * @return {@code true} if the first result is a {@code ResultSet}, {@code * false} if the first result is an update count or if there is no * result. * @throws SQLException * if an error occurs accessing the database. */ public boolean execute(String sql, int[] columnIndexes) throws SQLException; /** * Executes the supplied SQL statement. This may return multiple {@code * ResultSet}s. This method allows retrieval of auto generated keys * specified by the supplied array of column indexes, if the SQL statement * is an {@code INSERT} statement. *

* Use the {@code getResultSet} or {@code getUpdateCount} methods to get the * first result and {@code getMoreResults} to get any subsequent results. * * @param sql * the SQL statement to execute. * @param columnNames * an array of column names in the inserted row which should be * made available for retrieval via the {@code getGeneratedKeys} * method. * @return {@code true} if the first result is a {@code ResultSet}, {@code * false} if the first result is an update count or if there is no * result * @throws SQLException * if an error occurs accessing the database. */ public boolean execute(String sql, String[] columnNames) throws SQLException; /** * Submits a batch of SQL commands to the database. Returns an array of * update counts, if all the commands execute successfully. *

* If one of the commands in the batch fails, this method can throw a * {@link BatchUpdateException} and the JDBC driver may or may not process * the remaining commands. The JDBC driver must behave consistently with the * underlying database, following the "all or nothing" principle. If the * driver continues processing, the array of results returned contains the * same number of elements as there are commands in the batch, with a * minimum of one of the elements having the {@code EXECUTE_FAILED} value. * * @return an array of update counts, with one entry for each command in the * batch. The elements are ordered according to the order in which * the commands were added to the batch. *

*

    *
  1. If the value of an element is ≥ 0, the corresponding * command completed successfully and the value is the update * count (the number of rows in the database affected by the * command) for that command.
    2. *
  2. If the value is {@code SUCCESS_NO_INFO}, the command * completed successfully but the number of rows affected is * unknown. *
  3. *
  4. If the value is {@code EXECUTE_FAILED}, the command failed. *
* @throws SQLException * if an error occurs accessing the database. */ public int[] executeBatch() throws SQLException; /** * Executes a supplied SQL statement. Returns a single {@code ResultSet}. * * @param sql * an SQL statement to execute. Typically a {@code SELECT} * statement * @return a {@code ResultSet} containing the data produced by the SQL * statement. Never null. * @throws SQLException * if an error occurs accessing the database or if the statement * produces anything other than a single {@code ResultSet}. */ public ResultSet executeQuery(String sql) throws SQLException; /** * Executes the supplied SQL statement. The statement may be an {@code * INSERT}, {@code UPDATE} or {@code DELETE} statement or a statement which * returns nothing. * * @param sql * an SQL statement to execute - an SQL {@code INSERT}, {@code * UPDATE}, {@code DELETE} or a statement which returns nothing * @return the count of updated rows, or 0 for a statement that returns * nothing. * @throws SQLException * if an error occurs accessing the database or if the statement * produces a {@code ResultSet}. */ public int executeUpdate(String sql) throws SQLException; /** * Executes the supplied SQL statement. This method allows control of * whether auto-generated Keys should be made available for retrieval. * * @param sql * an SQL statement to execute - an SQL {@code INSERT}, {@code * UPDATE}, {@code DELETE} or a statement which does not return * anything. * @param autoGeneratedKeys * a flag that indicates whether to allow retrieval of auto * generated keys. Parameter must be one of {@code * Statement.RETURN_GENERATED_KEYS} or {@code * Statement.NO_GENERATED_KEYS} * @return the number of updated rows, or 0 if the statement returns * nothing. * @throws SQLException * if an error occurs accessing the database or if the statement * produces a {@code ResultSet}. */ public int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException; /** * Executes the supplied SQL statement. This method allows retrieval of auto * generated keys specified by the supplied array of column indexes. * * @param sql * an SQL statement to execute - an SQL {@code INSERT}, {@code * UPDATE}, {@code DELETE} or a statement which returns nothing * @param columnIndexes * an array of indexes of the columns in the inserted row which * should be made available for retrieval via the {@code * getGeneratedKeys} method. * @return the count of updated rows, or 0 for a statement that returns * nothing. * @throws SQLException * if an error occurs accessing the database or if the statement * produces a {@code ResultSet}. */ public int executeUpdate(String sql, int[] columnIndexes) throws SQLException; /** * Executes the supplied SQL statement. This method allows retrieval of auto * generated keys specified by the supplied array of column names. * * @param sql * an SQL statement to execute - an SQL {@code INSERT}, {@code * UPDATE}, {@code DELETE} or a statement which returns nothing * @param columnNames * an array of column names in the inserted row which should be * made available for retrieval via the {@code getGeneratedKeys} * method. * @return the count of updated rows, or 0 for a statement that returns * nothing. * @throws SQLException * if an error occurs accessing the database or if the statement * produces a {@code ResultSet}. */ public int executeUpdate(String sql, String[] columnNames) throws SQLException; /** * Gets the {@code Connection} object which created this statement. * * @return the {@code Connection} through which this statement is * transmitted to the database. * @throws SQLException * if an error occurs accessing the database. */ public Connection getConnection() throws SQLException; /** * Gets the default direction for fetching rows for {@code ResultSet}s * generated from this statement. * * @return the default fetch direction, one of: * * @throws SQLException * if an error occurs accessing the database. */ public int getFetchDirection() throws SQLException; /** * Gets the default number of rows for a fetch for the {@code ResultSet} * objects returned from this statement. * * @return the default fetch size for {@code ResultSet}s produced by this * statement. * @throws SQLException * if an error occurs accessing the database. */ public int getFetchSize() throws SQLException; /** * Returns auto generated keys created by executing this statement. * * @return a {@code ResultSet} containing the auto generated keys - empty if * no keys are generated by this statement. * @throws SQLException * if an error occurs accessing the database. */ public ResultSet getGeneratedKeys() throws SQLException; /** * Gets the maximum number of bytes which can be returned as values from * character and binary type columns in a {@code ResultSet} derived from this * statement. This limit applies to {@code BINARY}, {@code VARBINARY}, * {@code LONGVARBINARY}, {@code CHAR}, {@code VARCHAR}, and {@code * LONGVARCHAR} types. Any data exceeding the maximum size is abandoned * without announcement. * * @return the current size limit, where {@code 0} means that there is no * limit. * @throws SQLException * if an error occurs accessing the database. */ public int getMaxFieldSize() throws SQLException; /** * Gets the maximum number of rows that a {@code ResultSet} can contain when * produced from this statement. If the limit is exceeded, the excess rows * are discarded silently. * * @return the current row limit, where {@code 0} means that there is no * limit. * @throws SQLException * if an error occurs accessing the database. */ public int getMaxRows() throws SQLException; /** * Moves to this statement's next result. Returns {@code true} if it is a * {@code ResultSet}. Any current {@code ResultSet} objects previously * obtained with {@code getResultSet()} are closed implicitly. * * @return {@code true} if the next result is a {@code ResultSet}, {@code * false} if the next result is not a {@code ResultSet} or if there * are no more results. Note that if there is no more data, this * method will return {@code false} and {@code getUpdateCount} will * return -1. * @throws SQLException * if an error occurs accessing the database. */ public boolean getMoreResults() throws SQLException; /** * Moves to this statement's next result. Returns {@code true} if the next * result is a {@code ResultSet}. Any current {@code ResultSet} objects * previously obtained with {@code getResultSet()} are handled as indicated * by a supplied Flag parameter. * * @param current * a flag indicating what to do with existing {@code ResultSet}s. * This parameter must be one of {@code * Statement.CLOSE_ALL_RESULTS}, {@code * Statement.CLOSE_CURRENT_RESULT} or {@code * Statement.KEEP_CURRENT_RESULT}. * @return {@code true} if the next result exists and is a {@code ResultSet} * , {@code false} if the next result is not a {@code ResultSet} or * if there are no more results. Note that if there is no more data, * this method will return {@code false} and {@code getUpdateCount} * will return -1. * @throws SQLException * if an error occurs accessing the database. */ public boolean getMoreResults(int current) throws SQLException; /** * Gets the timeout value for the statement's execution time. The JDBC * driver will wait up to this value for the execution to complete - after * the limit is exceeded an SQL {@code Exception} is thrown. * * @return the current query timeout value, where {@code 0} indicates that * there is no current timeout. * @throws SQLException * if an error occurs accessing the database. */ public int getQueryTimeout() throws SQLException; /** * Gets the current result. Should only be called once per result. * * @return the {@code ResultSet} for the current result. {@code null} if the * result is an update count or if there are no more results. * @throws SQLException * if an error occurs accessing the database. */ public ResultSet getResultSet() throws SQLException; /** * Gets the concurrency setting for {@code ResultSet} objects generated by * this statement. * * @return {@code ResultSet.CONCUR_READ_ONLY} or {@code * ResultSet.CONCUR_UPDATABLE}. * @throws SQLException * if an error occurs accessing the database. */ public int getResultSetConcurrency() throws SQLException; /** * Gets the cursor hold setting for {@code ResultSet} objects generated by * this statement. * * @return {@code ResultSet.HOLD_CURSORS_OVER_COMMIT} or {@code * ResultSet.CLOSE_CURSORS_AT_COMMIT} * @throws SQLException * if there is an error while accessing the database. */ public int getResultSetHoldability() throws SQLException; /** * Gets the {@code ResultSet} type setting for {@code ResultSet}s derived * from this statement. * * @return {@code ResultSet.TYPE_FORWARD_ONLY} for a {@code ResultSet} where * the cursor can only move forwards, {@code * ResultSet.TYPE_SCROLL_INSENSITIVE} for a {@code ResultSet} which * is scrollable but is not sensitive to changes made by others, * {@code ResultSet.TYPE_SCROLL_SENSITIVE} for a {@code ResultSet} * which is scrollable but is sensitive to changes made by others. * @throws SQLException * if there is an error accessing the database. */ public int getResultSetType() throws SQLException; /** * Gets an update count for the current result if it is not a {@code * ResultSet}. * * @return the current result as an update count. {@code -1} if the current * result is a {@code ResultSet} or if there are no more results. * @throws SQLException * if an error occurs accessing the database. */ public int getUpdateCount() throws SQLException; /** * Retrieves the first {@code SQLWarning} reported by calls on this * statement. If there are multiple warnings, subsequent warnings are * chained to the first one. The chain of warnings is cleared each time the * statement is executed. *

* Warnings associated with reads from the {@code ResultSet} returned from * executing the statement will be attached to the {@code ResultSet}, not the * statement object. * * @return an SQLWarning, null if there are no warnings * @throws SQLException * if an error occurs accessing the database. */ public SQLWarning getWarnings() throws SQLException; /** * Sets the SQL cursor name. This name is used by subsequent statement * execute methods. *

* Cursor names must be unique within one Connection. *

* With the cursor name set, it can then be used in SQL positioned * update or delete statements to determine the current row in a {@code * ResultSet} generated from this statement. The positioned update or delete * must be done with a different statement than this one. * * @param name * the Cursor name as a string, * @throws SQLException * if an error occurs accessing the database. */ public void setCursorName(String name) throws SQLException; /** * Sets Escape Processing mode. *

* If Escape Processing is on, the JDBC driver will do escape substitution * on an SQL statement before sending it for execution. This does not apply * to {@link PreparedStatement}s since they are processed when created, * before this method can be called. * * @param enable * {@code true} to set escape processing mode on, {@code * false} to turn it off. * @throws SQLException * if an error occurs accessing the database. */ public void setEscapeProcessing(boolean enable) throws SQLException; /** * Sets the fetch direction - a hint to the JDBC driver about the direction * of processing of rows in {@code ResultSet}s created by this statement. * The default fetch direction is {@code FETCH_FORWARD}. * * @param direction * which fetch direction to use. This parameter should be one of *

* @throws SQLException * if there is an error while accessing the database or if the * fetch direction is unrecognized. */ public void setFetchDirection(int direction) throws SQLException; /** * Sets the fetch size. This is a hint to the JDBC driver about how many * rows should be fetched from the database when more are required by * application processing. * * @param rows * the number of rows that should be fetched. {@code 0} tells the driver * to ignore the hint. Should be less than {@code getMaxRows} for * this statement. Should not be negative. * @throws SQLException * if an error occurs accessing the database, or if the rows * parameter is out of range. */ public void setFetchSize(int rows) throws SQLException; /** * Sets the maximum number of bytes for {@code ResultSet} columns that * contain character or binary values. This applies to {@code BINARY}, * {@code VARBINARY}, {@code LONGVARBINARY}, {@code CHAR}, {@code VARCHAR}, * and {@code LONGVARCHAR} fields. Any data exceeding the maximum size is * abandoned without announcement. * * @param max * the maximum field size in bytes. {@code 0} means "no limit". * @throws SQLException * if an error occurs accessing the database or the {@code max} * value is < {@code 0}. */ public void setMaxFieldSize(int max) throws SQLException; /** * Sets the maximum number of rows that any {@code ResultSet} can contain. * If the number of rows exceeds this value, the additional rows are * silently discarded. * * @param max * the maximum number of rows. {@code 0} means "no limit". * @throws SQLException * if an error occurs accessing the database or if max < {@code * 0}. */ public void setMaxRows(int max) throws SQLException; /** * Sets the timeout, in seconds, for queries - how long the driver will * allow for completion of a statement execution. If the timeout is * exceeded, the query will throw an {@code SQLException}. * * @param seconds * timeout in seconds. 0 means no timeout ("wait forever") * @throws SQLException * if an error occurs accessing the database or if seconds < * {@code 0}. */ public void setQueryTimeout(int seconds) throws SQLException; /** * Returns true if this statement has been closed, false otherwise. */ public boolean isClosed() throws SQLException; /** * Hints whether this statement should be pooled. Defaults to false for {@code Statement}, * but true for {@code CallableStatement} and {@code PreparedStatement}. Pool manager * implementations may or may not honor this hint. */ public void setPoolable(boolean poolable) throws SQLException; /** * Returns true if this statement is poolable, false otherwise. */ public boolean isPoolable() throws SQLException; }