libjava/java/sql/PreparedStatement.java

   1 /* PreparedStatement.java -- Interface for pre-compiled statements.
   2    Copyright (C) 1999, 2000 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 package java.sql;
  39
  40 import java.io.InputStream;
  41 import java.io.Reader;
  42 import java.math.BigDecimal;
  43 import java.net.URL;
  44 import java.util.Calendar;
  45
  46 /**
  47  * This interface provides a mechanism for executing pre-compiled
  48  * statements.  This provides greater efficiency when calling the same
  49  * statement multiple times.  Parameters are allowed in a statement,
  50  * providings for maximum reusability.
  51  *
  52  * @author Aaron M. Renn (arenn@urbanophile.com)
  53  */
  54 public interface PreparedStatement extends Statement
  55 {
  56   /**
  57    * This method executes a prepared SQL query and returns its ResultSet.
  58    *
  59    * @return The ResultSet of the SQL statement.
  60    * @exception SQLException If an error occurs.
  61    */
  62   public ResultSet executeQuery() throws SQLException;
  63
  64   /**
  65    * This method executes an SQL INSERT, UPDATE or DELETE statement.  SQL
  66    * statements that return nothing such as SQL DDL statements can be executed.
  67    *
  68    * @return The result is either the row count for INSERT, UPDATE or DELETE
  69    *         statements; or 0 for SQL statements that return nothing.
  70    * @exception SQLException If an error occurs.
  71    */
  72   public int executeUpdate() throws SQLException;
  73
  74   /**
  75    * This method populates the specified parameter with a SQL NULL value
  76    * for the specified type.
  77    *
  78    * @param index The index of the parameter to set.
  79    * @param type The SQL type identifier of the parameter from <code>Types</code>
  80    *
  81    * @exception SQLException If an error occurs.
  82    */
  83   public void setNull(int parameterIndex, int sqlType) throws SQLException;
  84
  85   /**
  86    * This method sets the specified parameter from the given Java
  87    * <code>boolean</code> value.
  88    *
  89    * @param index The index of the parameter value to set.
  90    * @param value The value of the parameter.
  91    * @exception SQLException If an error occurs.
  92    */
  93   public void setBoolean(int parameterIndex, boolean x) throws SQLException;
  94
  95   /**
  96    * This method sets the specified parameter from the given Java
  97    * <code>byte</code> value.
  98    *
  99    * @param index The index of the parameter value to set.
 100    * @param value The value of the parameter.
 101    * @exception SQLException If an error occurs.
 102    */
 103   public void setByte(int parameterIndex, byte x) throws SQLException;
 104
 105   /**
 106    * This method sets the specified parameter from the given Java
 107    * <code>short</code> value.
 108    *
 109    * @param index The index of the parameter value to set.
 110    * @param value The value of the parameter.
 111    * @exception SQLException If an error occurs.
 112    */
 113   public void setShort(int parameterIndex, short x) throws SQLException;
 114
 115   /**
 116    * This method sets the specified parameter from the given Java
 117    * <code>int</code> value.
 118    *
 119    * @param index The index of the parameter value to set.
 120    * @param value The value of the parameter.
 121    * @exception SQLException If an error occurs.
 122    */
 123   public void setInt(int parameterIndex, int x) throws SQLException;
 124
 125   /**
 126    * This method sets the specified parameter from the given Java
 127    * <code>long</code> value.
 128    *
 129    * @param index The index of the parameter value to set.
 130    * @param value The value of the parameter.
 131    * @exception SQLException If an error occurs.
 132    */
 133   public void setLong(int parameterIndex, long x) throws SQLException;
 134
 135   /**
 136    * This method sets the specified parameter from the given Java
 137    * <code>float</code> value.
 138    *
 139    * @param index The index of the parameter value to set.
 140    * @param value The value of the parameter.
 141    * @exception SQLException If an error occurs.
 142    */
 143   public void setFloat(int parameterIndex, float x) throws SQLException;
 144
 145   /**
 146    * This method sets the specified parameter from the given Java
 147    * <code>double</code> value.
 148    *
 149    * @param index The index of the parameter value to set.
 150    * @param value The value of the parameter.
 151    * @exception SQLException If an error occurs.
 152    */
 153   public void setDouble(int parameterIndex, double x) throws SQLException;
 154
 155   /**
 156    * This method sets the specified parameter from the given Java
 157    * <code>java.math.BigDecimal</code> value.
 158    *
 159    * @param index The index of the parameter value to set.
 160    * @param value The value of the parameter.
 161    * @exception SQLException If an error occurs.
 162    */
 163   public void setBigDecimal(int parameterIndex, BigDecimal x) throws
 164       SQLException;
 165
 166   /**
 167    * This method sets the specified parameter from the given Java
 168    * <code>String</code> value.
 169    *
 170    * @param index The index of the parameter value to set.
 171    * @param value The value of the parameter.
 172    * @exception SQLException If an error occurs.
 173    */
 174   public void setString(int parameterIndex, String x) throws SQLException;
 175
 176   /**
 177    * This method sets the specified parameter from the given Java
 178    * <code>byte</code> array value.
 179    *
 180    * @param index The index of the parameter value to set.
 181    * @param value The value of the parameter.
 182    * @exception SQLException If an error occurs.
 183    */
 184   public void setBytes(int parameterIndex, byte[] x) throws SQLException;
 185
 186   /**
 187    * This method sets the specified parameter from the given Java
 188    * <code>java.sql.Date</code> value.
 189    *
 190    * @param index The index of the parameter value to set.
 191    * @param value The value of the parameter.
 192    * @exception SQLException If an error occurs.
 193    */
 194   public void setDate(int parameterIndex, Date x) throws SQLException;
 195
 196   /**
 197    * This method sets the specified parameter from the given Java
 198    * <code>java.sql.Time</code> value.
 199    *
 200    * @param index The index of the parameter value to set.
 201    * @param value The value of the parameter.
 202    * @exception SQLException If an error occurs.
 203    */
 204   public void setTime(int parameterIndex, Time x) throws SQLException;
 205
 206   /**
 207    * This method sets the specified parameter from the given Java
 208    * <code>java.sql.Timestamp</code> value.
 209    *
 210    * @param index The index of the parameter value to set.
 211    * @param value The value of the parameter.
 212    * @exception SQLException If an error occurs.
 213    */
 214   public void setTimestamp(int parameterIndex, Timestamp x)
 215     throws SQLException;
 216
 217   /**
 218    * This method sets the specified parameter from the given Java
 219    * ASCII <code>InputStream</code> value.
 220    *
 221    * @param index The index of the parameter value to set.
 222    * @param value The value of the parameter.
 223    * @param length The number of bytes in the stream.
 224    * @exception SQLException If an error occurs.
 225    */
 226   public void setAsciiStream(int parameterIndex, InputStream x, int length)
 227     throws SQLException;
 228
 229   /**
 230    * This method sets the specified parameter from the given Java
 231    * Unicode UTF-8 <code>InputStream</code> value.
 232    *
 233    * @param index The index of the parameter value to set.
 234    * @param value The value of the parameter.
 235    * @param length The number of bytes in the stream.
 236    * @exception SQLException If an error occurs.
 237    * @deprecated
 238    */
 239   public void setUnicodeStream(int parameterIndex, InputStream x, int length)
 240     throws SQLException;
 241
 242   /**
 243    * This method sets the specified parameter from the given Java
 244    * binary <code>InputStream</code> value.
 245    *
 246    * @param index The index of the parameter value to set.
 247    * @param value The value of the parameter.
 248    * @param length The number of bytes in the stream.
 249    * @exception SQLException If an error occurs.
 250    */
 251   public void setBinaryStream(int parameterIndex, InputStream x, int length)
 252     throws SQLException;
 253
 254   /**
 255    * This method clears all of the input parameter that have been
 256    * set on this statement.
 257    *
 258    * @exception SQLException If an error occurs.
 259    */
 260   public void clearParameters() throws SQLException;
 261
 262   /**
 263    * This method sets the specified parameter from the given Java
 264    * <code>Object</code> value.  The specified SQL object type will be used.
 265    *
 266    * @param index The index of the parameter value to set.
 267    * @param value The value of the parameter.
 268    * @param type The SQL type to use for the parameter, from <code>Types</code>
 269    * @param scale The scale of the value, for numeric values only.
 270    * @exception SQLException If an error occurs.
 271    * @see Types
 272    */
 273   public void setObject(int parameterIndex, Object x, int targetSqlType,
 274     int scale) throws SQLException;
 275
 276   /**
 277    * This method sets the specified parameter from the given Java
 278    * <code>Object</code> value.  The specified SQL object type will be used.
 279    *
 280    * @param index The index of the parameter value to set.
 281    * @param value The value of the parameter.
 282    * @param type The SQL type to use for the parameter, from <code>Types</code>
 283    * @exception SQLException If an error occurs.
 284    * @see Types
 285    */
 286   public void setObject(int parameterIndex, Object x, int targetSqlType)
 287     throws SQLException;
 288
 289   /**
 290    * This method sets the specified parameter from the given Java
 291    * <code>Object</code> value.  The default object type to SQL type mapping
 292    * will be used.
 293    *
 294    * @param index The index of the parameter value to set.
 295    * @param value The value of the parameter.
 296    * @exception SQLException If an error occurs.
 297    */
 298   public void setObject(int parameterIndex, Object x) throws SQLException;
 299
 300   /**
 301    * This method executes a prepared SQL query.
 302    * Some prepared statements return multiple results; the execute method
 303    * handles these complex statements as well as the simpler form of
 304    * statements handled by executeQuery and executeUpdate.
 305    *
 306    * @return The result of the SQL statement.
 307    * @exception SQLException If an error occurs.
 308    */
 309   public boolean execute() throws SQLException;
 310
 311   /**
 312    * This method adds a set of parameters to the batch for JDBC 2.0.
 313    * @exception SQLException If an error occurs.
 314    */
 315   public void addBatch() throws SQLException;
 316
 317   /**
 318    * This method sets the specified parameter from the given Java
 319    * character <code>Reader</code> value.
 320    *
 321    * @param index The index of the parameter value to set.
 322    * @param value The value of the parameter.
 323    * @param length The number of bytes in the stream.
 324    * @exception SQLException If an error occurs.
 325    */
 326   public void setCharacterStream(int parameterIndex, Reader reader,
 327     int length) throws SQLException;
 328
 329   /**
 330    * This method sets the specified parameter from the given Java
 331    * <code>Ref</code> value.  The default object type to SQL type mapping
 332    * will be used.
 333    *
 334    * @param index The index of the parameter value to set.
 335    * @param value The value of the parameter.
 336    * @exception SQLException If an error occurs.
 337    */
 338   public void setRef(int i, Ref x) throws SQLException;
 339
 340   /**
 341    * This method sets the specified parameter from the given Java
 342    * <code>Blob</code> value.  The default object type to SQL type mapping
 343    * will be used.
 344    *
 345    * @param index The index of the parameter value to set.
 346    * @param value The value of the parameter.
 347    * @exception SQLException If an error occurs.
 348    */
 349   public void setBlob(int i, Blob x) throws SQLException;
 350
 351   /**
 352    * This method sets the specified parameter from the given Java
 353    * <code>Clob</code> value.  The default object type to SQL type mapping
 354    * will be used.
 355    *
 356    * @param index The index of the parameter value to set.
 357    * @param value The value of the parameter.
 358    * @exception SQLException If an error occurs.
 359    */
 360   public void setClob(int i, Clob x) throws SQLException;
 361
 362   /**
 363    * This method sets the specified parameter from the given Java
 364    * <code>Array</code> value.  The default object type to SQL type mapping
 365    * will be used.
 366    *
 367    * @param index The index of the parameter value to set.
 368    * @param value The value of the parameter.
 369    * @exception SQLException If an error occurs.
 370    */
 371   public void setArray(int i, Array x) throws SQLException;
 372
 373   /**
 374    * This method returns meta data for the result set from this statement.
 375    *
 376    * @return Meta data for the result set from this statement.
 377    * @exception SQLException If an error occurs.
 378    */
 379   public ResultSetMetaData getMetaData() throws SQLException;
 380
 381   /**
 382    * This method sets the specified parameter from the given Java
 383    * <code>java.sql.Date</code> value.
 384    *
 385    * @param index The index of the parameter value to set.
 386    * @param value The value of the parameter.
 387    * @param calendar The <code>Calendar</code> to use for timezone and locale.
 388    * @exception SQLException If an error occurs.
 389    */
 390   public void setDate(int parameterIndex, Date x, Calendar cal)
 391     throws SQLException;
 392
 393   /**
 394    * This method sets the specified parameter from the given Java
 395    * <code>java.sql.Time</code> value.
 396    *
 397    * @param index The index of the parameter value to set.
 398    * @param value The value of the parameter.
 399    * @param calendar The <code>Calendar</code> to use for timezone and locale.
 400    * @exception SQLException If an error occurs.
 401    */
 402   public void setTime(int parameterIndex, Time x, Calendar cal)
 403     throws SQLException;
 404
 405   /**
 406    * This method sets the specified parameter from the given Java
 407    * <code>java.sql.Timestamp</code> value.
 408    *
 409    * @param index The index of the parameter value to set.
 410    * @param value The value of the parameter.
 411    * @param calendar The <code>Calendar</code> to use for timezone and locale.
 412    * @exception SQLException If an error occurs.
 413    */
 414   public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal)
 415     throws SQLException;
 416
 417   /**
 418    * This method populates the specified parameter with a SQL NULL value
 419    * for the specified type.
 420    *
 421    * @param index The index of the parameter to set.
 422    * @param type The SQL type identifier of the parameter from <code>Types</code>
 423    * @param name The name of the data type, for user defined types.
 424    * @exception SQLException If an error occurs.
 425    */
 426   public void setNull(int paramIndex, int sqlType, String typeName)
 427     throws SQLException;
 428
 429   /**
 430    * @since 1.4
 431    */
 432   public void setURL(int parameterIndex, URL x) throws SQLException;
 433
 434   /**
 435    * @since 1.4
 436    */
 437   public ParameterMetaData getParameterMetaData() throws SQLException;
 438 }