| Frames | No Frames |
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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 325: Connection getConnection() throws SQLException; 326: 327: /** 328: * @since 1.4 329: */ 330: boolean getMoreResults(int current) throws SQLException; 331: 332: /** 333: * @since 1.4 334: */ 335: ResultSet getGeneratedKeys() throws SQLException; 336: 337: /** 338: * @since 1.4 339: */ 340: int executeUpdate(String sql, int autoGeneratedKeys) 341: throws SQLException; 342: 343: /** 344: * @since 1.4 345: */ 346: int executeUpdate(String sql, int[] columnIndexes) 347: throws SQLException; 348: 349: /** 350: * @since 1.4 351: */ 352: int executeUpdate(String sql, String[] columnNames) 353: throws SQLException; 354: 355: /** 356: * @since 1.4 357: */ 358: boolean execute(String sql, int autoGeneratedKeys) 359: throws SQLException; 360: 361: /** 362: * @since 1.4 363: */ 364: boolean execute(String sql, int[] columnIndexes) throws SQLException; 365: 366: /** 367: * @since 1.4 368: */ 369: boolean execute(String sql, String[] columnNames) 370: throws SQLException; 371: 372: /** 373: * @since 1.4 374: */ 375: int getResultSetHoldability() throws SQLException; 376: }