1 /* Statement.java -- Interface for executing SQL statements. 2 Copyright (C) 1999, 2000, 2002, 2006 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package java.sql; 40 41 /** 42 * This interface provides a mechanism for executing SQL statements. 43 * 44 * @author Aaron M. Renn (arenn@urbanophile.com) 45 */ 46 public interface Statement 47 extends AutoCloseable 48 { 49 int CLOSE_CURRENT_RESULT = 1; 50 int KEEP_CURRENT_RESULT = 2; 51 int CLOSE_ALL_RESULTS = 3; 52 int SUCCESS_NO_INFO = -2; 53 int EXECUTE_FAILED = -3; 54 int RETURN_GENERATED_KEYS = 1; 55 int NO_GENERATED_KEYS = 2; 56 57 /** 58 * This method executes the specified SQL SELECT statement and returns a 59 * (possibly empty) <code>ResultSet</code> with the results of the query. 60 * 61 * @param sql The SQL statement to execute. 62 * @return The result set of the SQL statement. 63 * @exception SQLException If an error occurs. 64 */ executeQuery(String sql)65 ResultSet executeQuery(String sql) throws SQLException; 66 67 /** 68 * This method executes the specified SQL INSERT, UPDATE, or DELETE statement 69 * and returns the number of rows affected, which may be 0. 70 * 71 * @param sql The SQL statement to execute. 72 * @return The number of rows affected by the SQL statement. 73 * @exception SQLException If an error occurs. 74 */ executeUpdate(String sql)75 int executeUpdate(String sql) throws SQLException; 76 77 /** 78 * This method closes the statement and frees any associated resources. 79 * 80 * @exception SQLException If an error occurs. 81 */ close()82 void close() throws SQLException; 83 84 /** 85 * This method returns the maximum length of any column value in bytes. 86 * 87 * @return The maximum length of any column value in bytes. 88 * @exception SQLException If an error occurs. 89 */ getMaxFieldSize()90 int getMaxFieldSize() throws SQLException; 91 92 /** 93 * This method sets the limit for the maximum length of any column in bytes. 94 * 95 * @param maxSize The new maximum length of any column in bytes. 96 * @exception SQLException If an error occurs. 97 */ setMaxFieldSize(int maxSize)98 void setMaxFieldSize(int maxSize) throws SQLException; 99 100 /** 101 * This method returns the maximum possible number of rows in a result set. 102 * 103 * @return The maximum possible number of rows in a result set. 104 * @exception SQLException If an error occurs. 105 */ getMaxRows()106 int getMaxRows() throws SQLException; 107 108 /** 109 * This method sets the maximum number of rows that can be present in a 110 * result set. 111 * 112 * @param maxRows The maximum possible number of rows in a result set. 113 * @exception SQLException If an error occurs. 114 */ setMaxRows(int maxRows)115 void setMaxRows(int maxRows) throws SQLException; 116 117 /** 118 * This method sets the local escape processing mode on or off. The 119 * default value is on. 120 * 121 * @param escape <code>true</code> to enable local escape processing, 122 * <code>false</code> to disable it. 123 * @exception SQLException If an error occurs. 124 */ setEscapeProcessing(boolean escape)125 void setEscapeProcessing(boolean escape) throws SQLException; 126 127 /** 128 * The method returns the number of seconds a statement may be in process 129 * before timing out. A value of 0 means there is no timeout. 130 * 131 * @return The SQL statement timeout in seconds. 132 * @exception SQLException If an error occurs. 133 */ getQueryTimeout()134 int getQueryTimeout() throws SQLException; 135 136 /** 137 * This method sets the number of seconds a statement may be in process 138 * before timing out. A value of 0 means there is no timeout. 139 * 140 * @param seconds The new SQL statement timeout value. 141 * @exception SQLException If an error occurs. 142 */ setQueryTimeout(int seconds)143 void setQueryTimeout(int seconds) throws SQLException; 144 145 /** 146 * This method cancels an outstanding statement, if the database supports 147 * that operation. 148 * 149 * @exception SQLException If an error occurs. 150 */ cancel()151 void cancel() throws SQLException; 152 153 /** 154 * This method returns the first SQL warning attached to this statement. 155 * Subsequent warnings will be chained to this one. 156 * 157 * @return The first SQL warning for this statement. 158 * @exception SQLException If an error occurs. 159 */ getWarnings()160 SQLWarning getWarnings() throws SQLException; 161 162 /** 163 * This method clears any SQL warnings that have been attached to this 164 * statement. 165 * 166 * @exception SQLException If an error occurs. 167 */ clearWarnings()168 void clearWarnings() throws SQLException; 169 170 /** 171 * This method sets the cursor name that will be used by the result set. 172 * 173 * @param name The cursor name to use for this statement. 174 * @exception SQLException If an error occurs. 175 */ setCursorName(String name)176 void setCursorName(String name) throws SQLException; 177 178 /** 179 * This method executes an arbitrary SQL statement of any time. The 180 * methods <code>getResultSet</code>, <code>getMoreResults</code> and 181 * <code>getUpdateCount</code> retrieve the results. 182 * 183 * @return <code>true</code> if a result set was returned, <code>false</code> 184 * if an update count was returned. 185 * @exception SQLException If an error occurs. 186 */ execute(String sql)187 boolean execute(String sql) throws SQLException; 188 189 /** 190 * This method returns the result set of the SQL statement that was 191 * executed. This should be called only once per result set returned. 192 * 193 * @return The result set of the query, or <code>null</code> if there was 194 * no result set (for example, if the statement was an UPDATE). 195 * @exception SQLException If an error occurs. 196 * @see #execute(String) 197 * @see #execute(String, int) 198 * @see #execute(String, int[]) 199 * @see #execute(String, String[]) 200 */ getResultSet()201 ResultSet getResultSet() throws SQLException; 202 203 /** 204 * This method returns the update count of the SQL statement that was 205 * executed. This should be called only once per executed SQL statement. 206 * 207 * @return The update count of the query, or -1 if there was no update 208 * count (for example, if the statement was a SELECT). 209 * @exception SQLException If an error occurs. 210 * @see #execute(String) 211 * @see #execute(String, int) 212 * @see #execute(String, int[]) 213 * @see #execute(String, String[]) 214 */ getUpdateCount()215 int getUpdateCount() throws SQLException; 216 217 /** 218 * This method advances the result set pointer to the next result set, 219 * which can then be retrieved using <code>getResultSet</code> 220 * 221 * @return <code>true</code> if there is another result set, 222 * <code>false</code> otherwise (for example, the next result is an 223 * update count). 224 * @exception SQLException If an error occurs. 225 * @see #execute(String) 226 * @see #execute(String, int) 227 * @see #execute(String, int[]) 228 * @see #execute(String, String[]) 229 */ getMoreResults()230 boolean getMoreResults() throws SQLException; 231 232 /** 233 * This method informs the driver which direction the result set will 234 * be accessed in. 235 * 236 * @param direction The direction the result set will be accessed in (?????) 237 * @exception SQLException If an error occurs. 238 */ setFetchDirection(int direction)239 void setFetchDirection(int direction) throws SQLException; 240 241 /** 242 * This method returns the current direction that the driver thinks the 243 * result set will be accessed int. 244 * 245 * @return The direction the result set will be accessed in (????) 246 * @exception SQLException If an error occurs. 247 */ getFetchDirection()248 int getFetchDirection() throws SQLException; 249 250 /** 251 * This method informs the driver how many rows it should fetch from the 252 * database at a time. 253 * 254 * @param numRows The number of rows the driver should fetch at a time 255 * to populate the result set. 256 * @exception SQLException If an error occurs. 257 */ setFetchSize(int numRows)258 void setFetchSize(int numRows) throws SQLException; 259 260 /** 261 * This method returns the number of rows the driver believes should be 262 * fetched from the database at a time. 263 * 264 * @return The number of rows that will be fetched from the database at a time. 265 * @exception SQLException If an error occurs. 266 */ getFetchSize()267 int getFetchSize() throws SQLException; 268 269 /** 270 * This method returns the concurrency type of the result set for this 271 * statement. This will be one of the concurrency types defined in 272 * <code>ResultSet</code>. 273 * 274 * @return The concurrency type of the result set for this statement. 275 * @exception SQLException If an error occurs. 276 * @see ResultSet 277 */ getResultSetConcurrency()278 int getResultSetConcurrency() throws SQLException; 279 280 /** 281 * This method returns the result set type for this statement. This will 282 * be one of the result set types defined in <code>ResultSet</code>. 283 * 284 * @return The result set type for this statement. 285 * @exception SQLException If an error occurs. 286 * @see ResultSet 287 */ getResultSetType()288 int getResultSetType() throws SQLException; 289 290 /** 291 * This method adds a SQL statement to a SQL batch. A driver is not 292 * required to implement this method. 293 * 294 * @param sql The sql statement to add to the batch. 295 * @exception SQLException If an error occurs. 296 */ addBatch(String sql)297 void addBatch(String sql) throws SQLException; 298 299 /** 300 * This method clears out any SQL statements that have been populated in 301 * the current batch. A driver is not required to implement this method. 302 * 303 * @exception SQLException If an error occurs. 304 */ clearBatch()305 void clearBatch() throws SQLException; 306 307 /** 308 * This method executes the SQL batch and returns an array of update 309 * counts - one for each SQL statement in the batch - ordered in the same 310 * order the statements were added to the batch. A driver is not required 311 * to implement this method. 312 * 313 * @return An array of update counts for this batch. 314 * @exception SQLException If an error occurs. 315 */ executeBatch()316 int[] executeBatch() throws SQLException; 317 318 /** 319 * This method returns the <code>Connection</code> instance that was 320 * used to create this object. 321 * 322 * @return The connection used to create this object. 323 * @exception SQLException If an error occurs. 324 */ getConnection()325 Connection getConnection() throws SQLException; 326 327 /** 328 * @since 1.4 329 */ getMoreResults(int current)330 boolean getMoreResults(int current) throws SQLException; 331 332 /** 333 * @since 1.4 334 */ getGeneratedKeys()335 ResultSet getGeneratedKeys() throws SQLException; 336 337 /** 338 * @since 1.4 339 */ executeUpdate(String sql, int autoGeneratedKeys)340 int executeUpdate(String sql, int autoGeneratedKeys) 341 throws SQLException; 342 343 /** 344 * @since 1.4 345 */ executeUpdate(String sql, int[] columnIndexes)346 int executeUpdate(String sql, int[] columnIndexes) 347 throws SQLException; 348 349 /** 350 * @since 1.4 351 */ executeUpdate(String sql, String[] columnNames)352 int executeUpdate(String sql, String[] columnNames) 353 throws SQLException; 354 355 /** 356 * @since 1.4 357 */ execute(String sql, int autoGeneratedKeys)358 boolean execute(String sql, int autoGeneratedKeys) 359 throws SQLException; 360 361 /** 362 * @since 1.4 363 */ execute(String sql, int[] columnIndexes)364 boolean execute(String sql, int[] columnIndexes) throws SQLException; 365 366 /** 367 * @since 1.4 368 */ execute(String sql, String[] columnNames)369 boolean execute(String sql, String[] columnNames) 370 throws SQLException; 371 372 /** 373 * @since 1.4 374 */ getResultSetHoldability()375 int getResultSetHoldability() throws SQLException; 376 } 377