001/* PreparedStatement.java -- Interface for pre-compiled statements.
002   Copyright (C) 1999, 2000, 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010 
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package java.sql;
039
040import java.io.InputStream;
041import java.io.Reader;
042import java.math.BigDecimal;
043import java.net.URL;
044import 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 */
056public 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}