| /* |
| * 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. |
| * <p> |
| * To have multiple {@code ResultSet} objects opened concurrently, multiple |
| * {@code Statement} objects must be created and then executed. |
| * <p> |
| * 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 <i>getMoreResults</i> 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}. |
| * <p> |
| * 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. |
| * <p> |
| * Using this method to release these resources as soon as possible is |
| * strongly recommended. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * <ol> |
| * <li>If the value of an element is ≥ 0, the corresponding |
| * command completed successfully and the value is the <i>update |
| * count</i> (the number of rows in the database affected by the |
| * command) for that command.</li> |
| * <li>If the value is {@code SUCCESS_NO_INFO}, the command |
| * completed successfully but the number of rows affected is |
| * unknown. |
| * <li> |
| * <li>If the value is {@code EXECUTE_FAILED}, the command failed. |
| * </ol> |
| * @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: |
| * <ul> |
| * <li>ResultSet.FETCH_FORWARD</li> <li>ResultSet.FETCH_REVERSE</li> |
| * <li>ResultSet.FETCH_UNKNOWN</li> |
| * </ul> |
| * @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. |
| * <p> |
| * 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. |
| * <p> |
| * Cursor names must be unique within one Connection. |
| * <p> |
| * 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. |
| * <p> |
| * 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 <i>on</i>, {@code |
| * false} to turn it <i>off</i>. |
| * @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 |
| * <ul> |
| * <li>{@code ResultSet.FETCH_UNKNOWN}</li> |
| * <li>{@code ResultSet.FETCH_FORWARD}</li> |
| * <li>{@code ResultSet.FETCH_REVERSE}</li> |
| * </ul> |
| * @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; |
| } |
