001 /* PreparedStatement.java -- Interface for pre-compiled statements. 002 Copyright (C) 1999, 2000, 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 package java.sql; 039 040 import java.io.InputStream; 041 import java.io.Reader; 042 import java.math.BigDecimal; 043 import java.net.URL; 044 import java.util.Calendar; 045 046 /** 047 * This interface provides a mechanism for executing pre-compiled 048 * statements. This provides greater efficiency when calling the same 049 * statement multiple times. Parameters are allowed in a statement, 050 * providings for maximum reusability. 051 * 052 * <p> Note that in this class parameter indices start at 1, not 0.</p> 053 * 054 * @author Aaron M. Renn (arenn@urbanophile.com) 055 */ 056 public interface PreparedStatement extends Statement 057 { 058 /** 059 * This method executes a prepared SQL query and returns its ResultSet. 060 * 061 * @return The ResultSet of the SQL statement. 062 * @exception SQLException If an error occurs. 063 */ 064 ResultSet executeQuery() throws SQLException; 065 066 /** 067 * This method executes an SQL INSERT, UPDATE or DELETE statement. SQL 068 * statements that return nothing such as SQL DDL statements can be executed. 069 * 070 * @return The result is either the row count for INSERT, UPDATE or DELETE 071 * statements; or 0 for SQL statements that return nothing. 072 * @exception SQLException If an error occurs. 073 */ 074 int executeUpdate() throws SQLException; 075 076 /** 077 * This method populates the specified parameter with a SQL NULL value 078 * for the specified type. 079 * 080 * @param index The index of the parameter to set. 081 * @param sqlType The SQL type identifier of the parameter from 082 * <code>Types</code> 083 * 084 * @exception SQLException If an error occurs. 085 */ 086 void setNull(int index, int sqlType) throws SQLException; 087 088 /** 089 * This method sets the specified parameter from the given Java 090 * <code>boolean</code> value. 091 * 092 * @param index The index of the parameter value to set. 093 * @param value The value of the parameter. 094 * @exception SQLException If an error occurs. 095 */ 096 void setBoolean(int index, boolean value) throws SQLException; 097 098 /** 099 * 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 }