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    }