001    /* Statement.java -- Interface for executing SQL statements.
002       Copyright (C) 1999, 2000, 2002, 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    
039    package java.sql;
040    
041    /**
042     * This interface provides a mechanism for executing SQL statements.
043     *
044     * @author Aaron M. Renn (arenn@urbanophile.com)
045     */
046    public interface Statement 
047    {
048      int CLOSE_CURRENT_RESULT = 1;
049      int KEEP_CURRENT_RESULT = 2;
050      int CLOSE_ALL_RESULTS = 3;
051      int SUCCESS_NO_INFO = -2;
052      int EXECUTE_FAILED = -3;
053      int RETURN_GENERATED_KEYS = 1;
054      int NO_GENERATED_KEYS = 2;
055    
056      /**
057       * This method executes the specified SQL SELECT statement and returns a
058       * (possibly empty) <code>ResultSet</code> with the results of the query.
059       *
060       * @param sql The SQL statement to execute.
061       * @return The result set of the SQL statement.
062       * @exception SQLException If an error occurs.
063       */
064      ResultSet executeQuery(String sql) throws SQLException;
065    
066      /**
067       * This method executes the specified SQL INSERT, UPDATE, or DELETE statement
068       * and returns the number of rows affected, which may be 0.
069       * 
070       * @param sql The SQL statement to execute.
071       * @return The number of rows affected by the SQL statement.
072       * @exception SQLException If an error occurs.
073       */
074      int executeUpdate(String sql) throws SQLException;
075    
076      /**
077       * This method closes the statement and frees any associated resources.
078       *
079       * @exception SQLException If an error occurs.
080       */
081      void close() throws SQLException;
082    
083      /**
084       * This method returns the maximum length of any column value in bytes.
085       *
086       * @return The maximum length of any column value in bytes.
087       * @exception SQLException If an error occurs.
088       */
089      int getMaxFieldSize() throws SQLException;
090    
091      /**
092       * This method sets the limit for the maximum length of any column in bytes.
093       *
094       * @param maxSize The new maximum length of any column in bytes.
095       * @exception SQLException If an error occurs.
096       */
097      void setMaxFieldSize(int maxSize) throws SQLException;
098    
099      /**
100       * This method returns the maximum possible number of rows in a result set.
101       *
102       * @return The maximum possible number of rows in a result set.
103       * @exception SQLException If an error occurs.
104       */
105      int getMaxRows() throws SQLException;
106    
107      /**
108       * This method sets the maximum number of rows that can be present in a
109       * result set.
110       *
111       * @param maxRows The maximum possible number of rows in a result set.
112       * @exception SQLException If an error occurs.
113       */
114      void setMaxRows(int maxRows) throws SQLException;
115    
116      /**
117       * This method sets the local escape processing mode on or off.  The
118       * default value is on.
119       *
120       * @param escape <code>true</code> to enable local escape processing, 
121       *               <code>false</code> to disable it.
122       * @exception SQLException If an error occurs.
123       */
124      void setEscapeProcessing(boolean escape) throws SQLException;
125    
126      /**
127       * The method returns the number of seconds a statement may be in process
128       * before timing out.  A value of 0 means there is no timeout.
129       *
130       * @return The SQL statement timeout in seconds.
131       * @exception SQLException If an error occurs.
132       */
133      int getQueryTimeout() throws SQLException;
134    
135      /**
136       * This method sets the number of seconds a statement may be in process
137       * before timing out.  A value of 0 means there is no timeout.
138       *
139       * @param seconds The new SQL statement timeout value.
140       * @exception SQLException If an error occurs.
141       */
142      void setQueryTimeout(int seconds) throws SQLException;
143    
144      /**
145       * This method cancels an outstanding statement, if the database supports
146       * that operation.
147       *
148       * @exception SQLException If an error occurs.
149       */
150      void cancel() throws SQLException;
151    
152      /**
153       * This method returns the first SQL warning attached to this statement.
154       * Subsequent warnings will be chained to this one.
155       *
156       * @return The first SQL warning for this statement.
157       * @exception SQLException If an error occurs.
158       */
159      SQLWarning getWarnings() throws SQLException;
160    
161      /**
162       * This method clears any SQL warnings that have been attached to this
163       * statement.
164       *
165       * @exception SQLException If an error occurs.
166       */
167      void clearWarnings() throws SQLException;
168    
169      /**
170       * This method sets the cursor name that will be used by the result set.
171       *
172       * @param name The cursor name to use for this statement.
173       * @exception SQLException If an error occurs.
174       */
175      void setCursorName(String name) throws SQLException;
176    
177      /**
178       * This method executes an arbitrary SQL statement of any time.  The
179       * methods <code>getResultSet</code>, <code>getMoreResults</code> and
180       * <code>getUpdateCount</code> retrieve the results.
181       *
182       * @return <code>true</code> if a result set was returned, <code>false</code>
183       *         if an update count was returned.
184       * @exception SQLException If an error occurs.
185       */
186      boolean execute(String sql) throws SQLException;
187    
188      /**
189       * This method returns the result set of the SQL statement that was
190       * executed.  This should be called only once per result set returned.
191       *
192       * @return The result set of the query, or <code>null</code> if there was
193       *         no result set (for example, if the statement was an UPDATE).
194       * @exception SQLException If an error occurs.
195       * @see #execute(String)
196       * @see #execute(String, int)
197       * @see #execute(String, int[])
198       * @see #execute(String, String[])
199       */
200      ResultSet getResultSet() throws SQLException;
201    
202      /**
203       * This method returns the update count of the SQL statement that was
204       * executed.  This should be called only once per executed SQL statement.
205       *
206       * @return The update count of the query, or -1 if there was no update
207       *         count (for example, if the statement was a SELECT).
208       * @exception SQLException If an error occurs.
209       * @see #execute(String)
210       * @see #execute(String, int)
211       * @see #execute(String, int[])
212       * @see #execute(String, String[])
213       */
214      int getUpdateCount() throws SQLException;
215    
216      /**
217       * This method advances the result set pointer to the next result set, 
218       * which can then be retrieved using <code>getResultSet</code>
219       *
220       * @return <code>true</code> if there is another result set, 
221       *         <code>false</code> otherwise (for example, the next result is an
222       *         update count).
223       * @exception SQLException If an error occurs.
224       * @see #execute(String)
225       * @see #execute(String, int)
226       * @see #execute(String, int[])
227       * @see #execute(String, String[])
228       */
229      boolean getMoreResults() throws SQLException;
230    
231      /**
232       * This method informs the driver which direction the result set will
233       * be accessed in.
234       *
235       * @param direction The direction the result set will be accessed in (?????)
236       * @exception SQLException If an error occurs.
237       */
238      void setFetchDirection(int direction) throws SQLException;
239    
240      /**
241       * This method returns the current direction that the driver thinks the
242       * result set will be accessed int.
243       *
244       * @return The direction the result set will be accessed in (????)
245       * @exception SQLException If an error occurs.
246       */
247      int getFetchDirection() throws SQLException;
248    
249      /**
250       * This method informs the driver how many rows it should fetch from the
251       * database at a time.
252       *
253       * @param numRows The number of rows the driver should fetch at a time
254       *                to populate the result set.
255       * @exception SQLException If an error occurs.
256       */
257      void setFetchSize(int numRows) throws SQLException;
258    
259      /**
260       * This method returns the number of rows the driver believes should be
261       * fetched from the database at a time.
262       *
263       * @return The number of rows that will be fetched from the database at a time.
264       * @exception SQLException If an error occurs.
265       */
266      int getFetchSize() throws SQLException;
267    
268      /**
269       * This method returns the concurrency type of the result set for this
270       * statement. This will be one of the concurrency types defined in
271       * <code>ResultSet</code>.
272       *
273       * @return The concurrency type of the result set for this statement.
274       * @exception SQLException If an error occurs.
275       * @see ResultSet
276       */
277      int getResultSetConcurrency() throws SQLException;
278    
279      /**
280       * This method returns the result set type for this statement.  This will
281       * be one of the result set types defined in <code>ResultSet</code>.
282       *
283       * @return The result set type for this statement.
284       * @exception SQLException If an error occurs.
285       * @see ResultSet
286       */
287      int getResultSetType() throws SQLException;
288    
289      /**
290       * This method adds a SQL statement to a SQL batch.  A driver is not
291       * required to implement this method.
292       *
293       * @param sql The sql statement to add to the batch.
294       * @exception SQLException If an error occurs.
295       */
296      void addBatch(String sql) throws SQLException;
297    
298      /**
299       * This method clears out any SQL statements that have been populated in
300       * the current batch.  A driver is not required to implement this method.
301       *
302       * @exception SQLException If an error occurs.
303       */
304      void clearBatch() throws SQLException;
305    
306      /**
307       * This method executes the SQL batch and returns an array of update
308       * counts - one for each SQL statement in the batch - ordered in the same
309       * order the statements were added to the batch.  A driver is not required
310       * to implement this method.
311       *
312       * @return An array of update counts for this batch.
313       * @exception SQLException If an error occurs.
314       */
315      int[] executeBatch() throws SQLException;
316    
317      /**
318       * This method returns the <code>Connection</code> instance that was
319       * used to create this object.
320       *
321       * @return The connection used to create this object.
322       * @exception SQLException If an error occurs.
323       */
324      Connection getConnection() throws SQLException;
325    
326      /**
327       * @since 1.4
328       */
329      boolean getMoreResults(int current) throws SQLException;
330    
331      /**
332       * @since 1.4
333       */
334      ResultSet getGeneratedKeys() throws SQLException;
335    
336      /**
337       * @since 1.4
338       */
339      int executeUpdate(String sql, int autoGeneratedKeys)
340        throws SQLException;
341    
342      /**
343       * @since 1.4
344       */
345      int executeUpdate(String sql, int[] columnIndexes)
346        throws SQLException;
347    
348      /**
349       * @since 1.4
350       */
351      int executeUpdate(String sql, String[] columnNames)
352        throws SQLException;
353    
354      /**
355       * @since 1.4
356       */
357      boolean execute(String sql, int autoGeneratedKeys)
358        throws SQLException;
359    
360      /**
361       * @since 1.4
362       */
363      boolean execute(String sql, int[] columnIndexes) throws SQLException;
364    
365      /**
366       * @since 1.4
367       */
368      boolean execute(String sql, String[] columnNames)
369        throws SQLException;
370    
371      /**
372       * @since 1.4
373       */
374      int getResultSetHoldability() throws SQLException;
375    }