001 /* Statement.java -- Interface for executing SQL statements. 002 Copyright (C) 1999, 2000, 2002, 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.sql; 040 041 /** 042 * This interface provides a mechanism for executing SQL statements. 043 * 044 * @author Aaron M. Renn (arenn@urbanophile.com) 045 */ 046 public interface Statement 047 { 048 int CLOSE_CURRENT_RESULT = 1; 049 int KEEP_CURRENT_RESULT = 2; 050 int CLOSE_ALL_RESULTS = 3; 051 int SUCCESS_NO_INFO = -2; 052 int EXECUTE_FAILED = -3; 053 int RETURN_GENERATED_KEYS = 1; 054 int NO_GENERATED_KEYS = 2; 055 056 /** 057 * This method executes the specified SQL SELECT statement and returns a 058 * (possibly empty) <code>ResultSet</code> with the results of the query. 059 * 060 * @param sql The SQL statement to execute. 061 * @return The result set of the SQL statement. 062 * @exception SQLException If an error occurs. 063 */ 064 ResultSet executeQuery(String sql) throws SQLException; 065 066 /** 067 * This method executes the specified SQL INSERT, UPDATE, or DELETE statement 068 * and returns the number of rows affected, which may be 0. 069 * 070 * @param sql The SQL statement to execute. 071 * @return The number of rows affected by the SQL statement. 072 * @exception SQLException If an error occurs. 073 */ 074 int executeUpdate(String sql) throws SQLException; 075 076 /** 077 * This method closes the statement and frees any associated resources. 078 * 079 * @exception SQLException If an error occurs. 080 */ 081 void close() throws SQLException; 082 083 /** 084 * This method returns the maximum length of any column value in bytes. 085 * 086 * @return The maximum length of any column value in bytes. 087 * @exception SQLException If an error occurs. 088 */ 089 int getMaxFieldSize() throws SQLException; 090 091 /** 092 * This method sets the limit for the maximum length of any column in bytes. 093 * 094 * @param maxSize The new maximum length of any column in bytes. 095 * @exception SQLException If an error occurs. 096 */ 097 void setMaxFieldSize(int maxSize) throws SQLException; 098 099 /** 100 * This method returns the maximum possible number of rows in a result set. 101 * 102 * @return The maximum possible number of rows in a result set. 103 * @exception SQLException If an error occurs. 104 */ 105 int getMaxRows() throws SQLException; 106 107 /** 108 * This method sets the maximum number of rows that can be present in a 109 * result set. 110 * 111 * @param maxRows The maximum possible number of rows in a result set. 112 * @exception SQLException If an error occurs. 113 */ 114 void setMaxRows(int maxRows) throws SQLException; 115 116 /** 117 * This method sets the local escape processing mode on or off. The 118 * default value is on. 119 * 120 * @param escape <code>true</code> to enable local escape processing, 121 * <code>false</code> to disable it. 122 * @exception SQLException If an error occurs. 123 */ 124 void setEscapeProcessing(boolean escape) throws SQLException; 125 126 /** 127 * The method returns the number of seconds a statement may be in process 128 * before timing out. A value of 0 means there is no timeout. 129 * 130 * @return The SQL statement timeout in seconds. 131 * @exception SQLException If an error occurs. 132 */ 133 int getQueryTimeout() throws SQLException; 134 135 /** 136 * This method sets the number of seconds a statement may be in process 137 * before timing out. A value of 0 means there is no timeout. 138 * 139 * @param seconds The new SQL statement timeout value. 140 * @exception SQLException If an error occurs. 141 */ 142 void setQueryTimeout(int seconds) throws SQLException; 143 144 /** 145 * This method cancels an outstanding statement, if the database supports 146 * that operation. 147 * 148 * @exception SQLException If an error occurs. 149 */ 150 void cancel() throws SQLException; 151 152 /** 153 * This method returns the first SQL warning attached to this statement. 154 * Subsequent warnings will be chained to this one. 155 * 156 * @return The first SQL warning for this statement. 157 * @exception SQLException If an error occurs. 158 */ 159 SQLWarning getWarnings() throws SQLException; 160 161 /** 162 * This method clears any SQL warnings that have been attached to this 163 * statement. 164 * 165 * @exception SQLException If an error occurs. 166 */ 167 void clearWarnings() throws SQLException; 168 169 /** 170 * This method sets the cursor name that will be used by the result set. 171 * 172 * @param name The cursor name to use for this statement. 173 * @exception SQLException If an error occurs. 174 */ 175 void setCursorName(String name) throws SQLException; 176 177 /** 178 * This method executes an arbitrary SQL statement of any time. The 179 * methods <code>getResultSet</code>, <code>getMoreResults</code> and 180 * <code>getUpdateCount</code> retrieve the results. 181 * 182 * @return <code>true</code> if a result set was returned, <code>false</code> 183 * if an update count was returned. 184 * @exception SQLException If an error occurs. 185 */ 186 boolean execute(String sql) throws SQLException; 187 188 /** 189 * This method returns the result set of the SQL statement that was 190 * executed. This should be called only once per result set returned. 191 * 192 * @return The result set of the query, or <code>null</code> if there was 193 * no result set (for example, if the statement was an UPDATE). 194 * @exception SQLException If an error occurs. 195 * @see #execute(String) 196 * @see #execute(String, int) 197 * @see #execute(String, int[]) 198 * @see #execute(String, String[]) 199 */ 200 ResultSet getResultSet() throws SQLException; 201 202 /** 203 * This method returns the update count of the SQL statement that was 204 * executed. This should be called only once per executed SQL statement. 205 * 206 * @return The update count of the query, or -1 if there was no update 207 * count (for example, if the statement was a SELECT). 208 * @exception SQLException If an error occurs. 209 * @see #execute(String) 210 * @see #execute(String, int) 211 * @see #execute(String, int[]) 212 * @see #execute(String, String[]) 213 */ 214 int getUpdateCount() throws SQLException; 215 216 /** 217 * This method advances the result set pointer to the next result set, 218 * which can then be retrieved using <code>getResultSet</code> 219 * 220 * @return <code>true</code> if there is another result set, 221 * <code>false</code> otherwise (for example, the next result is an 222 * update count). 223 * @exception SQLException If an error occurs. 224 * @see #execute(String) 225 * @see #execute(String, int) 226 * @see #execute(String, int[]) 227 * @see #execute(String, String[]) 228 */ 229 boolean getMoreResults() throws SQLException; 230 231 /** 232 * This method informs the driver which direction the result set will 233 * be accessed in. 234 * 235 * @param direction The direction the result set will be accessed in (?????) 236 * @exception SQLException If an error occurs. 237 */ 238 void setFetchDirection(int direction) throws SQLException; 239 240 /** 241 * This method returns the current direction that the driver thinks the 242 * result set will be accessed int. 243 * 244 * @return The direction the result set will be accessed in (????) 245 * @exception SQLException If an error occurs. 246 */ 247 int getFetchDirection() throws SQLException; 248 249 /** 250 * This method informs the driver how many rows it should fetch from the 251 * database at a time. 252 * 253 * @param numRows The number of rows the driver should fetch at a time 254 * to populate the result set. 255 * @exception SQLException If an error occurs. 256 */ 257 void setFetchSize(int numRows) throws SQLException; 258 259 /** 260 * This method returns the number of rows the driver believes should be 261 * fetched from the database at a time. 262 * 263 * @return The number of rows that will be fetched from the database at a time. 264 * @exception SQLException If an error occurs. 265 */ 266 int getFetchSize() throws SQLException; 267 268 /** 269 * This method returns the concurrency type of the result set for this 270 * statement. This will be one of the concurrency types defined in 271 * <code>ResultSet</code>. 272 * 273 * @return The concurrency type of the result set for this statement. 274 * @exception SQLException If an error occurs. 275 * @see ResultSet 276 */ 277 int getResultSetConcurrency() throws SQLException; 278 279 /** 280 * This method returns the result set type for this statement. This will 281 * be one of the result set types defined in <code>ResultSet</code>. 282 * 283 * @return The result set type for this statement. 284 * @exception SQLException If an error occurs. 285 * @see ResultSet 286 */ 287 int getResultSetType() throws SQLException; 288 289 /** 290 * This method adds a SQL statement to a SQL batch. A driver is not 291 * required to implement this method. 292 * 293 * @param sql The sql statement to add to the batch. 294 * @exception SQLException If an error occurs. 295 */ 296 void addBatch(String sql) throws SQLException; 297 298 /** 299 * This method clears out any SQL statements that have been populated in 300 * the current batch. A driver is not required to implement this method. 301 * 302 * @exception SQLException If an error occurs. 303 */ 304 void clearBatch() throws SQLException; 305 306 /** 307 * This method executes the SQL batch and returns an array of update 308 * counts - one for each SQL statement in the batch - ordered in the same 309 * order the statements were added to the batch. A driver is not required 310 * to implement this method. 311 * 312 * @return An array of update counts for this batch. 313 * @exception SQLException If an error occurs. 314 */ 315 int[] executeBatch() throws SQLException; 316 317 /** 318 * This method returns the <code>Connection</code> instance that was 319 * used to create this object. 320 * 321 * @return The connection used to create this object. 322 * @exception SQLException If an error occurs. 323 */ 324 Connection getConnection() throws SQLException; 325 326 /** 327 * @since 1.4 328 */ 329 boolean getMoreResults(int current) throws SQLException; 330 331 /** 332 * @since 1.4 333 */ 334 ResultSet getGeneratedKeys() throws SQLException; 335 336 /** 337 * @since 1.4 338 */ 339 int executeUpdate(String sql, int autoGeneratedKeys) 340 throws SQLException; 341 342 /** 343 * @since 1.4 344 */ 345 int executeUpdate(String sql, int[] columnIndexes) 346 throws SQLException; 347 348 /** 349 * @since 1.4 350 */ 351 int executeUpdate(String sql, String[] columnNames) 352 throws SQLException; 353 354 /** 355 * @since 1.4 356 */ 357 boolean execute(String sql, int autoGeneratedKeys) 358 throws SQLException; 359 360 /** 361 * @since 1.4 362 */ 363 boolean execute(String sql, int[] columnIndexes) throws SQLException; 364 365 /** 366 * @since 1.4 367 */ 368 boolean execute(String sql, String[] columnNames) 369 throws SQLException; 370 371 /** 372 * @since 1.4 373 */ 374 int getResultSetHoldability() throws SQLException; 375 }