home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / PreparedStatement.java < prev    next >
Text File  |  1997-08-30  |  14KB  |  348 lines
  1. /*
  2.  * @(#)PreparedStatement.java    1.8 97/02/11
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.sql;
  24.  
  25. import java.math.BigDecimal;
  26.  
  27. /**
  28.  * <P>A SQL statement is pre-compiled and stored in a
  29.  * PreparedStatement object. This object can then be used to
  30.  * efficiently execute this statement multiple times. 
  31.  *
  32.  * <P><B>Note:</B> The setXXX methods for setting IN parameter values
  33.  * must specify types that are compatible with the defined SQL type of
  34.  * the input parameter. For instance, if the IN parameter has SQL type
  35.  * Integer then setInt should be used.
  36.  *
  37.  * <p>If arbitrary parameter type conversions are required then the
  38.  * setObject method should be used with a target SQL type.
  39.  *
  40.  * @see Connection#prepareStatement
  41.  * @see ResultSet 
  42.  */
  43.  
  44. public interface PreparedStatement extends Statement {
  45.  
  46.     /**
  47.      * A prepared SQL query is executed and its ResultSet is returned.
  48.      *
  49.      * @return a ResultSet that contains the data produced by the
  50.      * query; never null
  51.      * @exception SQLException if a database-access error occurs.
  52.      */
  53.     ResultSet executeQuery() throws SQLException;
  54.  
  55.     /**
  56.      * Execute a SQL INSERT, UPDATE or DELETE statement. In addition,
  57.      * SQL statements that return nothing such as SQL DDL statements
  58.      * can be executed.
  59.      *
  60.      * @return either the row count for INSERT, UPDATE or DELETE; or 0
  61.      * for SQL statements that return nothing
  62.      * @exception SQLException if a database-access error occurs.
  63.      */
  64.     int executeUpdate() throws SQLException;
  65.  
  66.     /**
  67.      * Set a parameter to SQL NULL.
  68.      *
  69.      * <P><B>Note:</B> You must specify the parameter's SQL type.
  70.      *
  71.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  72.      * @param sqlType SQL type code defined by java.sql.Types
  73.      * @exception SQLException if a database-access error occurs.
  74.      */
  75.     void setNull(int parameterIndex, int sqlType) throws SQLException;
  76.  
  77.     /**
  78.      * Set a parameter to a Java boolean value.  The driver converts this
  79.      * to a SQL BIT value when it sends it to the database.
  80.      *
  81.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  82.      * @param x the parameter value
  83.      * @exception SQLException if a database-access error occurs.
  84.      */
  85.     void setBoolean(int parameterIndex, boolean x) throws SQLException;
  86.  
  87.     /**
  88.      * Set a parameter to a Java byte value.  The driver converts this
  89.      * to a SQL TINYINT value when it sends it to the database.
  90.      *
  91.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  92.      * @param x the parameter value
  93.      * @exception SQLException if a database-access error occurs.
  94.      */
  95.     void setByte(int parameterIndex, byte x) throws SQLException;
  96.  
  97.     /**
  98.      * Set a parameter to a Java short value.  The driver converts this
  99.      * to a SQL SMALLINT value when it sends it to the database.
  100.      *
  101.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  102.      * @param x the parameter value
  103.      * @exception SQLException if a database-access error occurs.
  104.      */
  105.     void setShort(int parameterIndex, short x) throws SQLException;
  106.  
  107.     /**
  108.      * Set a parameter to a Java int value.  The driver converts this
  109.      * to a SQL INTEGER value when it sends it to the database.
  110.      *
  111.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  112.      * @param x the parameter value
  113.      * @exception SQLException if a database-access error occurs.
  114.      */
  115.     void setInt(int parameterIndex, int x) throws SQLException;
  116.  
  117.     /**
  118.      * Set a parameter to a Java long value.  The driver converts this
  119.      * to a SQL BIGINT value when it sends it to the database.
  120.      *
  121.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  122.      * @param x the parameter value
  123.      * @exception SQLException if a database-access error occurs.
  124.      */
  125.     void setLong(int parameterIndex, long x) throws SQLException;
  126.  
  127.     /**
  128.      * Set a parameter to a Java float value.  The driver converts this
  129.      * to a SQL FLOAT value when it sends it to the database.
  130.      *
  131.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  132.      * @param x the parameter value
  133.      * @exception SQLException if a database-access error occurs.
  134.      */
  135.     void setFloat(int parameterIndex, float x) throws SQLException;
  136.  
  137.     /**
  138.      * Set a parameter to a Java double value.  The driver converts this
  139.      * to a SQL DOUBLE value when it sends it to the database.
  140.      *
  141.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  142.      * @param x the parameter value
  143.      * @exception SQLException if a database-access error occurs.
  144.      */
  145.     void setDouble(int parameterIndex, double x) throws SQLException;
  146.  
  147.     /**
  148.      * Set a parameter to a java.lang.BigDecimal value.  
  149.      * The driver converts this to a SQL NUMERIC value when
  150.      * it sends it to the database.
  151.      *
  152.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  153.      * @param x the parameter value
  154.      * @exception SQLException if a database-access error occurs.
  155.      */
  156.     void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;
  157.  
  158.     /**
  159.      * Set a parameter to a Java String value.  The driver converts this
  160.      * to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments
  161.      * size relative to the driver's limits on VARCHARs) when it sends
  162.      * it to the database.
  163.      *
  164.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  165.      * @param x the parameter value
  166.      * @exception SQLException if a database-access error occurs.
  167.      */
  168.     void setString(int parameterIndex, String x) throws SQLException;
  169.  
  170.     /**
  171.      * Set a parameter to a Java array of bytes.  The driver converts
  172.      * this to a SQL VARBINARY or LONGVARBINARY (depending on the
  173.      * argument's size relative to the driver's limits on VARBINARYs)
  174.      * when it sends it to the database.
  175.      *
  176.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  177.      * @param x the parameter value 
  178.      * @exception SQLException if a database-access error occurs.
  179.      */
  180.     void setBytes(int parameterIndex, byte x[]) throws SQLException;
  181.  
  182.     /**
  183.      * Set a parameter to a java.sql.Date value.  The driver converts this
  184.      * to a SQL DATE value when it sends it to the database.
  185.      *
  186.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  187.      * @param x the parameter value
  188.      * @exception SQLException if a database-access error occurs.
  189.      */
  190.     void setDate(int parameterIndex, java.sql.Date x)
  191.         throws SQLException;
  192.  
  193.     /**
  194.      * Set a parameter to a java.sql.Time value.  The driver converts this
  195.      * to a SQL TIME value when it sends it to the database.
  196.      *
  197.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  198.      * @param x the parameter value
  199.      * @exception SQLException if a database-access error occurs.
  200.      */
  201.     void setTime(int parameterIndex, java.sql.Time x) 
  202.         throws SQLException;
  203.  
  204.     /**
  205.      * Set a parameter to a java.sql.Timestamp value.  The driver
  206.      * converts this to a SQL TIMESTAMP value when it sends it to the
  207.      * database.
  208.      *
  209.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  210.      * @param x the parameter value 
  211.      * @exception SQLException if a database-access error occurs.
  212.      */
  213.     void setTimestamp(int parameterIndex, java.sql.Timestamp x)
  214.         throws SQLException;
  215.  
  216.     /**
  217.      * When a very large ASCII value is input to a LONGVARCHAR
  218.      * parameter, it may be more practical to send it via a
  219.      * java.io.InputStream. JDBC will read the data from the stream
  220.      * as needed, until it reaches end-of-file.  The JDBC driver will
  221.      * do any necessary conversion from ASCII to the database char format.
  222.      * 
  223.      * <P><B>Note:</B> This stream object can either be a standard
  224.      * Java stream object or your own subclass that implements the
  225.      * standard interface.
  226.      *
  227.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  228.      * @param x the java input stream which contains the ASCII parameter value
  229.      * @param length the number of bytes in the stream 
  230.      * @exception SQLException if a database-access error occurs.
  231.      */
  232.     void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)
  233.         throws SQLException;
  234.  
  235.     /**
  236.      * When a very large UNICODE value is input to a LONGVARCHAR
  237.      * parameter, it may be more practical to send it via a
  238.      * java.io.InputStream. JDBC will read the data from the stream
  239.      * as needed, until it reaches end-of-file.  The JDBC driver will
  240.      * do any necessary conversion from UNICODE to the database char format.
  241.      * 
  242.      * <P><B>Note:</B> This stream object can either be a standard
  243.      * Java stream object or your own subclass that implements the
  244.      * standard interface.
  245.      *
  246.      * @param parameterIndex the first parameter is 1, the second is 2, ...  
  247.      * @param x the java input stream which contains the
  248.      * UNICODE parameter value 
  249.      * @param length the number of bytes in the stream 
  250.      * @exception SQLException if a database-access error occurs.
  251.      */
  252.     void setUnicodeStream(int parameterIndex, java.io.InputStream x, int length)
  253.         throws SQLException;
  254.  
  255.     /**
  256.      * When a very large binary value is input to a LONGVARBINARY
  257.      * parameter, it may be more practical to send it via a
  258.      * java.io.InputStream. JDBC will read the data from the stream
  259.      * as needed, until it reaches end-of-file.
  260.      * 
  261.      * <P><B>Note:</B> This stream object can either be a standard
  262.      * Java stream object or your own subclass that implements the
  263.      * standard interface.
  264.      *
  265.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  266.      * @param x the java input stream which contains the binary parameter value
  267.      * @param length the number of bytes in the stream 
  268.      * @exception SQLException if a database-access error occurs.
  269.      */
  270.     void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) 
  271.         throws SQLException;
  272.  
  273.     /**
  274.      * <P>In general, parameter values remain in force for repeated use of a
  275.      * Statement. Setting a parameter value automatically clears its
  276.      * previous value.  However, in some cases it is useful to immediately
  277.      * release the resources used by the current parameter values; this can
  278.      * be done by calling clearParameters.
  279.      *
  280.      * @exception SQLException if a database-access error occurs.
  281.      */
  282.     void clearParameters() throws SQLException;
  283.  
  284.     //----------------------------------------------------------------------
  285.     // Advanced features:
  286.  
  287.     /**
  288.      * <p>Set the value of a parameter using an object; use the
  289.      * java.lang equivalent objects for integral values.
  290.      *
  291.      * <p>The given Java object will be converted to the targetSqlType
  292.      * before being sent to the database.
  293.      *
  294.      * <p>Note that this method may be used to pass datatabase-
  295.      * specific abstract data types. This is done by using a Driver-
  296.      * specific Java type and using a targetSqlType of
  297.      * java.sql.types.OTHER.
  298.      *
  299.      * @param parameterIndex The first parameter is 1, the second is 2, ...
  300.      * @param x The object containing the input parameter value
  301.      * @param targetSqlType The SQL type (as defined in java.sql.Types) to be 
  302.      * sent to the database. The scale argument may further qualify this type.
  303.      * @param scale For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types
  304.      *          this is the number of digits after the decimal.  For all other
  305.      *          types this value will be ignored,
  306.      * @exception SQLException if a database-access error occurs.
  307.      * @see Types 
  308.      */
  309.     void setObject(int parameterIndex, Object x, int targetSqlType, int scale)
  310.             throws SQLException;
  311.  
  312.    /**
  313.      * This method is like setObject above, but assumes a scale of zero.
  314.      *
  315.      * @exception SQLException if a database-access error occurs.
  316.      */
  317.     void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException;
  318.  
  319.     /**
  320.      * <p>Set the value of a parameter using an object; use the
  321.      * java.lang equivalent objects for integral values.
  322.      *
  323.      * <p>The JDBC specification specifies a standard mapping from
  324.      * Java Object types to SQL types.  The given argument java object
  325.      * will be converted to the corresponding SQL type before being
  326.      * sent to the database.
  327.      *
  328.      * <p>Note that this method may be used to pass datatabase
  329.      * specific abstract data types, by using a Driver specific Java
  330.      * type.
  331.      *
  332.      * @param parameterIndex The first parameter is 1, the second is 2, ...
  333.      * @param x The object containing the input parameter value 
  334.      * @exception SQLException if a database-access error occurs.
  335.      */
  336.     void setObject(int parameterIndex, Object x) throws SQLException;
  337.  
  338.     /**
  339.      * Some prepared statements return multiple results; the execute
  340.      * method handles these complex statements as well as the simpler
  341.      * form of statements handled by executeQuery and executeUpdate.
  342.      *
  343.      * @exception SQLException if a database-access error occurs.
  344.      * @see Statement#execute
  345.      */
  346.     boolean execute() throws SQLException;
  347. }
  348.