Apple Developer Connection Student Program

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

/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / PreparedStatement.java < prev next >

Wrap

Java Source | 1999-05-28 | 23.0 KB | 582 lines | [TEXT/CWIE]

/* * @(#)PreparedStatement.java 1.23 98/09/29 * * 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; import java.util.Calendar; /** * An object that represents a precompiled SQL statement. * 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 the method <code>setInt</code> should be used. * * If arbitrary parameter type conversions are required, the method * <code>setObject</code> should be used with a target SQL type. * * Example of setting a parameter; <code>con</code> is an active connection * <pre><code> * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES * SET SALARY = ? WHERE ID = ?"); * pstmt.setBigDecimal(1, 153833.00) * pstmt.setInt(2, 110592) * </code></pre> * * @see Connection#prepareStatement * @see ResultSet */ public interface PreparedStatement extends Statement { /** * Executes the SQL query in this <code>PreparedStatement</code> object * and returns the result set generated by the query. * * @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; /** * Executes the SQL INSERT, UPDATE or DELETE statement * in this <code>PreparedStatement</code> object. * 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 statements; * or 0 for SQL statements that return nothing * @exception SQLException if a database access error occurs */ int executeUpdate() throws SQLException; /** * Sets the designated 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 the SQL type code defined in java.sql.Types * @exception SQLException if a database access error occurs */ void setNull(int parameterIndex, int sqlType) throws SQLException; /** * Sets the designated parameter to a Java boolean value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java byte value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java short value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java int value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java long value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java float value. The driver converts this * to an 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; /** * Sets the designated parameter to a Java double value. The driver converts this * to an 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; /** * Sets the designated parameter to a java.lang.BigDecimal value. * The driver converts this to an 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; /** * Sets the designated parameter to a Java String value. The driver converts this * to an SQL VARCHAR or LONGVARCHAR value (depending on the argument's * 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; /** * Sets the designated parameter to a Java array of bytes. The driver converts * this to an 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; /** * Sets the designated parameter to a java.sql.Date value. The driver converts this * to an 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; /** * Sets the designated parameter to a java.sql.Time value. The driver converts this * to an 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; /** * Sets the designated parameter to a java.sql.Timestamp value. The driver * converts this to an 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; /** * Sets the designated parameter to the given input stream, which will have * the specified number of bytes. * 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 that 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; /** * Sets the designated parameter to the given input stream, which will have * the specified number of bytes. * 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. * The byte format of the Unicode stream must be Java UTF-8, as * defined in the Java Virtual Machine Specification. * * 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; /** * Sets the designated parameter to the given input stream, which will have * the specified number of bytes. * 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; /** * Clears the current parameter values immediately. * 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: /** * Sets the value of a parameter using an object. The second * argument must be an object type; for integral values, the * java.lang equivalent objects should be used. * * The given Java object will be converted to the targetSqlType * before being sent to the database. * * If the object has a custom mapping (is of a class implementing SQLData), * the JDBC driver should call its method <code>writeSQL</code> to write it * to the SQL data stream. * If, on the other hand, the object is of a class implementing * Ref, Blob, Clob, Struct, * or Array, the driver should pass it to the database as a value of the * corresponding SQL type. * * Note that this method may be used to pass datatabase- * specific abstract data types. * * @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 point. 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; /** * Sets the value of the designated parameter with the given object. * This method is like setObject above, except that it assumes a scale of zero. * * @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 * @exception SQLException if a database access error occurs */ void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException; /** * Sets 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. * * If the object is of a class implementing SQLData, * the JDBC driver should call its method <code>writeSQL</code> to write it * to the SQL data stream. * If, on the other hand, the object is of a class implementing * Ref, Blob, Clob, Struct, * or Array, then the driver should pass it to the database as a value of the * corresponding SQL type. * * This method throws an exception if there is an ambiguity, for example, if the * object is of a class implementing more than one of those interfaces. * * @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; /** * Executes any kind of SQL statement. * 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 * * Adds 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 * * Sets the designated parameter to the given <code>Reader</code> * object, which is the given number of characters long. * 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; /** * JDBC 2.0 * * Sets 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 * @exception SQLException if a database access error occurs */ void setRef (int i, Ref x) throws SQLException; /** * JDBC 2.0 * * Sets a BLOB parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing a BLOB * @exception SQLException if a database access error occurs */ void setBlob (int i, Blob x) throws SQLException; /** * JDBC 2.0 * * Sets a CLOB parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing a CLOB * @exception SQLException if a database access error occurs */ void setClob (int i, Clob x) throws SQLException; /** * JDBC 2.0 * * Sets an Array parameter. * * @param i the first parameter is 1, the second is 2, ... * @param x an object representing an SQL array * @exception SQLException if a database access error occurs */ void setArray (int i, Array x) throws SQLException; /** * JDBC 2.0 * * Gets the number, types and properties of a ResultSet's columns. * * @return the description of a ResultSet's columns * @exception SQLException if a database access error occurs */ ResultSetMetaData getMetaData() throws SQLException; /** * JDBC 2.0 * * Sets the designated parameter to a java.sql.Date value, * using the given <code>Calendar</code> object. The driver uses * the <code>Calendar</code> object to construct an SQL DATE, * which the driver then sends to the database. With a * a <code>Calendar</code> object, the driver can calculate the date * taking into account a custom timezone and locale. If no * <code>Calendar</code> object is specified, the driver uses the default * timezone and locale. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the <code>Calendar</code> object the driver will use * to construct the date * @exception SQLException if a database access error occurs */ void setDate(int parameterIndex, java.sql.Date x, Calendar cal) throws SQLException; /** * JDBC 2.0 * * Sets the designated parameter to a java.sql.Time value, * using the given <code>Calendar</code> object. The driver uses * the <code>Calendar</code> object to construct an SQL TIME, * which the driver then sends to the database. With a * a <code>Calendar</code> object, the driver can calculate the time * taking into account a custom timezone and locale. If no * <code>Calendar</code> object is specified, the driver uses the default * timezone and locale. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the <code>Calendar</code> object the driver will use * to construct the time * @exception SQLException if a database access error occurs */ void setTime(int parameterIndex, java.sql.Time x, Calendar cal) throws SQLException; /** * JDBC 2.0 * * Sets the designated parameter to a java.sql.Timestamp value, * using the given <code>Calendar</code> object. The driver uses * the <code>Calendar</code> object to construct an SQL TIMESTAMP, * which the driver then sends to the database. With a * a <code>Calendar</code> object, the driver can calculate the timestamp * taking into account a custom timezone and locale. If no * <code>Calendar</code> object is specified, the driver uses the default * timezone and locale. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the <code>Calendar</code> object the driver will use * to construct the timestamp * @exception SQLException if a database access error occurs */ void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) throws SQLException; /** * JDBC 2.0 * * Sets the designated parameter to SQL NULL. This version of setNull should * be used for user-named types and REF type parameters. Examples * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and * named array types. * * Note: To be portable, applications must give the * SQL type code and the fully-qualified SQL type name when specifying * a NULL user-defined or REF parameter. In the case of a user-named type * the name is the type name of the parameter itself. For a REF * parameter the name is the type name of the referenced type. If * a JDBC driver does not need the type code or type name information, * it may ignore it. * * Although it is intended for user-named and Ref parameters, * this method may be used to set a null parameter of any JDBC type. * If the parameter does not have a user-named or REF type, the given * typeName is ignored. * * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param sqlType a value from java.sql.Types * @param typeName the fully-qualified name of an SQL user-named type, * ignored if the parameter is not a user-named type or REF * @exception SQLException if a database access error occurs */ void setNull (int paramIndex, int sqlType, String typeName) throws SQLException; }