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 / CallableStatement.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  19.5 KB  |  488 lines  |  [TEXT/CWIE]
  1.     /*
  2.      * @(#)CallableStatement.java    1.17 98/05/08
  3.      * 
  4.      * Copyright 1996-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.     import java.util.Calendar;
  19.  
  20.     /**
  21.      * The interface used to execute SQL 
  22.      * stored procedures.  JDBC provides a stored procedure 
  23.      * SQL escape that allows stored procedures to be called in a standard 
  24.      * way for all RDBMSs. This escape syntax has one form that includes 
  25.      * a result parameter and one that does not. If used, the result 
  26.      * parameter must be registered as an OUT parameter. The other parameters
  27.      * can be used for input, output or both. Parameters are referred to 
  28.      * sequentially, by number. The first parameter is 1.
  29.      * <P>
  30.      * <blockquote><pre>
  31.      *   {?= call <procedure-name>[<arg1>,<arg2>, ...]}
  32.      *   {call <procedure-name>[<arg1>,<arg2>, ...]}
  33.      * </pre></blockquote>
  34.      * <P>
  35.      * IN parameter values are set using the set methods inherited from
  36.      * {@link 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 <code>get</code> methods provided here.
  39.      * <P>
  40.      * A <code>CallableStatement</code> can return one {@link ResultSet} or 
  41.      * multiple <code>ResultSet</code> objets.  Multiple 
  42.      * <code>ResultSet</code> objects are handled using operations
  43.      * inherited from {@link Statement}.
  44.      * <P>
  45.      * For maximum portability, a call's <code>ResultSet</code> objects and 
  46.      * update counts should be processed prior to getting the values of output
  47.      * parameters.
  48.      *
  49.      * @see Connection#prepareCall
  50.      * @see ResultSet 
  51.      */
  52.     public interface CallableStatement extends PreparedStatement {
  53.  
  54.         /**
  55.          * Registers the OUT parameter in ordinal position 
  56.          * <code>parameterIndex</code> to the JDBC type 
  57.          * <code>sqlType</code>.  All OUT parameters must be registered
  58.          * before a stored procedure is executed.
  59.          * <p>
  60.          * The JDBC type specified by <code>sqlType</code> for an OUT
  61.          * parameter determines the Java type that must be used
  62.          * in the <code>get</code> method to read the value of that parameter.
  63.          * <p>
  64.          * If the JDBC type expected to be returned to this output parameter
  65.          * is specific to this particular database, <code>sqlType</code>
  66.          * should be <code>java.sql.Types.OTHER</code>.  The method 
  67.          * {@link #getObject} retrieves the value.
  68.          * @param parameterIndex the first parameter is 1, the second is 2, 
  69.          * and so on
  70.          * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
  71.          * If the parameter is of type Numeric or Decimal, the version of
  72.          * <code>registerOutParameter</code> that accepts a scale value 
  73.          * should be used.
  74.          * @exception SQLException if a database access error occurs
  75.          * @see Types 
  76.          */
  77.         void registerOutParameter(int parameterIndex, int sqlType)
  78.             throws SQLException;
  79.  
  80.         /**
  81.          * Registers the parameter in ordinal position
  82.          * <code>parameterIndex</code> to be of JDBC type
  83.          * <code>sqlType</code>.  This method must be called
  84.          * before a stored procedure is executed.
  85.          * <p>
  86.          * The JDBC type specified by <code>sqlType</code> for an OUT
  87.          * parameter determines the Java type that must be used
  88.          * in the <code>get</code> method to read the value of that parameter.
  89.          * <p>
  90.          * This version of <code>registerOutParameter</code> should be
  91.          * used when the parameter is of JDBC type <code>NUMERIC</code>
  92.          * or <code>DECIMAL</code>.
  93.          * @param parameterIndex the first parameter is 1, the second is 2,
  94.          * and so on
  95.          * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
  96.          * @param scale the desired number of digits to the right of the
  97.          * decimal point.  It must be greater than or equal to zero.
  98.          * @exception SQLException if a database access error occurs
  99.          * @see Types 
  100.          */
  101.         void registerOutParameter(int parameterIndex, int sqlType, int scale)
  102.             throws SQLException;
  103.  
  104.         /**
  105.          * Indicates whether or not the last OUT parameter read had the value of
  106.          * SQL NULL.  Note that this method should be called only after
  107.          * calling the <code>get</code> method; otherwise, there is no value to use in 
  108.          * determining whether it is <code>null</code> or not.
  109.          * @return <code>true</code> if the last parameter read was SQL NULL;
  110.          * <code>false</code> otherwise. 
  111.          * @exception SQLException if a database access error occurs
  112.          */
  113.         boolean wasNull() throws SQLException;
  114.  
  115.         /**
  116.          * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>, 
  117.          * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in 
  118.          * the Java programming language.
  119.          * <p>
  120.          * For the fixed-length type JDBC CHAR, the <code>String</code> object
  121.          * returned has exactly the same value the JDBC CHAR value had in the
  122.          * database, including any padding added by the database.
  123.          * @param parameterIndex the first parameter is 1, the second is 2, 
  124.          * and so on
  125.          * @return the parameter value. If the value is SQL NULL, the result 
  126.          * is <code>null</code>.
  127.          * @exception SQLException if a database access error occurs
  128.          */
  129.         String getString(int parameterIndex) throws SQLException;
  130.  
  131.         /**
  132.          * Gets the value of a JDBC BIT parameter as a <code>boolean</code> 
  133.          * in the Java programming language.
  134.          * @param parameterIndex the first parameter is 1, the second is 2, 
  135.          * and so on
  136.          * @return the parameter value.  If the value is SQL NULL, the result 
  137.          * is <code>false</code>.
  138.          * @exception SQLException if a database access error occurs
  139.          */
  140.         boolean getBoolean(int parameterIndex) throws SQLException;
  141.  
  142.         /**
  143.          * Gets the value of a JDBC TINYINT parameter as a <code>byte</code> 
  144.          * in the Java programming language.
  145.          * @param parameterIndex the first parameter is 1, the second is 2, 
  146.          * and so on
  147.          * @return the parameter value.  If the value is SQL NULL, the result 
  148.          * is 0.
  149.          * @exception SQLException if a database access error occurs
  150.          */
  151.         byte getByte(int parameterIndex) throws SQLException;
  152.  
  153.         /**
  154.          * Gets the value of a JDBC SMALLINT parameter as a <code>short</code>
  155.          * in the Java programming language.
  156.          * @param parameterIndex the first parameter is 1, the second is 2, 
  157.          * and so on
  158.          * @return the parameter value.  If the value is SQL NULL, the result 
  159.          * is 0.
  160.          * @exception SQLException if a database access error occurs
  161.          */
  162.         short getShort(int parameterIndex) throws SQLException;
  163.  
  164.         /**
  165.          * Gets the value of a JDBC INTEGER parameter as an <code>int</code>
  166.          * in the Java programming language.
  167.          * @param parameterIndex the first parameter is 1, the second is 2, 
  168.          * and so on
  169.          * @return the parameter value.  If the value is SQL NULL, the result 
  170.          * is 0.
  171.          * @exception SQLException if a database access error occurs
  172.          */
  173.         int getInt(int parameterIndex) throws SQLException;
  174.  
  175.         /**
  176.          * Gets the value of a JDBC BIGINT parameter as a <code>long</code>
  177.          * in the Java programming language.
  178.          * @param parameterIndex the first parameter is 1, the second is 2, 
  179.          * and so on
  180.          * @return the parameter value.  If the value is SQL NULL, the result 
  181.          * is 0.
  182.          * @exception SQLException if a database access error occurs
  183.          */
  184.         long getLong(int parameterIndex) throws SQLException;
  185.  
  186.         /**
  187.          * Gets the value of a JDBC FLOAT parameter as a <code>float</code>
  188.          * in the Java programming language.
  189.          * @param parameterIndex the first parameter is 1, the second is 2, 
  190.          * and so on
  191.          * @return the parameter value.  If the value is SQL NULL, the result 
  192.          * is 0.
  193.          * @exception SQLException if a database access error occurs
  194.          */
  195.         float getFloat(int parameterIndex) throws SQLException;
  196.  
  197.         /**
  198.          * Gets the value of a JDBC DOUBLE parameter as a <code>double</code>
  199.          * in the Java programming language.
  200.          * @param parameterIndex the first parameter is 1, the second is 2,
  201.          * and so on
  202.          * @return the parameter value.  If the value is SQL NULL, the result 
  203.          * is 0.
  204.          * @exception SQLException if a database access error occurs
  205.          */
  206.         double getDouble(int parameterIndex) throws SQLException;
  207.  
  208.         /** 
  209.          * Gets the value of a JDBC <code>NUMERIC</code> parameter as a 
  210.          * <code>java.math.BigDecimal</code> object with scale digits to
  211.          * the right of the decimal point.
  212.          * @param parameterIndex the first parameter is 1, the second is 2, 
  213.          * and so on
  214.          * @param scale the number of digits to the right of the decimal point 
  215.          * @return the parameter value.  If the value is SQL NULL, the result is
  216.          * <code>null</code>. 
  217.          * @exception SQLException if a database access error occurs
  218.          * @deprecated
  219.          */
  220.         BigDecimal getBigDecimal(int parameterIndex, int scale)
  221.           throws SQLException;
  222.  
  223.         /**
  224.          * Gets the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code> 
  225.          * parameter as an array of <code>byte</code> vlaures in the Java 
  226.          * programming language.
  227.          * @param parameterIndex the first parameter is 1, the second is 2, 
  228.          * and so on
  229.          * @return the parameter value.  If the value is SQL NULL, the result is 
  230.          *  <code>null</code>.
  231.          * @exception SQLException if a database access error occurs
  232.          */
  233.         byte[] getBytes(int parameterIndex) throws SQLException;
  234.  
  235.         /**
  236.          * Gets the value of a JDBC <code>DATE</code> parameter as a 
  237.          * <code>java.sql.Date</code> object.
  238.          * @param parameterIndex the first parameter is 1, the second is 2, 
  239.          * and so on
  240.          * @return the parameter value.  If the value is SQL NULL, the result 
  241.          * is <code>null</code>.
  242.          * @exception SQLException if a database access error occurs
  243.          */
  244.         java.sql.Date getDate(int parameterIndex) throws SQLException;
  245.  
  246.         /**
  247.          * Get the value of a JDBC <code>TIME</code> parameter as a 
  248.          * <code>java.sql.Time</code> object.
  249.          * @param parameterIndex the first parameter is 1, the second is 2, 
  250.          * and so on
  251.          * @return the parameter value.  If the value is SQL NULL, the result 
  252.          * is <code>null</code>.
  253.          * @exception SQLException if a database access error occurs
  254.          */
  255.         java.sql.Time getTime(int parameterIndex) throws SQLException;
  256.  
  257.         /**
  258.          * Gets the value of a JDBC <code>TIMESTAMP</code> parameter as a 
  259.          * <code>java.sql.Timestamp</code> object.
  260.          * @param parameterIndex the first parameter is 1, the second is 2, 
  261.          * and so on
  262.          * @return the parameter value.  If the value is SQL NULL, the result 
  263.          * is <code>null</code>.
  264.          * @exception SQLException if a database access error occurs
  265.          */
  266.         java.sql.Timestamp getTimestamp(int parameterIndex) 
  267.             throws SQLException;
  268.  
  269.         //----------------------------------------------------------------------
  270.         // Advanced features:
  271.  
  272.  
  273.         /**
  274.          * Gets the value of a parameter as an object in the Java 
  275.          * programming language.
  276.          * <p>
  277.          * This method returns a Java object whose type corresponds to the JDBC
  278.          * type that was registered for this parameter using the method
  279.          * <code>registerOutParameter</code>.  By registering the target JDBC
  280.          * type as <code>java.sql.Types.OTHER</code>, this method can be used
  281.          * to read database-specific abstract data types.
  282.          * @param parameterIndex The first parameter is 1, the second is 2, 
  283.          * and so on
  284.          * @return A <code>java.lang.Object</code> holding the OUT parameter value.
  285.          * @exception SQLException if a database access error occurs
  286.          * @see Types 
  287.          */
  288.         Object getObject(int parameterIndex) throws SQLException;
  289.  
  290.  
  291.         //--------------------------JDBC 2.0-----------------------------
  292.  
  293.         /**
  294.          * JDBC 2.0
  295.          *
  296.          * Gets the value of a JDBC <code>NUMERIC</code> parameter as a 
  297.          * <code>java.math.BigDecimal</code> object with as many digits to the
  298.          * right of the decimal point as the value contains.
  299.          * @param parameterIndex the first parameter is 1, the second is 2,
  300.          * and so on
  301.          * @return the parameter value in full precision.  If the value is 
  302.          * SQL NULL, the result is <code>null</code>. 
  303.          * @exception SQLException if a database access error occurs
  304.          */
  305.         BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
  306.  
  307.         /**
  308.          * JDBC 2.0
  309.          *
  310.          * Returns an object representing the value of OUT parameter 
  311.          * <code>i</code> and uses <code>map</code> for the custom
  312.          * mapping of the parameter value.
  313.          * <p>
  314.          * This method returns a Java object whose type corresponds to the
  315.          * JDBC type that was registered for this parameter using the method
  316.          * <code>registerOutParameter</code>.  By registering the target
  317.          * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
  318.          * be used to read database-specific abstract data types.  
  319.          * @param i the first parameter is 1, the second is 2, and so on
  320.          * @param map the mapping from SQL type names to Java classes
  321.          * @return a java.lang.Object holding the OUT parameter value.
  322.          * @exception SQLException if a database access error occurs
  323.          */
  324.          Object  getObject (int i, java.util.Map map) throws SQLException;
  325.  
  326.         /**
  327.          * JDBC 2.0
  328.          *
  329.          * Gets the value of a JDBC <code>REF(<structured-type>)</code>
  330.          * parameter as a {@link Ref} object in the Java programming language.
  331.          * @param i the first parameter is 1, the second is 2, 
  332.          * and so on
  333.          * @return the parameter value as a <code>Ref</code> object in the
  334.          * Java programming language.  If the value was SQL NULL, the value
  335.          * <code>null</code> is returned.
  336.          * @exception SQLException if a database access error occurs
  337.          */
  338.          Ref getRef (int i) throws SQLException;
  339.  
  340.         /**
  341.          * JDBC 2.0
  342.          *
  343.          * Gets the value of a JDBC <code>BLOB</code> parameter as a
  344.          * {@link Blob} object in the Java programming language.
  345.          * @param i the first parameter is 1, the second is 2, and so on
  346.          * @return the parameter value as a <code>Blob</code> object in the
  347.          * Java programming language.  If the value was SQL NULL, the value
  348.          * <code>null</code> is returned.
  349.          * @exception SQLException if a database access error occurs
  350.          */
  351.          Blob getBlob (int i) throws SQLException;
  352.  
  353.         /**
  354.          * JDBC 2.0
  355.          *
  356.          * Gets the value of a JDBC <code>CLOB</code> parameter as a
  357.          * <code>Clob</code> object in the Java programming language.
  358.          * @param i the first parameter is 1, the second is 2, and
  359.          * so on
  360.          * @return the parameter value as a <code>Clob</code> object in the
  361.          * Java programming language.  If the value was SQL NULL, the
  362.          * value <code>null</code> is returned.
  363.          * @exception SQLException if a database access error occurs
  364.          */
  365.          Clob getClob (int i) throws SQLException;
  366.  
  367.         /**
  368.          * JDBC 2.0
  369.          *
  370.          * Gets the value of a JDBC <code>ARRAY</code> parameter as an
  371.          * {@link Array} object in the Java programming language.
  372.          * @param i the first parameter is 1, the second is 2, and 
  373.          * so on
  374.          * @return the parameter value as an <code>Array</code> object in
  375.          * the Java programming language.  If the value was SQL NULL, the
  376.          * value <code>null</code> is returned.
  377.          * @exception SQLException if a database access error occurs
  378.          */
  379.          Array getArray (int i) throws SQLException;
  380.  
  381.         /**
  382.          * Gets the value of a JDBC <code>DATE</code> parameter as a 
  383.          * <code>java.sql.Date</code> object, using
  384.          * the given <code>Calendar</code> object
  385.          * to construct the date.
  386.          * With a <code>Calendar</code> object, the driver
  387.          * can calculate the date taking into account a custom timezone and locale.
  388.          * If no <code>Calendar</code> object is specified, the driver uses the
  389.          * default timezone and locale.
  390.          *
  391.          * @param parameterIndex the first parameter is 1, the second is 2, 
  392.          * and so on
  393.          * @param cal the <code>Calendar</code> object the driver will use
  394.          *            to construct the date
  395.          * @return the parameter value.  If the value is SQL NULL, the result is 
  396.          * <code>null</code>.
  397.          * @exception SQLException if a database access error occurs
  398.          */
  399.         java.sql.Date getDate(int parameterIndex, Calendar cal) 
  400.           throws SQLException;
  401.  
  402.         /**
  403.          * Gets the value of a JDBC <code>TIME</code> parameter as a 
  404.          * <code>java.sql.Time</code> object, using
  405.          * the given <code>Calendar</code> object
  406.          * to construct the time.
  407.          * With a <code>Calendar</code> object, the driver
  408.          * can calculate the time taking into account a custom timezone and locale.
  409.          * If no <code>Calendar</code> object is specified, the driver uses the
  410.          * default timezone and locale.
  411.          *
  412.          * @param parameterIndex the first parameter is 1, the second is 2,
  413.          * and so on
  414.          * @param cal the <code>Calendar</code> object the driver will use
  415.          *            to construct the time
  416.          * @return the parameter value; if the value is SQL NULL, the result is 
  417.          * <code>null</code>.
  418.          * @exception SQLException if a database access error occurs
  419.          */
  420.         java.sql.Time getTime(int parameterIndex, Calendar cal) 
  421.           throws SQLException;
  422.  
  423.         /**
  424.          * Gets the value of a JDBC <code>TIMESTAMP</code> parameter as a
  425.          * <code>java.sql.Timestamp</code> object, using
  426.          * the given <code>Calendar</code> object to construct
  427.          * the <code>Timestamp</code> object.
  428.          * With a <code>Calendar</code> object, the driver
  429.          * can calculate the timestamp taking into account a custom timezone and locale.
  430.          * If no <code>Calendar</code> object is specified, the driver uses the
  431.          * default timezone and locale.
  432.          *
  433.          *
  434.          * @param parameterIndex the first parameter is 1, the second is 2, 
  435.          * and so on
  436.          * @param cal the <code>Calendar</code> object the driver will use
  437.          *            to construct the timestamp
  438.          * @return the parameter value.  If the value is SQL NULL, the result is 
  439.          * <code>null</code>.
  440.          * @exception SQLException if a database access error occurs
  441.          */
  442.         java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal) 
  443.           throws SQLException;
  444.  
  445.  
  446.         /**
  447.          * JDBC 2.0
  448.          *
  449.          * Registers the designated output parameter.  This version of 
  450.          * the method <code>registerOutParameter</code>
  451.          * should be used for a user-named or REF output parameter.  Examples
  452.          * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
  453.          * named array types.
  454.          *
  455.          * Before executing a stored procedure call, you must explicitly
  456.          * call <code>registerOutParameter</code> to register the type from
  457.          * <code>java.sql.Types</code> for each
  458.          * OUT parameter.  For a user-named parameter the fully-qualified SQL
  459.          * type name of the parameter should also be given, while a REF
  460.          * parameter requires that the fully-qualified type name of the
  461.          * referenced type be given.  A JDBC driver that does not need the
  462.          * type code and type name information may ignore it.   To be portable,
  463.          * however, applications should always provide these values for
  464.          * user-named and REF parameters.
  465.          *
  466.          * Although it is intended for user-named and REF parameters,
  467.          * this method may be used to register a parameter of any JDBC type.
  468.          * If the parameter does not have a user-named or REF type, the
  469.          * typeName parameter is ignored.
  470.          *
  471.          * <P><B>Note:</B> When reading the value of an out parameter, you
  472.          * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
  473.          * parameter's registered SQL type.
  474.          *
  475.          * @param parameterIndex the first parameter is 1, the second is 2,...
  476.          * @param sqlType a value from {@link java.sql.Types}
  477.          * @param typeName the fully-qualified name of an SQL structured type
  478.          * @exception SQLException if a database-access error occurs
  479.          * @see Types
  480.          */
  481.         void registerOutParameter (int paramIndex, int sqlType, String typeName)
  482.           throws SQLException;
  483. }
  484.  
  485.  
  486.  
  487.  
  488.