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 }