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