| Frames | No Frames |
1: /* PreparedStatement.java -- Interface for pre-compiled statements. 2: Copyright (C) 1999, 2000, 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: package java.sql; 39: 40: import java.io.InputStream; 41: import java.io.Reader; 42: import java.math.BigDecimal; 43: import java.net.URL; 44: import java.util.Calendar; 45: 46: /** 47: * This interface provides a mechanism for executing pre-compiled 48: * statements. This provides greater efficiency when calling the same 49: * statement multiple times. Parameters are allowed in a statement, 50: * providings for maximum reusability. 51: * 52: * <p> Note that in this class parameter indices start at 1, not 0.</p> 53: * 54: * @author Aaron M. Renn (arenn@urbanophile.com) 55: */ 56: public interface PreparedStatement extends Statement 57: { 58: /** 59: * This method executes a prepared SQL query and returns its ResultSet. 60: * 61: * @return The ResultSet of the SQL statement. 62: * @exception SQLException If an error occurs. 63: */ 64: ResultSet executeQuery() throws SQLException; 65: 66: /** 67: * This method executes an SQL INSERT, UPDATE or DELETE statement. SQL 68: * statements that return nothing such as SQL DDL statements can be executed. 69: * 70: * @return The result is either the row count for INSERT, UPDATE or DELETE 71: * statements; or 0 for SQL statements that return nothing. 72: * @exception SQLException If an error occurs. 73: */ 74: int executeUpdate() throws SQLException; 75: 76: /** 77: * This method populates the specified parameter with a SQL NULL value 78: * for the specified type. 79: * 80: * @param index The index of the parameter to set. 81: * @param sqlType The SQL type identifier of the parameter from 82: * <code>Types</code> 83: * 84: * @exception SQLException If an error occurs. 85: */ 86: void setNull(int index, int sqlType) throws SQLException; 87: 88: /** 89: * This method sets the specified parameter from the given Java 90: * <code>boolean</code> value. 91: * 92: * @param index The index of the parameter value to set. 93: * @param value The value of the parameter. 94: * @exception SQLException If an error occurs. 95: */ 96: void setBoolean(int index, boolean value) throws SQLException; 97: 98: /** 99: * This method sets the specified parameter from the given Java 100: * <code>byte</code> value. 101: * 102: * @param index The index of the parameter value to set. 103: * @param value The value of the parameter. 104: * @exception SQLException If an error occurs. 105: */ 106: void setByte(int index, byte value) throws SQLException; 107: 108: /** 109: * This method sets the specified parameter from the given Java 110: * <code>short</code> value. 111: * 112: * @param index The index of the parameter value to set. 113: * @param value The value of the parameter. 114: * @exception SQLException If an error occurs. 115: */ 116: void setShort(int index, short value) throws SQLException; 117: 118: /** 119: * This method sets the specified parameter from the given Java 120: * <code>int</code> value. 121: * 122: * @param index The index of the parameter value to set. 123: * @param value The value of the parameter. 124: * @exception SQLException If an error occurs. 125: */ 126: void setInt(int index, int value) throws SQLException; 127: 128: /** 129: * This method sets the specified parameter from the given Java 130: * <code>long</code> value. 131: * 132: * @param index The index of the parameter value to set. 133: * @param value The value of the parameter. 134: * @exception SQLException If an error occurs. 135: */ 136: void setLong(int index, long value) throws SQLException; 137: 138: /** 139: * This method sets the specified parameter from the given Java 140: * <code>float</code> value. 141: * 142: * @param index The index of the parameter value to set. 143: * @param value The value of the parameter. 144: * @exception SQLException If an error occurs. 145: */ 146: void setFloat(int index, float value) throws SQLException; 147: 148: /** 149: * This method sets the specified parameter from the given Java 150: * <code>double</code> value. 151: * 152: * @param index The index of the parameter value to set. 153: * @param value The value of the parameter. 154: * @exception SQLException If an error occurs. 155: */ 156: void setDouble(int index, double value) throws SQLException; 157: 158: /** 159: * This method sets the specified parameter from the given Java 160: * <code>java.math.BigDecimal</code> value. 161: * 162: * @param index The index of the parameter value to set. 163: * @param value The value of the parameter. 164: * @exception SQLException If an error occurs. 165: */ 166: void setBigDecimal(int index, BigDecimal value) throws 167: SQLException; 168: 169: /** 170: * This method sets the specified parameter from the given Java 171: * <code>String</code> value. 172: * 173: * @param index The index of the parameter value to set. 174: * @param value The value of the parameter. 175: * @exception SQLException If an error occurs. 176: */ 177: void setString(int index, String value) throws SQLException; 178: 179: /** 180: * This method sets the specified parameter from the given Java 181: * <code>byte</code> array value. 182: * 183: * @param index The index of the parameter value to set. 184: * @param value The value of the parameter. 185: * @exception SQLException If an error occurs. 186: */ 187: void setBytes(int index, byte[] value) throws SQLException; 188: 189: /** 190: * This method sets the specified parameter from the given Java 191: * <code>java.sql.Date</code> value. 192: * 193: * @param index The index of the parameter value to set. 194: * @param value The value of the parameter. 195: * @exception SQLException If an error occurs. 196: */ 197: void setDate(int index, Date value) throws SQLException; 198: 199: /** 200: * This method sets the specified parameter from the given Java 201: * <code>java.sql.Time</code> value. 202: * 203: * @param index The index of the parameter value to set. 204: * @param value The value of the parameter. 205: * @exception SQLException If an error occurs. 206: */ 207: void setTime(int index, Time value) throws SQLException; 208: 209: /** 210: * This method sets the specified parameter from the given Java 211: * <code>java.sql.Timestamp</code> value. 212: * 213: * @param index The index of the parameter value to set. 214: * @param value The value of the parameter. 215: * @exception SQLException If an error occurs. 216: */ 217: void setTimestamp(int index, Timestamp value) 218: throws SQLException; 219: 220: /** 221: * This method sets the specified parameter from the given Java 222: * ASCII <code>InputStream</code> value. 223: * 224: * @param index The index of the parameter value to set. 225: * @param stream The stream from which the parameter value is read. 226: * @param count The number of bytes in the stream. 227: * @exception SQLException If an error occurs. 228: */ 229: void setAsciiStream(int index, InputStream stream, int count) 230: throws SQLException; 231: 232: /** 233: * This method sets the specified parameter from the given Java 234: * Unicode UTF-8 <code>InputStream</code> value. 235: * 236: * @param index The index of the parameter value to set. 237: * @param stream The stream from which the parameter value is read. 238: * @param count The number of bytes in the stream. 239: * @exception SQLException If an error occurs. 240: * @deprecated 241: */ 242: void setUnicodeStream(int index, InputStream stream, int count) 243: throws SQLException; 244: 245: /** 246: * This method sets the specified parameter from the given Java 247: * binary <code>InputStream</code> value. 248: * 249: * @param index The index of the parameter value to set. 250: * @param stream The stream from which the parameter value is read. 251: * @param count The number of bytes in the stream. 252: * @exception SQLException If an error occurs. 253: */ 254: void setBinaryStream(int index, InputStream stream, int count) 255: throws SQLException; 256: 257: /** 258: * This method clears all of the input parameter that have been 259: * set on this statement. 260: * 261: * @exception SQLException If an error occurs. 262: */ 263: void clearParameters() throws SQLException; 264: 265: /** 266: * This method sets the specified parameter from the given Java 267: * <code>Object</code> value. The specified SQL object type will be used. 268: * 269: * @param index The index of the parameter value to set. 270: * @param value The value of the parameter. 271: * @param sqlType The SQL type to use for the parameter, from 272: * <code>Types</code> 273: * @param scale The scale of the value, for numeric values only. 274: * @exception SQLException If an error occurs. 275: * @see Types 276: */ 277: void setObject(int index, Object value, int sqlType, int scale) 278: throws SQLException; 279: 280: /** 281: * This method sets the specified parameter from the given Java 282: * <code>Object</code> value. The specified SQL object type will be used. 283: * 284: * @param index The index of the parameter value to set. 285: * @param value The value of the parameter. 286: * @param sqlType The SQL type to use for the parameter, from 287: * <code>Types</code> 288: * @exception SQLException If an error occurs. 289: * @see Types 290: */ 291: void setObject(int index, Object value, int sqlType) 292: throws SQLException; 293: 294: /** 295: * This method sets the specified parameter from the given Java 296: * <code>Object</code> value. The default object type to SQL type mapping 297: * will be used. 298: * 299: * @param index The index of the parameter value to set. 300: * @param value The value of the parameter. 301: * @exception SQLException If an error occurs. 302: */ 303: void setObject(int index, Object value) throws SQLException; 304: 305: /** 306: * This method executes a prepared SQL query. 307: * Some prepared statements return multiple results; the execute method 308: * handles these complex statements as well as the simpler form of 309: * statements handled by executeQuery and executeUpdate. 310: * 311: * @return The result of the SQL statement. 312: * @exception SQLException If an error occurs. 313: */ 314: boolean execute() throws SQLException; 315: 316: /** 317: * This method adds a set of parameters to the batch for JDBC 2.0. 318: * @exception SQLException If an error occurs. 319: */ 320: void addBatch() throws SQLException; 321: 322: /** 323: * This method sets the specified parameter from the given Java 324: * character <code>Reader</code> value. 325: * 326: * @param index The index of the parameter value to set. 327: * @param reader The reader from which the parameter value is read. 328: * @param count The number of characters in the stream. 329: * @exception SQLException If an error occurs. 330: */ 331: void setCharacterStream(int index, Reader reader, int count) 332: throws SQLException; 333: 334: /** 335: * This method sets the specified parameter from the given Java 336: * <code>Ref</code> value. The default object type to SQL type mapping 337: * will be used. 338: * 339: * @param index The index of the parameter value to set. 340: * @param value The <code>Ref</code> used to set the value of the parameter. 341: * @exception SQLException If an error occurs. 342: */ 343: void setRef(int index, Ref value) throws SQLException; 344: 345: /** 346: * This method sets the specified parameter from the given Java 347: * <code>Blob</code> value. The default object type to SQL type mapping 348: * will be used. 349: * 350: * @param index The index of the parameter value to set. 351: * @param value The <code>Blob</code> used to set the 352: * value of the parameter. 353: * @exception SQLException If an error occurs. 354: */ 355: void setBlob(int index, Blob value) throws SQLException; 356: 357: /** 358: * This method sets the specified parameter from the given Java 359: * <code>Clob</code> value. The default object type to SQL type mapping 360: * will be used. 361: * 362: * @param index The index of the parameter value to set. 363: * @param value The <code>Clob</code> used to set the 364: * value of the parameter. 365: * @exception SQLException If an error occurs. 366: */ 367: void setClob(int index, Clob value) throws SQLException; 368: 369: /** 370: * This method sets the specified parameter from the given Java 371: * <code>Array</code> value. The default object type to SQL type mapping 372: * will be used. 373: * 374: * @param index The index of the parameter value to set. 375: * @param value The value of the parameter. 376: * @exception SQLException If an error occurs. 377: */ 378: void setArray(int index, Array value) throws SQLException; 379: 380: /** 381: * This method returns meta data for the result set from this statement. 382: * 383: * @return Meta data for the result set from this statement. 384: * @exception SQLException If an error occurs. 385: */ 386: ResultSetMetaData getMetaData() throws SQLException; 387: 388: /** 389: * This method sets the specified parameter from the given Java 390: * <code>java.sql.Date</code> value. 391: * 392: * @param index The index of the parameter value to set. 393: * @param value The value of the parameter. 394: * @param cal The <code>Calendar</code> to use for timezone and locale. 395: * @exception SQLException If an error occurs. 396: */ 397: void setDate(int index, Date value, Calendar cal) 398: throws SQLException; 399: 400: /** 401: * This method sets the specified parameter from the given Java 402: * <code>java.sql.Time</code> value. 403: * 404: * @param index The index of the parameter value to set. 405: * @param value The value of the parameter. 406: * @param cal The <code>Calendar</code> to use for timezone and locale. 407: * @exception SQLException If an error occurs. 408: */ 409: void setTime(int index, Time value, Calendar cal) 410: throws SQLException; 411: 412: /** 413: * This method sets the specified parameter from the given Java 414: * <code>java.sql.Timestamp</code> value. 415: * 416: * @param index The index of the parameter value to set. 417: * @param value The value of the parameter. 418: * @param cal The <code>Calendar</code> to use for timezone and locale. 419: * @exception SQLException If an error occurs. 420: */ 421: void setTimestamp(int index, Timestamp value, Calendar cal) 422: throws SQLException; 423: 424: /** 425: * This method populates the specified parameter with a SQL NULL value 426: * for the specified type. 427: * 428: * @param index The index of the parameter to set. 429: * @param sqlType The SQL type identifier of the parameter from 430: * <code>Types</code> 431: * @param typeName The name of the data type, for user defined types. 432: * @exception SQLException If an error occurs. 433: */ 434: void setNull(int index, int sqlType, String typeName) 435: throws SQLException; 436: 437: /** 438: * This method sets the specified parameter from the given Java 439: * <code>java.net.URL</code> value. 440: * 441: * @param index The index of the parameter to set. 442: * @param value The value of the parameter. 443: * @exception SQLException If an error occurs. 444: * @since 1.4 445: */ 446: void setURL(int index, URL value) throws SQLException; 447: 448: /** 449: * Returns information about the parameters set on this 450: * <code>PreparedStatement</code> (see {@link ParameterMetaData} for a 451: * detailed description of the provided information). 452: * 453: * @return Meta data for the parameters of this statement. 454: * @see ParameterMetaData 455: * @since 1.4 456: */ 457: ParameterMetaData getParameterMetaData() throws SQLException; 458: }