home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / CallableStatement.java < prev    next >
Text File  |  1997-05-20  |  11KB  |  259 lines
  1. /*
  2.  * @(#)CallableStatement.java    1.7 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>CallableStatement is used to execute SQL stored procedures.
  29.  *
  30.  * <P>JDBC provides a stored procedure SQL escape that allows stored
  31.  * procedures to be called in a standard way for all RDBMS's. This
  32.  * escape syntax has one form that includes a result parameter and one
  33.  * that does not. If used, the result parameter must be registered as
  34.  * an OUT parameter. The other parameters may be used for input,
  35.  * output or both. Parameters are refered to sequentially, by
  36.  * number. The first parameter is 1.
  37.  *
  38.  * <P><CODE>
  39.  * {?= call <procedure-name>[<arg1>,<arg2>, ...]}<BR>
  40.  * {call <procedure-name>[<arg1>,<arg2>, ...]}
  41.  * </CODE>
  42.  *    
  43.  * <P>IN parameter values are set using the set methods inherited from
  44.  * PreparedStatement. The type of all OUT parameters must be
  45.  * registered prior to executing the stored procedure; their values
  46.  * are retrieved after execution via the get methods provided here.
  47.  *
  48.  * <P>A Callable statement may return a ResultSet or multiple
  49.  * ResultSets. Multiple ResultSets are handled using operations
  50.  * inherited from Statement.
  51.  *
  52.  * <P>For maximum portability, a call's ResultSets and update counts
  53.  * should be processed prior to getting the values of output
  54.  * parameters.
  55.  *
  56.  * @see Connection#prepareCall
  57.  * @see ResultSet 
  58.  */
  59. public interface CallableStatement extends PreparedStatement {
  60.  
  61.     /**
  62.      * Before executing a stored procedure call, you must explicitly
  63.      * call registerOutParameter to register the java.sql.Type of each
  64.      * out parameter.
  65.      *
  66.      * <P><B>Note:</B> When reading the value of an out parameter, you
  67.      * must use the getXXX method whose Java type XXX corresponds to the
  68.      * parameter's registered SQL type.
  69.      *
  70.      * @param parameterIndex the first parameter is 1, the second is 2,...
  71.      * @param sqlType SQL type code defined by java.sql.Types;
  72.      * for parameters of type Numeric or Decimal use the version of
  73.      * registerOutParameter that accepts a scale value
  74.      * @exception SQLException if a database-access error occurs.
  75.      * @see Type 
  76.      */
  77.     void registerOutParameter(int parameterIndex, int sqlType)
  78.         throws SQLException;
  79.  
  80.     /**
  81.      * Use this version of registerOutParameter for registering
  82.      * Numeric or Decimal out parameters.
  83.      *
  84.      * <P><B>Note:</B> When reading the value of an out parameter, you
  85.      * must use the getXXX method whose Java type XXX corresponds to the
  86.      * parameter's registered SQL type.
  87.      *
  88.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  89.      * @param sqlType use either java.sql.Type.NUMERIC or java.sql.Type.DECIMAL
  90.      * @param scale a value greater than or equal to zero representing the 
  91.      *              desired number of digits to the right of the decimal point
  92.      * @exception SQLException if a database-access error occurs.
  93.      * @see Type 
  94.      */
  95.     void registerOutParameter(int parameterIndex, int sqlType, int scale)
  96.         throws SQLException;
  97.  
  98.     /**
  99.      * An OUT parameter may have the value of SQL NULL; wasNull reports 
  100.      * whether the last value read has this special value.
  101.      *
  102.      * <P><B>Note:</B> You must first call getXXX on a parameter to
  103.      * read its value and then call wasNull() to see if the value was
  104.      * SQL NULL.
  105.      *
  106.      * @return true if the last parameter read was SQL NULL 
  107.      * @exception SQLException if a database-access error occurs.
  108.      */
  109.     boolean wasNull() throws SQLException;
  110.  
  111.     /**
  112.      * Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.
  113.      *
  114.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  115.      * @return the parameter value; if the value is SQL NULL, the result is null
  116.      * @exception SQLException if a database-access error occurs.
  117.      */
  118.     String getString(int parameterIndex) throws SQLException;
  119.  
  120.     /**
  121.      * Get the value of a BIT parameter as a Java boolean.
  122.      *
  123.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  124.      * @return the parameter value; if the value is SQL NULL, the result is false
  125.      * @exception SQLException if a database-access error occurs.
  126.      */
  127.     boolean getBoolean(int parameterIndex) throws SQLException;
  128.  
  129.     /**
  130.      * Get the value of a TINYINT parameter as a Java byte.
  131.      *
  132.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  133.      * @return the parameter value; if the value is SQL NULL, the result is 0
  134.      * @exception SQLException if a database-access error occurs.
  135.      */
  136.     byte getByte(int parameterIndex) throws SQLException;
  137.  
  138.     /**
  139.      * Get the value of a SMALLINT parameter as a Java short.
  140.      *
  141.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  142.      * @return the parameter value; if the value is SQL NULL, the result is 0
  143.      * @exception SQLException if a database-access error occurs.
  144.      */
  145.     short getShort(int parameterIndex) throws SQLException;
  146.  
  147.     /**
  148.      * Get the value of an INTEGER parameter as a Java int.
  149.      *
  150.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  151.      * @return the parameter value; if the value is SQL NULL, the result is 0
  152.      * @exception SQLException if a database-access error occurs.
  153.      */
  154.     int getInt(int parameterIndex) throws SQLException;
  155.  
  156.     /**
  157.      * Get the value of a BIGINT parameter as a Java long.
  158.      *
  159.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  160.      * @return the parameter value; if the value is SQL NULL, the result is 0
  161.      * @exception SQLException if a database-access error occurs.
  162.      */
  163.     long getLong(int parameterIndex) throws SQLException;
  164.  
  165.     /**
  166.      * Get the value of a FLOAT parameter as a Java float.
  167.      *
  168.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  169.      * @return the parameter value; if the value is SQL NULL, the result is 0
  170.      * @exception SQLException if a database-access error occurs.
  171.      */
  172.     float getFloat(int parameterIndex) throws SQLException;
  173.  
  174.     /**
  175.      * Get the value of a DOUBLE parameter as a Java double.
  176.      *
  177.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  178.      * @return the parameter value; if the value is SQL NULL, the result is 0
  179.      * @exception SQLException if a database-access error occurs.
  180.      */
  181.     double getDouble(int parameterIndex) throws SQLException;
  182.  
  183.     /** 
  184.      * Get the value of a NUMERIC parameter as a java.math.BigDecimal object.
  185.      *
  186.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  187.      *
  188.      * @param scale a value greater than or equal to zero representing the
  189.      * desired number of digits to the right of the decimal point 
  190.      *
  191.      * @return the parameter value; if the value is SQL NULL, the result is
  192.      * null 
  193.      * @exception SQLException if a database-access error occurs.
  194.      */
  195.     BigDecimal getBigDecimal(int parameterIndex, int scale) 
  196.     throws SQLException;
  197.  
  198.     /**
  199.      * Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[]
  200.      *
  201.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  202.      * @return the parameter value; if the value is SQL NULL, the result is null
  203.      * @exception SQLException if a database-access error occurs.
  204.      */
  205.     byte[] getBytes(int parameterIndex) throws SQLException;
  206.  
  207.     /**
  208.      * Get the value of a SQL DATE parameter as a java.sql.Date object
  209.      *
  210.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  211.      * @return the parameter value; if the value is SQL NULL, the result is null
  212.      * @exception SQLException if a database-access error occurs.
  213.      */
  214.     java.sql.Date getDate(int parameterIndex) throws SQLException;
  215.  
  216.     /**
  217.      * Get the value of a SQL TIME parameter as a java.sql.Time object.
  218.      *
  219.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  220.      * @return the parameter value; if the value is SQL NULL, the result is null
  221.      * @exception SQLException if a database-access error occurs.
  222.      */
  223.     java.sql.Time getTime(int parameterIndex) throws SQLException;
  224.  
  225.     /**
  226.      * Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.
  227.      *
  228.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  229.      * @return the parameter value; if the value is SQL NULL, the result is null
  230.      * @exception SQLException if a database-access error occurs.
  231.      */
  232.     java.sql.Timestamp getTimestamp(int parameterIndex) 
  233.         throws SQLException;
  234.  
  235.     //----------------------------------------------------------------------
  236.     // Advanced features:
  237.  
  238.  
  239.     /**
  240.      * Get the value of a parameter as a Java object.
  241.      *
  242.      * <p>This method returns a Java object whose type coresponds to the SQL
  243.      * type that was registered for this parameter using registerOutParameter.
  244.      *
  245.      * <p>Note that this method may be used to read
  246.      * datatabase-specific, abstract data types. This is done by
  247.      * specifying a targetSqlType of java.sql.types.OTHER, which
  248.      * allows the driver to return a database-specific Java type.
  249.      *
  250.      * @param parameterIndex The first parameter is 1, the second is 2, ...
  251.      * @return A java.lang.Object holding the OUT parameter value.
  252.      * @exception SQLException if a database-access error occurs.
  253.      * @see Types 
  254.      */
  255.     Object getObject(int parameterIndex) throws SQLException;
  256.  
  257. }
  258.  
  259.