Java 1.2 How-To

home *** CD-ROM | disk | FTP | other *** search

/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / sql / PreparedStatement.java < prev next >

Wrap

Java Source | 1998-03-20 | 15.4 KB | 446 lines

/* * @(#)PreparedStatement.java 1.14 98/03/18 * * Copyright 1996-1998 by Sun Microsystems, Inc., * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * All rights reserved. * * This software is the confidential and proprietary information * of Sun Microsystems, Inc. ("Confidential Information"). You * shall not disclose such Confidential Information and shall use * it only in accordance with the terms of the license agreement * you entered into with Sun. */ package java.sql; import java.math.BigDecimal; /** * A SQL statement is pre-compiled and stored in a * PreparedStatement object. This object can then be used to * efficiently execute this statement multiple times. * * Note: The setXXX methods for setting IN parameter values * must specify types that are compatible with the defined SQL type of * the input parameter. For instance, if the IN parameter has SQL type * Integer then setInt should be used. * * If arbitrary parameter type conversions are required then the * setObject method should be used with a target SQL type. * * @see Connection#prepareStatement * @see ResultSet */ public interface PreparedStatement extends Statement { /** * A prepared SQL query is executed and its ResultSet is returned. * * @return a ResultSet that contains the data produced by the * query; never null * @exception SQLException if a database-access error occurs. */ ResultSet executeQuery() throws SQLException; /** * Execute a SQL INSERT, UPDATE or DELETE statement. In addition, * SQL statements that return nothing such as SQL DDL statements * can be executed. * * @return either the row count for INSERT, UPDATE or DELETE; or 0 * for SQL statements that return nothing * @exception SQLException if a database-access error occurs. */ int executeUpdate() throws SQLException; /** * Set a parameter to SQL NULL. * * Note: You must specify the parameter's SQL type. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param sqlType SQL type code defined by java.sql.Types * @exception SQLException if a database-access error occurs. */ void setNull(int parameterIndex, int sqlType) throws SQLException; /** * Set a parameter to a Java boolean value. The driver converts this * to a SQL BIT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setBoolean(int parameterIndex, boolean x) throws SQLException; /** * Set a parameter to a Java byte value. The driver converts this * to a SQL TINYINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setByte(int parameterIndex, byte x) throws SQLException; /** * Set a parameter to a Java short value. The driver converts this * to a SQL SMALLINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setShort(int parameterIndex, short x) throws SQLException; /** * Set a parameter to a Java int value. The driver converts this * to a SQL INTEGER value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setInt(int parameterIndex, int x) throws SQLException; /** * Set a parameter to a Java long value. The driver converts this * to a SQL BIGINT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setLong(int parameterIndex, long x) throws SQLException; /** * Set a parameter to a Java float value. The driver converts this * to a SQL FLOAT value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setFloat(int parameterIndex, float x) throws SQLException; /** * Set a parameter to a Java double value. The driver converts this * to a SQL DOUBLE value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setDouble(int parameterIndex, double x) throws SQLException; /** * Set a parameter to a java.math.BigDecimal value. * The driver converts this to a SQL NUMERIC value when * it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException; /** * Set a parameter to a Java String value. The driver converts this * to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments * size relative to the driver's limits on VARCHARs) when it sends * it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setString(int parameterIndex, String x) throws SQLException; /** * Set a parameter to a Java array of bytes. The driver converts * this to a SQL VARBINARY or LONGVARBINARY (depending on the * argument's size relative to the driver's limits on VARBINARYs) * when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setBytes(int parameterIndex, byte x[]) throws SQLException; /** * Set a parameter to a java.sql.Date value. The driver converts this * to a SQL DATE value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setDate(int parameterIndex, java.sql.Date x) throws SQLException; /** * Set a parameter to a java.sql.Time value. The driver converts this * to a SQL TIME value when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setTime(int parameterIndex, java.sql.Time x) throws SQLException; /** * Set a parameter to a java.sql.Timestamp value. The driver * converts this to a SQL TIMESTAMP value when it sends it to the * database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @exception SQLException if a database-access error occurs. */ void setTimestamp(int parameterIndex, java.sql.Timestamp x) throws SQLException; /** * When a very large ASCII value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. The JDBC driver will * do any necessary conversion from ASCII to the database char format. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the ASCII parameter value * @param length the number of bytes in the stream * @exception SQLException if a database-access error occurs. */ void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. The JDBC driver will * do any necessary conversion from UNICODE to the database char format. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the * UNICODE parameter value * @param length the number of bytes in the stream * @exception SQLException if a database-access error occurs. * @deprecated */ void setUnicodeStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * When a very large binary value is input to a LONGVARBINARY * parameter, it may be more practical to send it via a * java.io.InputStream. JDBC will read the data from the stream * as needed, until it reaches end-of-file. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the binary parameter value * @param length the number of bytes in the stream * @exception SQLException if a database-access error occurs. */ void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * In general, parameter values remain in force for repeated use of a * Statement. Setting a parameter value automatically clears its * previous value. However, in some cases it is useful to immediately * release the resources used by the current parameter values; this can * be done by calling clearParameters. * * @exception SQLException if a database-access error occurs. */ void clearParameters() throws SQLException; //---------------------------------------------------------------------- // Advanced features: /** * Set the value of a parameter using an object; use the * java.lang equivalent objects for integral values. * * The given Java object will be converted to the targetSqlType * before being sent to the database. * * Note that this method may be used to pass datatabase- * specific abstract data types. This is done by using a Driver- * specific Java type and using a targetSqlType of * java.sql.types.OTHER. * * @param parameterIndex The first parameter is 1, the second is 2, ... * @param x The object containing the input parameter value * @param targetSqlType The SQL type (as defined in java.sql.Types) to be * sent to the database. The scale argument may further qualify this type. * @param scale For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types * this is the number of digits after the decimal. For all other * types this value will be ignored, * @exception SQLException if a database-access error occurs. * @see Types */ void setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException; /** * This method is like setObject above, but assumes a scale of zero. * * @exception SQLException if a database-access error occurs. */ void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException; /** * Set the value of a parameter using an object; use the * java.lang equivalent objects for integral values. * * The JDBC specification specifies a standard mapping from * Java Object types to SQL types. The given argument java object * will be converted to the corresponding SQL type before being * sent to the database. * * Note that this method may be used to pass datatabase * specific abstract data types, by using a Driver specific Java * type. * * @param parameterIndex The first parameter is 1, the second is 2, ... * @param x The object containing the input parameter value * @exception SQLException if a database-access error occurs. */ void setObject(int parameterIndex, Object x) throws SQLException; /** * Some prepared statements return multiple results; the execute * method handles these complex statements as well as the simpler * form of statements handled by executeQuery and executeUpdate. * * @exception SQLException if a database-access error occurs. * @see Statement#execute */ boolean execute() throws SQLException; //--------------------------JDBC 2.0----------------------------- /** * JDBC 2.0 * * Add a set of parameters to the batch. * * @exception SQLException if a database-access error occurs. * @see Statement#addBatch */ void addBatch() throws SQLException; /** * JDBC 2.0 * * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.Reader. JDBC will read the data from the stream * as needed, until it reaches end-of-file. The JDBC driver will * do any necessary conversion from UNICODE to the database char format. * * Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java reader which contains the UNICODE data * @param length the number of characters in the stream * @exception SQLException if a database-access error occurs. */ void setCharacterStream(int parameterIndex, java.io.Reader reader, int length) throws SQLException; /** * When the parameter x is a UDT value, the JDBC driver will * act as follows: * * If the object is of a class implementing SQLData, * then call its method writeSQL to write it to the SQL data stream. * else * If the object is of a class implementing Ref, BlobLocator, * ClobLocator, StructLocator, or ArrayLocator then * pass it to the database as a value of the corresponding SQL type. * * Raise an exception if there is an ambiguity, for example, if the * object is of a class implementing more than one of those interfaces. * * @param i the first parameter is 1, the second is 2, ... * @param x an value to be passed to SQL void setObject (int i, Object x) throws SQLException; */ /** * Set a REF(<structured-type>) parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing data of an SQL REF Type */ void setRef (int i, Ref x) throws SQLException; /** * Set a LOCATOR(BLOB) parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing data of a locator to a BLOB */ void setBlobLocator (int i, BlobLocator x) throws SQLException; /** * Set a LOCATOR(CLOB) parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing data of a locator to a CLOB */ void setClobLocator (int i, ClobLocator x) throws SQLException; /** * Set a LOCATOR(<structured-type>) parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing data of a locator to an instance * of a Structured Type */ void setStructLocator (int i, StructLocator x) throws SQLException; /** * Set a LOCATOR(<array>) parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing data of a locator to an SQL array */ void setArrayLocator (int i, ArrayLocator x) throws SQLException; }