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