libjava/java/sql/Statement.java

   1 /* Statement.java -- Interface for executing SQL statements.
   2    Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.sql;
  40
  41 /**
  42  * This interface provides a mechanism for executing SQL statements.
  43  *
  44  * @author Aaron M. Renn (arenn@urbanophile.com)
  45  */
  46 public interface Statement
  47 {
  48   public static final int CLOSE_CURRENT_RESULT = 1;
  49   public static final int KEEP_CURRENT_RESULT = 2;
  50   public static final int CLOSE_ALL_RESULTS = 3;
  51   public static final int SUCCESS_NO_INFO = -2;
  52   public static final int EXECUTE_FAILED = -3;
  53   public static final int RETURN_GENERATED_KEYS = 1;
  54   public static final int NO_GENERATED_KEYS = 2;
  55
  56   /**
  57    * This method executes the specified SQL SELECT statement and returns a
  58    * (possibly empty) <code>ResultSet</code> with the results of the query.
  59    *
  60    * @param sql The SQL statement to execute.
  61    * @return The result set of the SQL statement.
  62    * @exception SQLException If an error occurs.
  63    */
  64   public ResultSet executeQuery(String sql) throws SQLException;
  65
  66   /**
  67    * This method executes the specified SQL INSERT, UPDATE, or DELETE statement
  68    * and returns the number of rows affected, which may be 0.
  69    *
  70    * @param sql The SQL statement to execute.
  71    * @return The number of rows affected by the SQL statement.
  72    * @exception SQLException If an error occurs.
  73    */
  74   public int executeUpdate(String sql) throws SQLException;
  75
  76   /**
  77    * This method closes the statement and frees any associated resources.
  78    *
  79    * @exception SQLException If an error occurs.
  80    */
  81   public void close() throws SQLException;
  82
  83   /**
  84    * This method returns the maximum length of any column value in bytes.
  85    *
  86    * @return The maximum length of any column value in bytes.
  87    * @exception SQLException If an error occurs.
  88    */
  89   public int getMaxFieldSize() throws SQLException;
  90
  91   /**
  92    * This method sets the limit for the maximum length of any column in bytes.
  93    *
  94    * @param maxsize The new maximum length of any column in bytes.
  95    * @exception SQLException If an error occurs.
  96    */
  97   public void setMaxFieldSize(int max) throws SQLException;
  98
  99   /**
 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   public 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   public void setMaxRows(int max) 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   public void setEscapeProcessing(boolean enable) 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   public 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 timeout The new SQL statement timeout value.
 140    * @exception SQLException If an error occurs.
 141    */
 142   public 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   public 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   public 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   public 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   public 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   public 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
 196    */
 197   public ResultSet getResultSet() throws SQLException;
 198
 199   /**
 200    * This method returns the update count of the SQL statement that was
 201    * executed.  This should be called only once per executed SQL statement.
 202    *
 203    * @return The update count of the query, or -1 if there was no update
 204    *         count (for example, if the statement was a SELECT).
 205    * @exception SQLException If an error occurs.
 206    * @see execute
 207    */
 208   public int getUpdateCount() throws SQLException;
 209
 210   /**
 211    * This method advances the result set pointer to the next result set,
 212    * which can then be retrieved using <code>getResultSet</code>
 213    *
 214    * @return <code>true</code> if there is another result set,
 215    *         <code>false</code> otherwise (for example, the next result is an
 216    *         update count).
 217    * @exception SQLException If an error occurs.
 218    * @see execute
 219    */
 220   public boolean getMoreResults() throws SQLException;
 221
 222   /**
 223    * This method informs the driver which direction the result set will
 224    * be accessed in.
 225    *
 226    * @param direction The direction the result set will be accessed in (?????)
 227    * @exception SQLException If an error occurs.
 228    */
 229   public void setFetchDirection(int direction) throws SQLException;
 230
 231   /**
 232    * This method returns the current direction that the driver thinks the
 233    * result set will be accessed int.
 234    *
 235    * @return The direction the result set will be accessed in (????)
 236    * @exception SQLException If an error occurs.
 237    */
 238   public int getFetchDirection() throws SQLException;
 239
 240   /**
 241    * This method informs the driver how many rows it should fetch from the
 242    * database at a time.
 243    *
 244    * @param numrows The number of rows the driver should fetch at a time
 245    *        to populate the result set.
 246    * @exception SQLException If an error occurs.
 247    */
 248   public void setFetchSize(int rows) throws SQLException;
 249
 250   /**
 251    * This method returns the number of rows the driver believes should be
 252    * fetched from the database at a time.
 253    *
 254    * @return The number of rows that will be fetched from the database at a time.
 255    * @exception SQLException If an error occurs.
 256    */
 257   public int getFetchSize() throws SQLException;
 258
 259   /**
 260    * This method returns the concurrency type of the result set for this
 261    * statement. This will be one of the concurrency types defined in
 262    * <code>ResultSet</code>.
 263    *
 264    * @return The concurrency type of the result set for this statement.
 265    * @exception SQLException If an error occurs.
 266    * @see ResultSet
 267    */
 268   public int getResultSetConcurrency() throws SQLException;
 269
 270   /**
 271    * This method returns the result set type for this statement.  This will
 272    * be one of the result set types defined in <code>ResultSet</code>.
 273    *
 274    * @return The result set type for this statement.
 275    * @exception SQLException If an error occurs.
 276    * @see ResultSet
 277    */
 278   public int getResultSetType() throws SQLException;
 279
 280   /**
 281    * This method adds a SQL statement to a SQL batch.  A driver is not
 282    * required to implement this method.
 283    *
 284    * @param sql The sql statement to add to the batch.
 285    * @exception SQLException If an error occurs.
 286    */
 287   public void addBatch(String sql) throws SQLException;
 288
 289   /**
 290    * This method clears out any SQL statements that have been populated in
 291    * the current batch.  A driver is not required to implement this method.
 292    *
 293    * @exception SQLException If an error occurs.
 294    */
 295   public void clearBatch() throws SQLException;
 296
 297   /**
 298    * This method executes the SQL batch and returns an array of update
 299    * counts - one for each SQL statement in the batch - ordered in the same
 300    * order the statements were added to the batch.  A driver is not required
 301    * to implement this method.
 302    *
 303    * @return An array of update counts for this batch.
 304    * @exception SQLException If an error occurs.
 305    */
 306   public int[] executeBatch() throws SQLException;
 307
 308   /**
 309    * This method returns the <code>Connection</code> instance that was
 310    * used to create this object.
 311    *
 312    * @return The connection used to create this object.
 313    * @exception SQLException If an error occurs.
 314    */
 315   public Connection getConnection() throws SQLException;
 316
 317   /**
 318    * @since 1.4
 319    */
 320   public boolean getMoreResults(int current) throws SQLException;
 321
 322   /**
 323    * @since 1.4
 324    */
 325   public ResultSet getGeneratedKeys() throws SQLException;
 326
 327   /**
 328    * @since 1.4
 329    */
 330   public int executeUpdate(String sql, int autoGeneratedKeys)
 331     throws SQLException;
 332
 333   /**
 334    * @since 1.4
 335    */
 336   public int executeUpdate(String sql, int[] columnIndexes)
 337     throws SQLException;
 338
 339   /**
 340    * @since 1.4
 341    */
 342   public int executeUpdate(String sql, String[] columnNames)
 343     throws SQLException;
 344
 345   /**
 346    * @since 1.4
 347    */
 348   public boolean execute(String sql, int autoGeneratedKeys)
 349     throws SQLException;
 350
 351   /**
 352    * @since 1.4
 353    */
 354   public boolean execute(String sql, int[] columnIndexes) throws SQLException;
 355
 356   /**
 357    * @since 1.4
 358    */
 359   public boolean execute(String sql, String[] columnNames)
 360     throws SQLException;
 361
 362   /**
 363    * @since 1.4
 364    */
 365   public int getResultSetHoldability() throws SQLException;
 366 }