0001: /*
0002: * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
0003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004: *
0005: * This code is free software; you can redistribute it and/or modify it
0006: * under the terms of the GNU General Public License version 2 only, as
0007: * published by the Free Software Foundation. Sun designates this
0008: * particular file as subject to the "Classpath" exception as provided
0009: * by Sun in the LICENSE file that accompanied this code.
0010: *
0011: * This code is distributed in the hope that it will be useful, but WITHOUT
0012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014: * version 2 for more details (a copy is included in the LICENSE file that
0015: * accompanied this code).
0016: *
0017: * You should have received a copy of the GNU General Public License version
0018: * 2 along with this work; if not, write to the Free Software Foundation,
0019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020: *
0021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022: * CA 95054 USA or visit www.sun.com if you need additional information or
0023: * have any questions.
0024: */
0025:
0026: package java.sql;
0027:
0028: import java.math.BigDecimal;
0029: import java.util.Calendar;
0030: import java.io.Reader;
0031: import java.io.InputStream;
0032:
0033: /**
0034: * The interface used to execute SQL stored procedures. The JDBC API
0035: * provides a stored procedure SQL escape syntax that allows stored procedures
0036: * to be called in a standard way for all RDBMSs. This escape syntax has one
0037: * form that includes a result parameter and one that does not. If used, the result
0038: * parameter must be registered as an OUT parameter. The other parameters
0039: * can be used for input, output or both. Parameters are referred to
0040: * sequentially, by number, with the first parameter being 1.
0041: * <PRE>
0042: * {?= call <procedure-name>[(<arg1>,<arg2>, ...)]}
0043: * {call <procedure-name>[(<arg1>,<arg2>, ...)]}
0044: * </PRE>
0045: * <P>
0046: * IN parameter values are set using the <code>set</code> methods inherited from
0047: * {@link PreparedStatement}. The type of all OUT parameters must be
0048: * registered prior to executing the stored procedure; their values
0049: * are retrieved after execution via the <code>get</code> methods provided here.
0050: * <P>
0051: * A <code>CallableStatement</code> can return one {@link ResultSet} object or
0052: * multiple <code>ResultSet</code> objects. Multiple
0053: * <code>ResultSet</code> objects are handled using operations
0054: * inherited from {@link Statement}.
0055: * <P>
0056: * For maximum portability, a call's <code>ResultSet</code> objects and
0057: * update counts should be processed prior to getting the values of output
0058: * parameters.
0059: * <P>
0060: *
0061: * @see Connection#prepareCall
0062: * @see ResultSet
0063: */
0064:
0065: public interface CallableStatement extends PreparedStatement {
0066:
0067: /**
0068: * Registers the OUT parameter in ordinal position
0069: * <code>parameterIndex</code> to the JDBC type
0070: * <code>sqlType</code>. All OUT parameters must be registered
0071: * before a stored procedure is executed.
0072: * <p>
0073: * The JDBC type specified by <code>sqlType</code> for an OUT
0074: * parameter determines the Java type that must be used
0075: * in the <code>get</code> method to read the value of that parameter.
0076: * <p>
0077: * If the JDBC type expected to be returned to this output parameter
0078: * is specific to this particular database, <code>sqlType</code>
0079: * should be <code>java.sql.Types.OTHER</code>. The method
0080: * {@link #getObject} retrieves the value.
0081: *
0082: * @param parameterIndex the first parameter is 1, the second is 2,
0083: * and so on
0084: * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
0085: * If the parameter is of JDBC type <code>NUMERIC</code>
0086: * or <code>DECIMAL</code>, the version of
0087: * <code>registerOutParameter</code> that accepts a scale value
0088: * should be used.
0089: *
0090: * @exception SQLException if the parameterIndex is not valid;
0091: * if a database access error occurs or
0092: * this method is called on a closed <code>CallableStatement</code>
0093: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0094: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0095: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0096: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0097: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0098: * or <code>STRUCT</code> data type and the JDBC driver does not support
0099: * this data type
0100: * @see Types
0101: */
0102: void registerOutParameter(int parameterIndex, int sqlType)
0103: throws SQLException;
0104:
0105: /**
0106: * Registers the parameter in ordinal position
0107: * <code>parameterIndex</code> to be of JDBC type
0108: * <code>sqlType</code>. All OUT parameters must be registered
0109: * before a stored procedure is executed.
0110: * <p>
0111: * The JDBC type specified by <code>sqlType</code> for an OUT
0112: * parameter determines the Java type that must be used
0113: * in the <code>get</code> method to read the value of that parameter.
0114: * <p>
0115: * This version of <code>registerOutParameter</code> should be
0116: * used when the parameter is of JDBC type <code>NUMERIC</code>
0117: * or <code>DECIMAL</code>.
0118: *
0119: * @param parameterIndex the first parameter is 1, the second is 2,
0120: * and so on
0121: * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
0122: * @param scale the desired number of digits to the right of the
0123: * decimal point. It must be greater than or equal to zero.
0124: * @exception SQLException if the parameterIndex is not valid;
0125: * if a database access error occurs or
0126: * this method is called on a closed <code>CallableStatement</code>
0127: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0128: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0129: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0130: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0131: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0132: * or <code>STRUCT</code> data type and the JDBC driver does not support
0133: * this data type
0134: * @see Types
0135: */
0136: void registerOutParameter(int parameterIndex, int sqlType, int scale)
0137: throws SQLException;
0138:
0139: /**
0140: * Retrieves whether the last OUT parameter read had the value of
0141: * SQL <code>NULL</code>. Note that this method should be called only after
0142: * calling a getter method; otherwise, there is no value to use in
0143: * determining whether it is <code>null</code> or not.
0144: *
0145: * @return <code>true</code> if the last parameter read was SQL
0146: * <code>NULL</code>; <code>false</code> otherwise
0147: * @exception SQLException if a database access error occurs or
0148: * this method is called on a closed <code>CallableStatement</code>
0149: */
0150: boolean wasNull() throws SQLException;
0151:
0152: /**
0153: * Retrieves the value of the designated JDBC <code>CHAR</code>,
0154: * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
0155: * <code>String</code> in the Java programming language.
0156: * <p>
0157: * For the fixed-length type JDBC <code>CHAR</code>,
0158: * the <code>String</code> object
0159: * returned has exactly the same value the SQL
0160: * <code>CHAR</code> value had in the
0161: * database, including any padding added by the database.
0162: *
0163: * @param parameterIndex the first parameter is 1, the second is 2,
0164: * and so on
0165: * @return the parameter value. If the value is SQL <code>NULL</code>,
0166: * the result
0167: * is <code>null</code>.
0168: * @exception SQLException if the parameterIndex is not valid;
0169: * if a database access error occurs or
0170: * this method is called on a closed <code>CallableStatement</code>
0171: * @see #setString
0172: */
0173: String getString(int parameterIndex) throws SQLException;
0174:
0175: /**
0176: * Retrieves the value of the designated JDBC <code>BIT</code>
0177: * or <code>BOOLEAN</code> parameter as a
0178: * <code>boolean</code> in the Java programming language.
0179: *
0180: * @param parameterIndex the first parameter is 1, the second is 2,
0181: * and so on
0182: * @return the parameter value. If the value is SQL <code>NULL</code>,
0183: * the result is <code>false</code>.
0184: * @exception SQLException if the parameterIndex is not valid;
0185: * if a database access error occurs or
0186: * this method is called on a closed <code>CallableStatement</code>
0187: * @see #setBoolean
0188: */
0189: boolean getBoolean(int parameterIndex) throws SQLException;
0190:
0191: /**
0192: * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
0193: * as a <code>byte</code> in the Java programming language.
0194: *
0195: * @param parameterIndex the first parameter is 1, the second is 2,
0196: * and so on
0197: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0198: * is <code>0</code>.
0199: * @exception SQLException if the parameterIndex is not valid;
0200: * if a database access error occurs or
0201: * this method is called on a closed <code>CallableStatement</code>
0202: * @see #setByte
0203: */
0204: byte getByte(int parameterIndex) throws SQLException;
0205:
0206: /**
0207: * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
0208: * as a <code>short</code> in the Java programming language.
0209: *
0210: * @param parameterIndex the first parameter is 1, the second is 2,
0211: * and so on
0212: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0213: * is <code>0</code>.
0214: * @exception SQLException if the parameterIndex is not valid;
0215: * if a database access error occurs or
0216: * this method is called on a closed <code>CallableStatement</code>
0217: * @see #setShort
0218: */
0219: short getShort(int parameterIndex) throws SQLException;
0220:
0221: /**
0222: * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
0223: * as an <code>int</code> in the Java programming language.
0224: *
0225: * @param parameterIndex the first parameter is 1, the second is 2,
0226: * and so on
0227: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0228: * is <code>0</code>.
0229: * @exception SQLException if the parameterIndex is not valid;
0230: * if a database access error occurs or
0231: * this method is called on a closed <code>CallableStatement</code>
0232: * @see #setInt
0233: */
0234: int getInt(int parameterIndex) throws SQLException;
0235:
0236: /**
0237: * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
0238: * as a <code>long</code> in the Java programming language.
0239: *
0240: * @param parameterIndex the first parameter is 1, the second is 2,
0241: * and so on
0242: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0243: * is <code>0</code>.
0244: * @exception SQLException if the parameterIndex is not valid;
0245: * if a database access error occurs or
0246: * this method is called on a closed <code>CallableStatement</code>
0247: * @see #setLong
0248: */
0249: long getLong(int parameterIndex) throws SQLException;
0250:
0251: /**
0252: * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
0253: * as a <code>float</code> in the Java programming language.
0254: *
0255: * @param parameterIndex the first parameter is 1, the second is 2,
0256: * and so on
0257: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0258: * is <code>0</code>.
0259: * @exception SQLException if the parameterIndex is not valid;
0260: * if a database access error occurs or
0261: * this method is called on a closed <code>CallableStatement</code>
0262: * @see #setFloat
0263: */
0264: float getFloat(int parameterIndex) throws SQLException;
0265:
0266: /**
0267: * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
0268: * in the Java programming language.
0269: * @param parameterIndex the first parameter is 1, the second is 2,
0270: * and so on
0271: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0272: * is <code>0</code>.
0273: * @exception SQLException if the parameterIndex is not valid;
0274: * if a database access error occurs or
0275: * this method is called on a closed <code>CallableStatement</code>
0276: * @see #setDouble
0277: */
0278: double getDouble(int parameterIndex) throws SQLException;
0279:
0280: /**
0281: * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
0282: * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
0283: * the right of the decimal point.
0284: * @param parameterIndex the first parameter is 1, the second is 2,
0285: * and so on
0286: * @param scale the number of digits to the right of the decimal point
0287: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0288: * is <code>null</code>.
0289: * @exception SQLException if the parameterIndex is not valid;
0290: * if a database access error occurs or
0291: * this method is called on a closed <code>CallableStatement</code>
0292: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0293: * this method
0294: * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
0295: * or <code>getBigDecimal(String parameterName)</code>
0296: * @see #setBigDecimal
0297: */
0298: BigDecimal getBigDecimal(int parameterIndex, int scale)
0299: throws SQLException;
0300:
0301: /**
0302: * Retrieves the value of the designated JDBC <code>BINARY</code> or
0303: * <code>VARBINARY</code> parameter as an array of <code>byte</code>
0304: * values in the Java programming language.
0305: * @param parameterIndex the first parameter is 1, the second is 2,
0306: * and so on
0307: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0308: * is <code>null</code>.
0309: * @exception SQLException if the parameterIndex is not valid;
0310: * if a database access error occurs or
0311: * this method is called on a closed <code>CallableStatement</code>
0312: * @see #setBytes
0313: */
0314: byte[] getBytes(int parameterIndex) throws SQLException;
0315:
0316: /**
0317: * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
0318: * <code>java.sql.Date</code> object.
0319: * @param parameterIndex the first parameter is 1, the second is 2,
0320: * and so on
0321: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0322: * is <code>null</code>.
0323: * @exception SQLException if the parameterIndex is not valid;
0324: * if a database access error occurs or
0325: * this method is called on a closed <code>CallableStatement</code>
0326: * @see #setDate
0327: */
0328: java.sql.Date getDate(int parameterIndex) throws SQLException;
0329:
0330: /**
0331: * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
0332: * <code>java.sql.Time</code> object.
0333: *
0334: * @param parameterIndex the first parameter is 1, the second is 2,
0335: * and so on
0336: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0337: * is <code>null</code>.
0338: * @exception SQLException if the parameterIndex is not valid;
0339: * if a database access error occurs or
0340: * this method is called on a closed <code>CallableStatement</code>
0341: * @see #setTime
0342: */
0343: java.sql.Time getTime(int parameterIndex) throws SQLException;
0344:
0345: /**
0346: * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
0347: * <code>java.sql.Timestamp</code> object.
0348: *
0349: * @param parameterIndex the first parameter is 1, the second is 2,
0350: * and so on
0351: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0352: * is <code>null</code>.
0353: * @exception SQLException if the parameterIndex is not valid;
0354: * if a database access error occurs or
0355: * this method is called on a closed <code>CallableStatement</code>
0356: * @see #setTimestamp
0357: */
0358: java.sql.Timestamp getTimestamp(int parameterIndex)
0359: throws SQLException;
0360:
0361: //----------------------------------------------------------------------
0362: // Advanced features:
0363:
0364: /**
0365: * Retrieves the value of the designated parameter as an <code>Object</code>
0366: * in the Java programming language. If the value is an SQL <code>NULL</code>,
0367: * the driver returns a Java <code>null</code>.
0368: * <p>
0369: * This method returns a Java object whose type corresponds to the JDBC
0370: * type that was registered for this parameter using the method
0371: * <code>registerOutParameter</code>. By registering the target JDBC
0372: * type as <code>java.sql.Types.OTHER</code>, this method can be used
0373: * to read database-specific abstract data types.
0374: *
0375: * @param parameterIndex the first parameter is 1, the second is 2,
0376: * and so on
0377: * @return A <code>java.lang.Object</code> holding the OUT parameter value
0378: * @exception SQLException if the parameterIndex is not valid;
0379: * if a database access error occurs or
0380: * this method is called on a closed <code>CallableStatement</code>
0381: * @see Types
0382: * @see #setObject
0383: */
0384: Object getObject(int parameterIndex) throws SQLException;
0385:
0386: //--------------------------JDBC 2.0-----------------------------
0387:
0388: /**
0389: * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
0390: * <code>java.math.BigDecimal</code> object with as many digits to the
0391: * right of the decimal point as the value contains.
0392: * @param parameterIndex the first parameter is 1, the second is 2,
0393: * and so on
0394: * @return the parameter value in full precision. If the value is
0395: * SQL <code>NULL</code>, the result is <code>null</code>.
0396: * @exception SQLException if the parameterIndex is not valid;
0397: * if a database access error occurs or
0398: * this method is called on a closed <code>CallableStatement</code>
0399: * @see #setBigDecimal
0400: * @since 1.2
0401: */
0402: BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
0403:
0404: /**
0405: * Returns an object representing the value of OUT parameter
0406: * <code>parameterIndex</code> and uses <code>map</code> for the custom
0407: * mapping of the parameter value.
0408: * <p>
0409: * This method returns a Java object whose type corresponds to the
0410: * JDBC type that was registered for this parameter using the method
0411: * <code>registerOutParameter</code>. By registering the target
0412: * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
0413: * be used to read database-specific abstract data types.
0414: * @param parameterIndex the first parameter is 1, the second is 2, and so on
0415: * @param map the mapping from SQL type names to Java classes
0416: * @return a <code>java.lang.Object</code> holding the OUT parameter value
0417: * @exception SQLException if the parameterIndex is not valid;
0418: * if a database access error occurs or
0419: * this method is called on a closed <code>CallableStatement</code>
0420: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0421: * this method
0422: * @see #setObject
0423: * @since 1.2
0424: */
0425: Object getObject(int parameterIndex,
0426: java.util.Map<String, Class<?>> map) throws SQLException;
0427:
0428: /**
0429: * Retrieves the value of the designated JDBC <code>REF(<structured-type>)</code>
0430: * parameter as a {@link java.sql.Ref} object in the Java programming language.
0431: * @param parameterIndex the first parameter is 1, the second is 2,
0432: * and so on
0433: * @return the parameter value as a <code>Ref</code> object in the
0434: * Java programming language. If the value was SQL <code>NULL</code>, the value
0435: * <code>null</code> is returned.
0436: * @exception SQLException if the parameterIndex is not valid;
0437: * if a database access error occurs or
0438: * this method is called on a closed <code>CallableStatement</code>
0439: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0440: * this method
0441: * @since 1.2
0442: */
0443: Ref getRef(int parameterIndex) throws SQLException;
0444:
0445: /**
0446: * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
0447: * {@link java.sql.Blob} object in the Java programming language.
0448: * @param parameterIndex the first parameter is 1, the second is 2, and so on
0449: * @return the parameter value as a <code>Blob</code> object in the
0450: * Java programming language. If the value was SQL <code>NULL</code>, the value
0451: * <code>null</code> is returned.
0452: * @exception SQLException if the parameterIndex is not valid;
0453: * if a database access error occurs or
0454: * this method is called on a closed <code>CallableStatement</code>
0455: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0456: * this method
0457: * @since 1.2
0458: */
0459: Blob getBlob(int parameterIndex) throws SQLException;
0460:
0461: /**
0462: * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
0463: * <code>java.sql.Clob</code> object in the Java programming language.
0464: * @param parameterIndex the first parameter is 1, the second is 2, and
0465: * so on
0466: * @return the parameter value as a <code>Clob</code> object in the
0467: * Java programming language. If the value was SQL <code>NULL</code>, the
0468: * value <code>null</code> is returned.
0469: * @exception SQLException if the parameterIndex is not valid;
0470: * if a database access error occurs or
0471: * this method is called on a closed <code>CallableStatement</code>
0472: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0473: * this method
0474: * @since 1.2
0475: */
0476: Clob getClob(int parameterIndex) throws SQLException;
0477:
0478: /**
0479: *
0480: * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
0481: * {@link java.sql.Array} object in the Java programming language.
0482: * @param parameterIndex the first parameter is 1, the second is 2, and
0483: * so on
0484: * @return the parameter value as an <code>Array</code> object in
0485: * the Java programming language. If the value was SQL <code>NULL</code>, the
0486: * value <code>null</code> is returned.
0487: * @exception SQLException if the parameterIndex is not valid;
0488: * if a database access error occurs or
0489: * this method is called on a closed <code>CallableStatement</code>
0490: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0491: * this method
0492: * @since 1.2
0493: */
0494: Array getArray(int parameterIndex) throws SQLException;
0495:
0496: /**
0497: * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
0498: * <code>java.sql.Date</code> object, using
0499: * the given <code>Calendar</code> object
0500: * to construct the date.
0501: * With a <code>Calendar</code> object, the driver
0502: * can calculate the date taking into account a custom timezone and locale.
0503: * If no <code>Calendar</code> object is specified, the driver uses the
0504: * default timezone and locale.
0505: *
0506: * @param parameterIndex the first parameter is 1, the second is 2,
0507: * and so on
0508: * @param cal the <code>Calendar</code> object the driver will use
0509: * to construct the date
0510: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0511: * is <code>null</code>.
0512: * @exception SQLException if the parameterIndex is not valid;
0513: * if a database access error occurs or
0514: * this method is called on a closed <code>CallableStatement</code>
0515: * @see #setDate
0516: * @since 1.2
0517: */
0518: java.sql.Date getDate(int parameterIndex, Calendar cal)
0519: throws SQLException;
0520:
0521: /**
0522: * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
0523: * <code>java.sql.Time</code> object, using
0524: * the given <code>Calendar</code> object
0525: * to construct the time.
0526: * With a <code>Calendar</code> object, the driver
0527: * can calculate the time taking into account a custom timezone and locale.
0528: * If no <code>Calendar</code> object is specified, the driver uses the
0529: * default timezone and locale.
0530: *
0531: * @param parameterIndex the first parameter is 1, the second is 2,
0532: * and so on
0533: * @param cal the <code>Calendar</code> object the driver will use
0534: * to construct the time
0535: * @return the parameter value; if the value is SQL <code>NULL</code>, the result
0536: * is <code>null</code>.
0537: * @exception SQLException if the parameterIndex is not valid;
0538: * if a database access error occurs or
0539: * this method is called on a closed <code>CallableStatement</code>
0540: * @see #setTime
0541: * @since 1.2
0542: */
0543: java.sql.Time getTime(int parameterIndex, Calendar cal)
0544: throws SQLException;
0545:
0546: /**
0547: * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
0548: * <code>java.sql.Timestamp</code> object, using
0549: * the given <code>Calendar</code> object to construct
0550: * the <code>Timestamp</code> object.
0551: * With a <code>Calendar</code> object, the driver
0552: * can calculate the timestamp taking into account a custom timezone and locale.
0553: * If no <code>Calendar</code> object is specified, the driver uses the
0554: * default timezone and locale.
0555: *
0556: *
0557: * @param parameterIndex the first parameter is 1, the second is 2,
0558: * and so on
0559: * @param cal the <code>Calendar</code> object the driver will use
0560: * to construct the timestamp
0561: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0562: * is <code>null</code>.
0563: * @exception SQLException if the parameterIndex is not valid;
0564: * if a database access error occurs or
0565: * this method is called on a closed <code>CallableStatement</code>
0566: * @see #setTimestamp
0567: * @since 1.2
0568: */
0569: java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
0570: throws SQLException;
0571:
0572: /**
0573: * Registers the designated output parameter.
0574: * This version of
0575: * the method <code>registerOutParameter</code>
0576: * should be used for a user-defined or <code>REF</code> output parameter. Examples
0577: * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
0578: * <code>JAVA_OBJECT</code>, and named array types.
0579: *<p>
0580: * All OUT parameters must be registered
0581: * before a stored procedure is executed.
0582: * <p> For a user-defined parameter, the fully-qualified SQL
0583: * type name of the parameter should also be given, while a <code>REF</code>
0584: * parameter requires that the fully-qualified type name of the
0585: * referenced type be given. A JDBC driver that does not need the
0586: * type code and type name information may ignore it. To be portable,
0587: * however, applications should always provide these values for
0588: * user-defined and <code>REF</code> parameters.
0589: *
0590: * Although it is intended for user-defined and <code>REF</code> parameters,
0591: * this method may be used to register a parameter of any JDBC type.
0592: * If the parameter does not have a user-defined or <code>REF</code> type, the
0593: * <i>typeName</i> parameter is ignored.
0594: *
0595: * <P><B>Note:</B> When reading the value of an out parameter, you
0596: * must use the getter method whose Java type corresponds to the
0597: * parameter's registered SQL type.
0598: *
0599: * @param parameterIndex the first parameter is 1, the second is 2,...
0600: * @param sqlType a value from {@link java.sql.Types}
0601: * @param typeName the fully-qualified name of an SQL structured type
0602: * @exception SQLException if the parameterIndex is not valid;
0603: * if a database access error occurs or
0604: * this method is called on a closed <code>CallableStatement</code>
0605: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0606: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0607: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0608: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0609: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0610: * or <code>STRUCT</code> data type and the JDBC driver does not support
0611: * this data type
0612: * @see Types
0613: * @since 1.2
0614: */
0615: void registerOutParameter(int parameterIndex, int sqlType,
0616: String typeName) throws SQLException;
0617:
0618: //--------------------------JDBC 3.0-----------------------------
0619:
0620: /**
0621: * Registers the OUT parameter named
0622: * <code>parameterName</code> to the JDBC type
0623: * <code>sqlType</code>. All OUT parameters must be registered
0624: * before a stored procedure is executed.
0625: * <p>
0626: * The JDBC type specified by <code>sqlType</code> for an OUT
0627: * parameter determines the Java type that must be used
0628: * in the <code>get</code> method to read the value of that parameter.
0629: * <p>
0630: * If the JDBC type expected to be returned to this output parameter
0631: * is specific to this particular database, <code>sqlType</code>
0632: * should be <code>java.sql.Types.OTHER</code>. The method
0633: * {@link #getObject} retrieves the value.
0634: * @param parameterName the name of the parameter
0635: * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
0636: * If the parameter is of JDBC type <code>NUMERIC</code>
0637: * or <code>DECIMAL</code>, the version of
0638: * <code>registerOutParameter</code> that accepts a scale value
0639: * should be used.
0640: * @exception SQLException if parameterName does not correspond to a named
0641: * parameter; if a database access error occurs or
0642: * this method is called on a closed <code>CallableStatement</code>
0643: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0644: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0645: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0646: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0647: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0648: * or <code>STRUCT</code> data type and the JDBC driver does not support
0649: * this data type or if the JDBC driver does not support
0650: * this method
0651: * @since 1.4
0652: * @see Types
0653: */
0654: void registerOutParameter(String parameterName, int sqlType)
0655: throws SQLException;
0656:
0657: /**
0658: * Registers the parameter named
0659: * <code>parameterName</code> to be of JDBC type
0660: * <code>sqlType</code>. All OUT parameters must be registered
0661: * before a stored procedure is executed.
0662: * <p>
0663: * The JDBC type specified by <code>sqlType</code> for an OUT
0664: * parameter determines the Java type that must be used
0665: * in the <code>get</code> method to read the value of that parameter.
0666: * <p>
0667: * This version of <code>registerOutParameter</code> should be
0668: * used when the parameter is of JDBC type <code>NUMERIC</code>
0669: * or <code>DECIMAL</code>.
0670: *
0671: * @param parameterName the name of the parameter
0672: * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
0673: * @param scale the desired number of digits to the right of the
0674: * decimal point. It must be greater than or equal to zero.
0675: * @exception SQLException if parameterName does not correspond to a named
0676: * parameter; if a database access error occurs or
0677: * this method is called on a closed <code>CallableStatement</code>
0678: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0679: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0680: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0681: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0682: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0683: * or <code>STRUCT</code> data type and the JDBC driver does not support
0684: * this data type or if the JDBC driver does not support
0685: * this method
0686: * @since 1.4
0687: * @see Types
0688: */
0689: void registerOutParameter(String parameterName, int sqlType,
0690: int scale) throws SQLException;
0691:
0692: /**
0693: * Registers the designated output parameter. This version of
0694: * the method <code>registerOutParameter</code>
0695: * should be used for a user-named or REF output parameter. Examples
0696: * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
0697: * named array types.
0698: *<p>
0699: * All OUT parameters must be registered
0700: * before a stored procedure is executed.
0701: * <p>
0702: * For a user-named parameter the fully-qualified SQL
0703: * type name of the parameter should also be given, while a REF
0704: * parameter requires that the fully-qualified type name of the
0705: * referenced type be given. A JDBC driver that does not need the
0706: * type code and type name information may ignore it. To be portable,
0707: * however, applications should always provide these values for
0708: * user-named and REF parameters.
0709: *
0710: * Although it is intended for user-named and REF parameters,
0711: * this method may be used to register a parameter of any JDBC type.
0712: * If the parameter does not have a user-named or REF type, the
0713: * typeName parameter is ignored.
0714: *
0715: * <P><B>Note:</B> When reading the value of an out parameter, you
0716: * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
0717: * parameter's registered SQL type.
0718: *
0719: * @param parameterName the name of the parameter
0720: * @param sqlType a value from {@link java.sql.Types}
0721: * @param typeName the fully-qualified name of an SQL structured type
0722: * @exception SQLException if parameterName does not correspond to a named
0723: * parameter; if a database access error occurs or
0724: * this method is called on a closed <code>CallableStatement</code>
0725: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0726: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0727: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0728: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0729: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0730: * or <code>STRUCT</code> data type and the JDBC driver does not support
0731: * this data type or if the JDBC driver does not support
0732: * this method
0733: * @see Types
0734: * @since 1.4
0735: */
0736: void registerOutParameter(String parameterName, int sqlType,
0737: String typeName) throws SQLException;
0738:
0739: /**
0740: * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
0741: * <code>java.net.URL</code> object.
0742: *
0743: * @param parameterIndex the first parameter is 1, the second is 2,...
0744: * @return a <code>java.net.URL</code> object that represents the
0745: * JDBC <code>DATALINK</code> value used as the designated
0746: * parameter
0747: * @exception SQLException if the parameterIndex is not valid;
0748: * if a database access error occurs,
0749: * this method is called on a closed <code>CallableStatement</code>,
0750: * or if the URL being returned is
0751: * not a valid URL on the Java platform
0752: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0753: * this method
0754: * @see #setURL
0755: * @since 1.4
0756: */
0757: java.net.URL getURL(int parameterIndex) throws SQLException;
0758:
0759: /**
0760: * Sets the designated parameter to the given <code>java.net.URL</code> object.
0761: * The driver converts this to an SQL <code>DATALINK</code> value when
0762: * it sends it to the database.
0763: *
0764: * @param parameterName the name of the parameter
0765: * @param val the parameter value
0766: * @exception SQLException if parameterName does not correspond to a named
0767: * parameter; if a database access error occurs;
0768: * this method is called on a closed <code>CallableStatement</code>
0769: * or if a URL is malformed
0770: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0771: * this method
0772: * @see #getURL
0773: * @since 1.4
0774: */
0775: void setURL(String parameterName, java.net.URL val)
0776: throws SQLException;
0777:
0778: /**
0779: * Sets the designated parameter to SQL <code>NULL</code>.
0780: *
0781: * <P><B>Note:</B> You must specify the parameter's SQL type.
0782: *
0783: * @param parameterName the name of the parameter
0784: * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
0785: * @exception SQLException if parameterName does not correspond to a named
0786: * parameter; if a database access error occurs or
0787: * this method is called on a closed <code>CallableStatement</code>
0788: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0789: * this method
0790: * @since 1.4
0791: */
0792: void setNull(String parameterName, int sqlType) throws SQLException;
0793:
0794: /**
0795: * Sets the designated parameter to the given Java <code>boolean</code> value.
0796: * The driver converts this
0797: * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
0798: *
0799: * @param parameterName the name of the parameter
0800: * @param x the parameter value
0801: * @exception SQLException if parameterName does not correspond to a named
0802: * parameter; if a database access error occurs or
0803: * this method is called on a closed <code>CallableStatement</code>
0804: * @see #getBoolean
0805: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0806: * this method
0807: * @since 1.4
0808: */
0809: void setBoolean(String parameterName, boolean x)
0810: throws SQLException;
0811:
0812: /**
0813: * Sets the designated parameter to the given Java <code>byte</code> value.
0814: * The driver converts this
0815: * to an SQL <code>TINYINT</code> value when it sends it to the database.
0816: *
0817: * @param parameterName the name of the parameter
0818: * @param x the parameter value
0819: * @exception SQLException if parameterName does not correspond to a named
0820: * parameter; if a database access error occurs or
0821: * this method is called on a closed <code>CallableStatement</code>
0822: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0823: * this method
0824: * @see #getByte
0825: * @since 1.4
0826: */
0827: void setByte(String parameterName, byte x) throws SQLException;
0828:
0829: /**
0830: * Sets the designated parameter to the given Java <code>short</code> value.
0831: * The driver converts this
0832: * to an SQL <code>SMALLINT</code> value when it sends it to the database.
0833: *
0834: * @param parameterName the name of the parameter
0835: * @param x the parameter value
0836: * @exception SQLException if parameterName does not correspond to a named
0837: * parameter; if a database access error occurs or
0838: * this method is called on a closed <code>CallableStatement</code>
0839: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0840: * this method
0841: * @see #getShort
0842: * @since 1.4
0843: */
0844: void setShort(String parameterName, short x) throws SQLException;
0845:
0846: /**
0847: * Sets the designated parameter to the given Java <code>int</code> value.
0848: * The driver converts this
0849: * to an SQL <code>INTEGER</code> value when it sends it to the database.
0850: *
0851: * @param parameterName the name of the parameter
0852: * @param x the parameter value
0853: * @exception SQLException if parameterName does not correspond to a named
0854: * parameter; if a database access error occurs or
0855: * this method is called on a closed <code>CallableStatement</code>
0856: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0857: * this method
0858: * @see #getInt
0859: * @since 1.4
0860: */
0861: void setInt(String parameterName, int x) throws SQLException;
0862:
0863: /**
0864: * Sets the designated parameter to the given Java <code>long</code> value.
0865: * The driver converts this
0866: * to an SQL <code>BIGINT</code> value when it sends it to the database.
0867: *
0868: * @param parameterName the name of the parameter
0869: * @param x the parameter value
0870: * @exception SQLException if parameterName does not correspond to a named
0871: * parameter; if a database access error occurs or
0872: * this method is called on a closed <code>CallableStatement</code>
0873: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0874: * this method
0875: * @see #getLong
0876: * @since 1.4
0877: */
0878: void setLong(String parameterName, long x) throws SQLException;
0879:
0880: /**
0881: * Sets the designated parameter to the given Java <code>float</code> value.
0882: * The driver converts this
0883: * to an SQL <code>FLOAT</code> value when it sends it to the database.
0884: *
0885: * @param parameterName the name of the parameter
0886: * @param x the parameter value
0887: * @exception SQLException if parameterName does not correspond to a named
0888: * parameter; if a database access error occurs or
0889: * this method is called on a closed <code>CallableStatement</code>
0890: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0891: * this method
0892: * @see #getFloat
0893: * @since 1.4
0894: */
0895: void setFloat(String parameterName, float x) throws SQLException;
0896:
0897: /**
0898: * Sets the designated parameter to the given Java <code>double</code> value.
0899: * The driver converts this
0900: * to an SQL <code>DOUBLE</code> value when it sends it to the database.
0901: *
0902: * @param parameterName the name of the parameter
0903: * @param x the parameter value
0904: * @exception SQLException if parameterName does not correspond to a named
0905: * parameter; if a database access error occurs or
0906: * this method is called on a closed <code>CallableStatement</code>
0907: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0908: * this method
0909: * @see #getDouble
0910: * @since 1.4
0911: */
0912: void setDouble(String parameterName, double x) throws SQLException;
0913:
0914: /**
0915: * Sets the designated parameter to the given
0916: * <code>java.math.BigDecimal</code> value.
0917: * The driver converts this to an SQL <code>NUMERIC</code> value when
0918: * it sends it to the database.
0919: *
0920: * @param parameterName the name of the parameter
0921: * @param x the parameter value
0922: * @exception SQLException if parameterName does not correspond to a named
0923: * parameter; if a database access error occurs or
0924: * this method is called on a closed <code>CallableStatement</code>
0925: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0926: * this method
0927: * @see #getBigDecimal
0928: * @since 1.4
0929: */
0930: void setBigDecimal(String parameterName, BigDecimal x)
0931: throws SQLException;
0932:
0933: /**
0934: * Sets the designated parameter to the given Java <code>String</code> value.
0935: * The driver converts this
0936: * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
0937: * (depending on the argument's
0938: * size relative to the driver's limits on <code>VARCHAR</code> values)
0939: * when it sends it to the database.
0940: *
0941: * @param parameterName the name of the parameter
0942: * @param x the parameter value
0943: * @exception SQLException if parameterName does not correspond to a named
0944: * parameter; if a database access error occurs or
0945: * this method is called on a closed <code>CallableStatement</code>
0946: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0947: * this method
0948: * @see #getString
0949: * @since 1.4
0950: */
0951: void setString(String parameterName, String x) throws SQLException;
0952:
0953: /**
0954: * Sets the designated parameter to the given Java array of bytes.
0955: * The driver converts this to an SQL <code>VARBINARY</code> or
0956: * <code>LONGVARBINARY</code> (depending on the argument's size relative
0957: * to the driver's limits on <code>VARBINARY</code> values) when it sends
0958: * it to the database.
0959: *
0960: * @param parameterName the name of the parameter
0961: * @param x the parameter value
0962: * @exception SQLException if parameterName does not correspond to a named
0963: * parameter; if a database access error occurs or
0964: * this method is called on a closed <code>CallableStatement</code>
0965: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0966: * this method
0967: * @see #getBytes
0968: * @since 1.4
0969: */
0970: void setBytes(String parameterName, byte x[]) throws SQLException;
0971:
0972: /**
0973: * Sets the designated parameter to the given <code>java.sql.Date</code> value
0974: * using the default time zone of the virtual machine that is running
0975: * the application.
0976: * The driver converts this
0977: * to an SQL <code>DATE</code> value when it sends it to the database.
0978: *
0979: * @param parameterName the name of the parameter
0980: * @param x the parameter value
0981: * @exception SQLException if parameterName does not correspond to a named
0982: * parameter; if a database access error occurs or
0983: * this method is called on a closed <code>CallableStatement</code>
0984: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0985: * this method
0986: * @see #getDate
0987: * @since 1.4
0988: */
0989: void setDate(String parameterName, java.sql.Date x)
0990: throws SQLException;
0991:
0992: /**
0993: * Sets the designated parameter to the given <code>java.sql.Time</code> value.
0994: * The driver converts this
0995: * to an SQL <code>TIME</code> value when it sends it to the database.
0996: *
0997: * @param parameterName the name of the parameter
0998: * @param x the parameter value
0999: * @exception SQLException if parameterName does not correspond to a named
1000: * parameter; if a database access error occurs or
1001: * this method is called on a closed <code>CallableStatement</code>
1002: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1003: * this method
1004: * @see #getTime
1005: * @since 1.4
1006: */
1007: void setTime(String parameterName, java.sql.Time x)
1008: throws SQLException;
1009:
1010: /**
1011: * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
1012: * The driver
1013: * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
1014: * database.
1015: *
1016: * @param parameterName the name of the parameter
1017: * @param x the parameter value
1018: * @exception SQLException if parameterName does not correspond to a named
1019: * parameter; if a database access error occurs or
1020: * this method is called on a closed <code>CallableStatement</code>
1021: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1022: * this method
1023: * @see #getTimestamp
1024: * @since 1.4
1025: */
1026: void setTimestamp(String parameterName, java.sql.Timestamp x)
1027: throws SQLException;
1028:
1029: /**
1030: * Sets the designated parameter to the given input stream, which will have
1031: * the specified number of bytes.
1032: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1033: * parameter, it may be more practical to send it via a
1034: * <code>java.io.InputStream</code>. Data will be read from the stream
1035: * as needed until end-of-file is reached. The JDBC driver will
1036: * do any necessary conversion from ASCII to the database char format.
1037: *
1038: * <P><B>Note:</B> This stream object can either be a standard
1039: * Java stream object or your own subclass that implements the
1040: * standard interface.
1041: *
1042: * @param parameterName the name of the parameter
1043: * @param x the Java input stream that contains the ASCII parameter value
1044: * @param length the number of bytes in the stream
1045: * @exception SQLException if parameterName does not correspond to a named
1046: * parameter; if a database access error occurs or
1047: * this method is called on a closed <code>CallableStatement</code>
1048: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1049: * this method
1050: * @since 1.4
1051: */
1052: void setAsciiStream(String parameterName, java.io.InputStream x,
1053: int length) throws SQLException;
1054:
1055: /**
1056: * Sets the designated parameter to the given input stream, which will have
1057: * the specified number of bytes.
1058: * When a very large binary value is input to a <code>LONGVARBINARY</code>
1059: * parameter, it may be more practical to send it via a
1060: * <code>java.io.InputStream</code> object. The data will be read from the stream
1061: * as needed until end-of-file is reached.
1062: *
1063: * <P><B>Note:</B> This stream object can either be a standard
1064: * Java stream object or your own subclass that implements the
1065: * standard interface.
1066: *
1067: * @param parameterName the name of the parameter
1068: * @param x the java input stream which contains the binary parameter value
1069: * @param length the number of bytes in the stream
1070: * @exception SQLException if parameterName does not correspond to a named
1071: * parameter; if a database access error occurs or
1072: * this method is called on a closed <code>CallableStatement</code>
1073: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1074: * this method
1075: * @since 1.4
1076: */
1077: void setBinaryStream(String parameterName, java.io.InputStream x,
1078: int length) throws SQLException;
1079:
1080: /**
1081: * Sets the value of the designated parameter with the given object. The second
1082: * argument must be an object type; for integral values, the
1083: * <code>java.lang</code> equivalent objects should be used.
1084: *
1085: * <p>The given Java object will be converted to the given targetSqlType
1086: * before being sent to the database.
1087: *
1088: * If the object has a custom mapping (is of a class implementing the
1089: * interface <code>SQLData</code>),
1090: * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1091: * to the SQL data stream.
1092: * If, on the other hand, the object is of a class implementing
1093: * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1094: * <code>Struct</code>, <code>java.net.URL</code>,
1095: * or <code>Array</code>, the driver should pass it to the database as a
1096: * value of the corresponding SQL type.
1097: * <P>
1098: * Note that this method may be used to pass datatabase-
1099: * specific abstract data types.
1100: *
1101: * @param parameterName the name of the parameter
1102: * @param x the object containing the input parameter value
1103: * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1104: * sent to the database. The scale argument may further qualify this type.
1105: * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1106: * this is the number of digits after the decimal point. For all other
1107: * types, this value will be ignored.
1108: * @exception SQLException if parameterName does not correspond to a named
1109: * parameter; if a database access error occurs or
1110: * this method is called on a closed <code>CallableStatement</code>
1111: * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1112: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1113: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1114: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1115: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1116: * or <code>STRUCT</code> data type and the JDBC driver does not support
1117: * this data type
1118: * @see Types
1119: * @see #getObject
1120: * @since 1.4
1121: */
1122: void setObject(String parameterName, Object x, int targetSqlType,
1123: int scale) throws SQLException;
1124:
1125: /**
1126: * Sets the value of the designated parameter with the given object.
1127: * This method is like the method <code>setObject</code>
1128: * above, except that it assumes a scale of zero.
1129: *
1130: * @param parameterName the name of the parameter
1131: * @param x the object containing the input parameter value
1132: * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1133: * sent to the database
1134: * @exception SQLException if parameterName does not correspond to a named
1135: * parameter; if a database access error occurs or
1136: * this method is called on a closed <code>CallableStatement</code>
1137: * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1138: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1139: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1140: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1141: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1142: * or <code>STRUCT</code> data type and the JDBC driver does not support
1143: * this data type
1144: * @see #getObject
1145: * @since 1.4
1146: */
1147: void setObject(String parameterName, Object x, int targetSqlType)
1148: throws SQLException;
1149:
1150: /**
1151: * Sets the value of the designated parameter with the given object.
1152: * The second parameter must be of type <code>Object</code>; therefore, the
1153: * <code>java.lang</code> equivalent objects should be used for built-in types.
1154: *
1155: * <p>The JDBC specification specifies a standard mapping from
1156: * Java <code>Object</code> types to SQL types. The given argument
1157: * will be converted to the corresponding SQL type before being
1158: * sent to the database.
1159: * <p>Note that this method may be used to pass datatabase-
1160: * specific abstract data types, by using a driver-specific Java
1161: * type.
1162: *
1163: * If the object is of a class implementing the interface <code>SQLData</code>,
1164: * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1165: * to write it to the SQL data stream.
1166: * If, on the other hand, the object is of a class implementing
1167: * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1168: * <code>Struct</code>, <code>java.net.URL</code>,
1169: * or <code>Array</code>, the driver should pass it to the database as a
1170: * value of the corresponding SQL type.
1171: * <P>
1172: * This method throws an exception if there is an ambiguity, for example, if the
1173: * object is of a class implementing more than one of the interfaces named above.
1174: *<p>
1175: *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
1176: * the backend. For maximum portability, the <code>setNull</code> or the
1177: * <code>setObject(String parameterName, Object x, int sqlType)</code>
1178: * method should be used
1179: * instead of <code>setObject(String parameterName, Object x)</code>.
1180: *<p>
1181: * @param parameterName the name of the parameter
1182: * @param x the object containing the input parameter value
1183: * @exception SQLException if parameterName does not correspond to a named
1184: * parameter; if a database access error occurs,
1185: * this method is called on a closed <code>CallableStatement</code> or if the given
1186: * <code>Object</code> parameter is ambiguous
1187: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1188: * this method
1189: * @see #getObject
1190: * @since 1.4
1191: */
1192: void setObject(String parameterName, Object x) throws SQLException;
1193:
1194: /**
1195: * Sets the designated parameter to the given <code>Reader</code>
1196: * object, which is the given number of characters long.
1197: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1198: * parameter, it may be more practical to send it via a
1199: * <code>java.io.Reader</code> object. The data will be read from the stream
1200: * as needed until end-of-file is reached. The JDBC driver will
1201: * do any necessary conversion from UNICODE to the database char format.
1202: *
1203: * <P><B>Note:</B> This stream object can either be a standard
1204: * Java stream object or your own subclass that implements the
1205: * standard interface.
1206: *
1207: * @param parameterName the name of the parameter
1208: * @param reader the <code>java.io.Reader</code> object that
1209: * contains the UNICODE data used as the designated parameter
1210: * @param length the number of characters in the stream
1211: * @exception SQLException if parameterName does not correspond to a named
1212: * parameter; if a database access error occurs or
1213: * this method is called on a closed <code>CallableStatement</code>
1214: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1215: * this method
1216: * @since 1.4
1217: */
1218: void setCharacterStream(String parameterName,
1219: java.io.Reader reader, int length) throws SQLException;
1220:
1221: /**
1222: * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1223: * using the given <code>Calendar</code> object. The driver uses
1224: * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1225: * which the driver then sends to the database. With a
1226: * a <code>Calendar</code> object, the driver can calculate the date
1227: * taking into account a custom timezone. If no
1228: * <code>Calendar</code> object is specified, the driver uses the default
1229: * timezone, which is that of the virtual machine running the application.
1230: *
1231: * @param parameterName the name of the parameter
1232: * @param x the parameter value
1233: * @param cal the <code>Calendar</code> object the driver will use
1234: * to construct the date
1235: * @exception SQLException if parameterName does not correspond to a named
1236: * parameter; if a database access error occurs or
1237: * this method is called on a closed <code>CallableStatement</code>
1238: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1239: * this method
1240: * @see #getDate
1241: * @since 1.4
1242: */
1243: void setDate(String parameterName, java.sql.Date x, Calendar cal)
1244: throws SQLException;
1245:
1246: /**
1247: * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1248: * using the given <code>Calendar</code> object. The driver uses
1249: * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1250: * which the driver then sends to the database. With a
1251: * a <code>Calendar</code> object, the driver can calculate the time
1252: * taking into account a custom timezone. If no
1253: * <code>Calendar</code> object is specified, the driver uses the default
1254: * timezone, which is that of the virtual machine running the application.
1255: *
1256: * @param parameterName the name of the parameter
1257: * @param x the parameter value
1258: * @param cal the <code>Calendar</code> object the driver will use
1259: * to construct the time
1260: * @exception SQLException if parameterName does not correspond to a named
1261: * parameter; if a database access error occurs or
1262: * this method is called on a closed <code>CallableStatement</code>
1263: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1264: * this method
1265: * @see #getTime
1266: * @since 1.4
1267: */
1268: void setTime(String parameterName, java.sql.Time x, Calendar cal)
1269: throws SQLException;
1270:
1271: /**
1272: * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1273: * using the given <code>Calendar</code> object. The driver uses
1274: * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1275: * which the driver then sends to the database. With a
1276: * a <code>Calendar</code> object, the driver can calculate the timestamp
1277: * taking into account a custom timezone. If no
1278: * <code>Calendar</code> object is specified, the driver uses the default
1279: * timezone, which is that of the virtual machine running the application.
1280: *
1281: * @param parameterName the name of the parameter
1282: * @param x the parameter value
1283: * @param cal the <code>Calendar</code> object the driver will use
1284: * to construct the timestamp
1285: * @exception SQLException if parameterName does not correspond to a named
1286: * parameter; if a database access error occurs or
1287: * this method is called on a closed <code>CallableStatement</code>
1288: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1289: * this method
1290: * @see #getTimestamp
1291: * @since 1.4
1292: */
1293: void setTimestamp(String parameterName, java.sql.Timestamp x,
1294: Calendar cal) throws SQLException;
1295:
1296: /**
1297: * Sets the designated parameter to SQL <code>NULL</code>.
1298: * This version of the method <code>setNull</code> should
1299: * be used for user-defined types and REF type parameters. Examples
1300: * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
1301: * named array types.
1302: *
1303: * <P><B>Note:</B> To be portable, applications must give the
1304: * SQL type code and the fully-qualified SQL type name when specifying
1305: * a NULL user-defined or REF parameter. In the case of a user-defined type
1306: * the name is the type name of the parameter itself. For a REF
1307: * parameter, the name is the type name of the referenced type.
1308: * <p>
1309: * Although it is intended for user-defined and Ref parameters,
1310: * this method may be used to set a null parameter of any JDBC type.
1311: * If the parameter does not have a user-defined or REF type, the given
1312: * typeName is ignored.
1313: *
1314: *
1315: * @param parameterName the name of the parameter
1316: * @param sqlType a value from <code>java.sql.Types</code>
1317: * @param typeName the fully-qualified name of an SQL user-defined type;
1318: * ignored if the parameter is not a user-defined type or
1319: * SQL <code>REF</code> value
1320: * @exception SQLException if parameterName does not correspond to a named
1321: * parameter; if a database access error occurs or
1322: * this method is called on a closed <code>CallableStatement</code>
1323: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1324: * this method
1325: * @since 1.4
1326: */
1327: void setNull(String parameterName, int sqlType, String typeName)
1328: throws SQLException;
1329:
1330: /**
1331: * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
1332: * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
1333: * the Java programming language.
1334: * <p>
1335: * For the fixed-length type JDBC <code>CHAR</code>,
1336: * the <code>String</code> object
1337: * returned has exactly the same value the SQL
1338: * <code>CHAR</code> value had in the
1339: * database, including any padding added by the database.
1340: * @param parameterName the name of the parameter
1341: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1342: * is <code>null</code>.
1343: * @exception SQLException if parameterName does not correspond to a named
1344: * parameter; if a database access error occurs or
1345: * this method is called on a closed <code>CallableStatement</code>
1346: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1347: * this method
1348: * @see #setString
1349: * @since 1.4
1350: */
1351: String getString(String parameterName) throws SQLException;
1352:
1353: /**
1354: * Retrieves the value of a JDBC <code>BIT</code> or <code>BOOLEAN</code>
1355: * parameter as a
1356: * <code>boolean</code> in the Java programming language.
1357: * @param parameterName the name of the parameter
1358: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1359: * is <code>false</code>.
1360: * @exception SQLException if parameterName does not correspond to a named
1361: * parameter; if a database access error occurs or
1362: * this method is called on a closed <code>CallableStatement</code>
1363: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1364: * this method
1365: * @see #setBoolean
1366: * @since 1.4
1367: */
1368: boolean getBoolean(String parameterName) throws SQLException;
1369:
1370: /**
1371: * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
1372: * in the Java programming language.
1373: * @param parameterName the name of the parameter
1374: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1375: * is <code>0</code>.
1376: * @exception SQLException if parameterName does not correspond to a named
1377: * parameter; if a database access error occurs or
1378: * this method is called on a closed <code>CallableStatement</code>
1379: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1380: * this method
1381: * @see #setByte
1382: * @since 1.4
1383: */
1384: byte getByte(String parameterName) throws SQLException;
1385:
1386: /**
1387: * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
1388: * in the Java programming language.
1389: * @param parameterName the name of the parameter
1390: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1391: * is <code>0</code>.
1392: * @exception SQLException if parameterName does not correspond to a named
1393: * parameter; if a database access error occurs or
1394: * this method is called on a closed <code>CallableStatement</code>
1395: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1396: * this method
1397: * @see #setShort
1398: * @since 1.4
1399: */
1400: short getShort(String parameterName) throws SQLException;
1401:
1402: /**
1403: * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
1404: * in the Java programming language.
1405: *
1406: * @param parameterName the name of the parameter
1407: * @return the parameter value. If the value is SQL <code>NULL</code>,
1408: * the result is <code>0</code>.
1409: * @exception SQLException if parameterName does not correspond to a named
1410: * parameter; if a database access error occurs or
1411: * this method is called on a closed <code>CallableStatement</code>
1412: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1413: * this method
1414: * @see #setInt
1415: * @since 1.4
1416: */
1417: int getInt(String parameterName) throws SQLException;
1418:
1419: /**
1420: * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
1421: * in the Java programming language.
1422: *
1423: * @param parameterName the name of the parameter
1424: * @return the parameter value. If the value is SQL <code>NULL</code>,
1425: * the result is <code>0</code>.
1426: * @exception SQLException if parameterName does not correspond to a named
1427: * parameter; if a database access error occurs or
1428: * this method is called on a closed <code>CallableStatement</code>
1429: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1430: * this method
1431: * @see #setLong
1432: * @since 1.4
1433: */
1434: long getLong(String parameterName) throws SQLException;
1435:
1436: /**
1437: * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
1438: * in the Java programming language.
1439: * @param parameterName the name of the parameter
1440: * @return the parameter value. If the value is SQL <code>NULL</code>,
1441: * the result is <code>0</code>.
1442: * @exception SQLException if parameterName does not correspond to a named
1443: * parameter; if a database access error occurs or
1444: * this method is called on a closed <code>CallableStatement</code>
1445: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1446: * this method
1447: * @see #setFloat
1448: * @since 1.4
1449: */
1450: float getFloat(String parameterName) throws SQLException;
1451:
1452: /**
1453: * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
1454: * in the Java programming language.
1455: * @param parameterName the name of the parameter
1456: * @return the parameter value. If the value is SQL <code>NULL</code>,
1457: * the result is <code>0</code>.
1458: * @exception SQLException if parameterName does not correspond to a named
1459: * parameter; if a database access error occurs or
1460: * this method is called on a closed <code>CallableStatement</code>
1461: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1462: * this method
1463: * @see #setDouble
1464: * @since 1.4
1465: */
1466: double getDouble(String parameterName) throws SQLException;
1467:
1468: /**
1469: * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
1470: * parameter as an array of <code>byte</code> values in the Java
1471: * programming language.
1472: * @param parameterName the name of the parameter
1473: * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1474: * <code>null</code>.
1475: * @exception SQLException if parameterName does not correspond to a named
1476: * parameter; if a database access error occurs or
1477: * this method is called on a closed <code>CallableStatement</code>
1478: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1479: * this method
1480: * @see #setBytes
1481: * @since 1.4
1482: */
1483: byte[] getBytes(String parameterName) throws SQLException;
1484:
1485: /**
1486: * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1487: * <code>java.sql.Date</code> object.
1488: * @param parameterName the name of the parameter
1489: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1490: * is <code>null</code>.
1491: * @exception SQLException if parameterName does not correspond to a named
1492: * parameter; if a database access error occurs or
1493: * this method is called on a closed <code>CallableStatement</code>
1494: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1495: * this method
1496: * @see #setDate
1497: * @since 1.4
1498: */
1499: java.sql.Date getDate(String parameterName) throws SQLException;
1500:
1501: /**
1502: * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1503: * <code>java.sql.Time</code> object.
1504: * @param parameterName the name of the parameter
1505: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1506: * is <code>null</code>.
1507: * @exception SQLException if parameterName does not correspond to a named
1508: * parameter; if a database access error occurs or
1509: * this method is called on a closed <code>CallableStatement</code>
1510: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1511: * this method
1512: * @see #setTime
1513: * @since 1.4
1514: */
1515: java.sql.Time getTime(String parameterName) throws SQLException;
1516:
1517: /**
1518: * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1519: * <code>java.sql.Timestamp</code> object.
1520: * @param parameterName the name of the parameter
1521: * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1522: * is <code>null</code>.
1523: * @exception SQLException if parameterName does not correspond to a named
1524: * parameter; if a database access error occurs or
1525: * this method is called on a closed <code>CallableStatement</code>
1526: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1527: * this method
1528: * @see #setTimestamp
1529: * @since 1.4
1530: */
1531: java.sql.Timestamp getTimestamp(String parameterName)
1532: throws SQLException;
1533:
1534: /**
1535: * Retrieves the value of a parameter as an <code>Object</code> in the Java
1536: * programming language. If the value is an SQL <code>NULL</code>, the
1537: * driver returns a Java <code>null</code>.
1538: * <p>
1539: * This method returns a Java object whose type corresponds to the JDBC
1540: * type that was registered for this parameter using the method
1541: * <code>registerOutParameter</code>. By registering the target JDBC
1542: * type as <code>java.sql.Types.OTHER</code>, this method can be used
1543: * to read database-specific abstract data types.
1544: * @param parameterName the name of the parameter
1545: * @return A <code>java.lang.Object</code> holding the OUT parameter value.
1546: * @exception SQLException if parameterName does not correspond to a named
1547: * parameter; if a database access error occurs or
1548: * this method is called on a closed <code>CallableStatement</code>
1549: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1550: * this method
1551: * @see Types
1552: * @see #setObject
1553: * @since 1.4
1554: */
1555: Object getObject(String parameterName) throws SQLException;
1556:
1557: /**
1558: * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
1559: * <code>java.math.BigDecimal</code> object with as many digits to the
1560: * right of the decimal point as the value contains.
1561: * @param parameterName the name of the parameter
1562: * @return the parameter value in full precision. If the value is
1563: * SQL <code>NULL</code>, the result is <code>null</code>.
1564: * @exception SQLExceptionif parameterName does not correspond to a named
1565: * parameter; if a database access error occurs or
1566: * this method is called on a closed <code>CallableStatement</code>
1567: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1568: * this method
1569: * @see #setBigDecimal
1570: * @since 1.4
1571: */
1572: BigDecimal getBigDecimal(String parameterName) throws SQLException;
1573:
1574: /**
1575: * Returns an object representing the value of OUT parameter
1576: * <code>parameterName</code> and uses <code>map</code> for the custom
1577: * mapping of the parameter value.
1578: * <p>
1579: * This method returns a Java object whose type corresponds to the
1580: * JDBC type that was registered for this parameter using the method
1581: * <code>registerOutParameter</code>. By registering the target
1582: * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
1583: * be used to read database-specific abstract data types.
1584: * @param parameterName the name of the parameter
1585: * @param map the mapping from SQL type names to Java classes
1586: * @return a <code>java.lang.Object</code> holding the OUT parameter value
1587: * @exception SQLException if parameterName does not correspond to a named
1588: * parameter; if a database access error occurs or
1589: * this method is called on a closed <code>CallableStatement</code>
1590: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1591: * this method
1592: * @see #setObject
1593: * @since 1.4
1594: */
1595: Object getObject(String parameterName,
1596: java.util.Map<String, Class<?>> map) throws SQLException;
1597:
1598: /**
1599: * Retrieves the value of a JDBC <code>REF(<structured-type>)</code>
1600: * parameter as a {@link java.sql.Ref} object in the Java programming language.
1601: *
1602: * @param parameterName the name of the parameter
1603: * @return the parameter value as a <code>Ref</code> object in the
1604: * Java programming language. If the value was SQL <code>NULL</code>,
1605: * the value <code>null</code> is returned.
1606: * @exception SQLException if parameterName does not correspond to a named
1607: * parameter; if a database access error occurs or
1608: * this method is called on a closed <code>CallableStatement</code>
1609: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1610: * this method
1611: * @since 1.4
1612: */
1613: Ref getRef(String parameterName) throws SQLException;
1614:
1615: /**
1616: * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
1617: * {@link java.sql.Blob} object in the Java programming language.
1618: *
1619: * @param parameterName the name of the parameter
1620: * @return the parameter value as a <code>Blob</code> object in the
1621: * Java programming language. If the value was SQL <code>NULL</code>,
1622: * the value <code>null</code> is returned.
1623: * @exception SQLException if parameterName does not correspond to a named
1624: * parameter; if a database access error occurs or
1625: * this method is called on a closed <code>CallableStatement</code>
1626: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1627: * this method
1628: * @since 1.4
1629: */
1630: Blob getBlob(String parameterName) throws SQLException;
1631:
1632: /**
1633: * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
1634: * <code>java.sql.Clob</code> object in the Java programming language.
1635: * @param parameterName the name of the parameter
1636: * @return the parameter value as a <code>Clob</code> object in the
1637: * Java programming language. If the value was SQL <code>NULL</code>,
1638: * the value <code>null</code> is returned.
1639: * @exception SQLException if parameterName does not correspond to a named
1640: * parameter; if a database access error occurs or
1641: * this method is called on a closed <code>CallableStatement</code>
1642: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1643: * this method
1644: * @since 1.4
1645: */
1646: Clob getClob(String parameterName) throws SQLException;
1647:
1648: /**
1649: * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
1650: * {@link java.sql.Array} object in the Java programming language.
1651: *
1652: * @param parameterName the name of the parameter
1653: * @return the parameter value as an <code>Array</code> object in
1654: * Java programming language. If the value was SQL <code>NULL</code>,
1655: * the value <code>null</code> is returned.
1656: * @exception SQLException if parameterName does not correspond to a named
1657: * parameter; if a database access error occurs or
1658: * this method is called on a closed <code>CallableStatement</code>
1659: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1660: * this method
1661: * @since 1.4
1662: */
1663: Array getArray(String parameterName) throws SQLException;
1664:
1665: /**
1666: * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1667: * <code>java.sql.Date</code> object, using
1668: * the given <code>Calendar</code> object
1669: * to construct the date.
1670: * With a <code>Calendar</code> object, the driver
1671: * can calculate the date taking into account a custom timezone and locale.
1672: * If no <code>Calendar</code> object is specified, the driver uses the
1673: * default timezone and locale.
1674: *
1675: * @param parameterName the name of the parameter
1676: * @param cal the <code>Calendar</code> object the driver will use
1677: * to construct the date
1678: * @return the parameter value. If the value is SQL <code>NULL</code>,
1679: * the result is <code>null</code>.
1680: * @exception SQLException if parameterName does not correspond to a named
1681: * parameter; if a database access error occurs or
1682: * this method is called on a closed <code>CallableStatement</code>
1683: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1684: * this method
1685: * @see #setDate
1686: * @since 1.4
1687: */
1688: java.sql.Date getDate(String parameterName, Calendar cal)
1689: throws SQLException;
1690:
1691: /**
1692: * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1693: * <code>java.sql.Time</code> object, using
1694: * the given <code>Calendar</code> object
1695: * to construct the time.
1696: * With a <code>Calendar</code> object, the driver
1697: * can calculate the time taking into account a custom timezone and locale.
1698: * If no <code>Calendar</code> object is specified, the driver uses the
1699: * default timezone and locale.
1700: *
1701: * @param parameterName the name of the parameter
1702: * @param cal the <code>Calendar</code> object the driver will use
1703: * to construct the time
1704: * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
1705: * <code>null</code>.
1706: * @exception SQLException if parameterName does not correspond to a named
1707: * parameter; if a database access error occurs or
1708: * this method is called on a closed <code>CallableStatement</code>
1709: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1710: * this method
1711: * @see #setTime
1712: * @since 1.4
1713: */
1714: java.sql.Time getTime(String parameterName, Calendar cal)
1715: throws SQLException;
1716:
1717: /**
1718: * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1719: * <code>java.sql.Timestamp</code> object, using
1720: * the given <code>Calendar</code> object to construct
1721: * the <code>Timestamp</code> object.
1722: * With a <code>Calendar</code> object, the driver
1723: * can calculate the timestamp taking into account a custom timezone and locale.
1724: * If no <code>Calendar</code> object is specified, the driver uses the
1725: * default timezone and locale.
1726: *
1727: *
1728: * @param parameterName the name of the parameter
1729: * @param cal the <code>Calendar</code> object the driver will use
1730: * to construct the timestamp
1731: * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1732: * <code>null</code>.
1733: * @exception SQLException if parameterName does not correspond to a named
1734: * parameter; if a database access error occurs or
1735: * this method is called on a closed <code>CallableStatement</code>
1736: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1737: * this method
1738: * @see #setTimestamp
1739: * @since 1.4
1740: */
1741: java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
1742: throws SQLException;
1743:
1744: /**
1745: * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
1746: * <code>java.net.URL</code> object.
1747: *
1748: * @param parameterName the name of the parameter
1749: * @return the parameter value as a <code>java.net.URL</code> object in the
1750: * Java programming language. If the value was SQL <code>NULL</code>, the
1751: * value <code>null</code> is returned.
1752: * @exception SQLException if parameterName does not correspond to a named
1753: * parameter; if a database access error occurs,
1754: * this method is called on a closed <code>CallableStatement</code>,
1755: * or if there is a problem with the URL
1756: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1757: * this method
1758: * @see #setURL
1759: * @since 1.4
1760: */
1761: java.net.URL getURL(String parameterName) throws SQLException;
1762:
1763: //------------------------- JDBC 4.0 -----------------------------------
1764:
1765: /**
1766: * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1767: * <code>java.sql.RowId</code> object.
1768: *
1769: * @param parameterIndex the first parameter is 1, the second is 2,...
1770: * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1771: * value is used as the designated parameter. If the parameter contains
1772: * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1773: * @throws SQLException if the parameterIndex is not valid;
1774: * if a database access error occurs or
1775: * this method is called on a closed <code>CallableStatement</code>
1776: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1777: * this method
1778: * @since 1.6
1779: */
1780: RowId getRowId(int parameterIndex) throws SQLException;
1781:
1782: /**
1783: * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1784: * <code>java.sql.RowId</code> object.
1785: *
1786: * @param parameterName the name of the parameter
1787: * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1788: * value is used as the designated parameter. If the parameter contains
1789: * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1790: * @throws SQLException if parameterName does not correspond to a named
1791: * parameter; if a database access error occurs or
1792: * this method is called on a closed <code>CallableStatement</code>
1793: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1794: * this method
1795: * @since 1.6
1796: */
1797: RowId getRowId(String parameterName) throws SQLException;
1798:
1799: /**
1800: * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1801: * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1802: * database.
1803: *
1804: * @param parameterName the name of the parameter
1805: * @param x the parameter value
1806: * @throws SQLException if parameterName does not correspond to a named
1807: * parameter; if a database access error occurs or
1808: * this method is called on a closed <code>CallableStatement</code>
1809: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1810: * this method
1811: * @since 1.6
1812: */
1813: void setRowId(String parameterName, RowId x) throws SQLException;
1814:
1815: /**
1816: * Sets the designated parameter to the given <code>String</code> object.
1817: * The driver converts this to a SQL <code>NCHAR</code> or
1818: * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1819: * @param parameterName the name of the parameter to be set
1820: * @param value the parameter value
1821: * @throws SQLException if parameterName does not correspond to a named
1822: * parameter; if the driver does not support national
1823: * character sets; if the driver can detect that a data conversion
1824: * error could occur; if a database access error occurs or
1825: * this method is called on a closed <code>CallableStatement</code>
1826: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1827: * this method
1828: * @since 1.6
1829: */
1830: void setNString(String parameterName, String value)
1831: throws SQLException;
1832:
1833: /**
1834: * Sets the designated parameter to a <code>Reader</code> object. The
1835: * <code>Reader</code> reads the data till end-of-file is reached. The
1836: * driver does the necessary conversion from Java character format to
1837: * the national character set in the database.
1838: * @param parameterName the name of the parameter to be set
1839: * @param value the parameter value
1840: * @param length the number of characters in the parameter data.
1841: * @throws SQLException if parameterName does not correspond to a named
1842: * parameter; if the driver does not support national
1843: * character sets; if the driver can detect that a data conversion
1844: * error could occur; if a database access error occurs or
1845: * this method is called on a closed <code>CallableStatement</code>
1846: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1847: * this method
1848: * @since 1.6
1849: */
1850: void setNCharacterStream(String parameterName, Reader value,
1851: long length) throws SQLException;
1852:
1853: /**
1854: * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
1855: * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
1856: * object maps to a SQL <code>NCLOB</code>.
1857: * @param parameterName the name of the parameter to be set
1858: * @param value the parameter value
1859: * @throws SQLException if parameterName does not correspond to a named
1860: * parameter; if the driver does not support national
1861: * character sets; if the driver can detect that a data conversion
1862: * error could occur; if a database access error occurs or
1863: * this method is called on a closed <code>CallableStatement</code>
1864: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1865: * this method
1866: * @since 1.6
1867: */
1868: void setNClob(String parameterName, NClob value)
1869: throws SQLException;
1870:
1871: /**
1872: * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1873: * of characters specified by length otherwise a <code>SQLException</code> will be
1874: * generated when the <code>CallableStatement</code> is executed.
1875: * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1876: * because it informs the driver that the parameter value should be sent to
1877: * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1878: * driver may have to do extra work to determine whether the parameter
1879: * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1880: * @param parameterName the name of the parameter to be set
1881: * @param reader An object that contains the data to set the parameter value to.
1882: * @param length the number of characters in the parameter data.
1883: * @throws SQLException if parameterName does not correspond to a named
1884: * parameter; if the length specified is less than zero;
1885: * a database access error occurs or
1886: * this method is called on a closed <code>CallableStatement</code>
1887: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1888: * this method
1889: *
1890: * @since 1.6
1891: */
1892: void setClob(String parameterName, Reader reader, long length)
1893: throws SQLException;
1894:
1895: /**
1896: * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1897: * of characters specified by length, otherwise a <code>SQLException</code> will be
1898: * generated when the <code>CallableStatement</code> is executed.
1899: * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1900: * method because it informs the driver that the parameter value should be
1901: * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1902: * the driver may have to do extra work to determine whether the parameter
1903: * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1904: *
1905: * @param parameterName the name of the parameter to be set
1906: * the second is 2, ...
1907: *
1908: * @param inputStream An object that contains the data to set the parameter
1909: * value to.
1910: * @param length the number of bytes in the parameter data.
1911: * @throws SQLException if parameterName does not correspond to a named
1912: * parameter; if the length specified
1913: * is less than zero; if the number of bytes in the inputstream does not match
1914: * the specfied length; if a database access error occurs or
1915: * this method is called on a closed <code>CallableStatement</code>
1916: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1917: * this method
1918: *
1919: * @since 1.6
1920: */
1921: void setBlob(String parameterName, InputStream inputStream,
1922: long length) throws SQLException;
1923:
1924: /**
1925: * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1926: * of characters specified by length otherwise a <code>SQLException</code> will be
1927: * generated when the <code>CallableStatement</code> is executed.
1928: * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1929: * because it informs the driver that the parameter value should be sent to
1930: * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
1931: * driver may have to do extra work to determine whether the parameter
1932: * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1933: *
1934: * @param parameterName the name of the parameter to be set
1935: * @param reader An object that contains the data to set the parameter value to.
1936: * @param length the number of characters in the parameter data.
1937: * @throws SQLException if parameterName does not correspond to a named
1938: * parameter; if the length specified is less than zero;
1939: * if the driver does not support national
1940: * character sets; if the driver can detect that a data conversion
1941: * error could occur; if a database access error occurs or
1942: * this method is called on a closed <code>CallableStatement</code>
1943: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1944: * this method
1945: * @since 1.6
1946: */
1947: void setNClob(String parameterName, Reader reader, long length)
1948: throws SQLException;
1949:
1950: /**
1951: * Retrieves the value of the designated JDBC <code>NCLOB</code> parameter as a
1952: * <code>java.sql.NClob</code> object in the Java programming language.
1953: *
1954: * @param parameterIndex the first parameter is 1, the second is 2, and
1955: * so on
1956: * @return the parameter value as a <code>NClob</code> object in the
1957: * Java programming language. If the value was SQL <code>NULL</code>, the
1958: * value <code>null</code> is returned.
1959: * @exception SQLException if the parameterIndex is not valid;
1960: * if the driver does not support national
1961: * character sets; if the driver can detect that a data conversion
1962: * error could occur; if a database access error occurs or
1963: * this method is called on a closed <code>CallableStatement</code>
1964: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1965: * this method
1966: * @since 1.6
1967: */
1968: NClob getNClob(int parameterIndex) throws SQLException;
1969:
1970: /**
1971: * Retrieves the value of a JDBC <code>NCLOB</code> parameter as a
1972: * <code>java.sql.NClob</code> object in the Java programming language.
1973: * @param parameterName the name of the parameter
1974: * @return the parameter value as a <code>NClob</code> object in the
1975: * Java programming language. If the value was SQL <code>NULL</code>,
1976: * the value <code>null</code> is returned.
1977: * @exception SQLException if parameterName does not correspond to a named
1978: * parameter; if the driver does not support national
1979: * character sets; if the driver can detect that a data conversion
1980: * error could occur; if a database access error occurs or
1981: * this method is called on a closed <code>CallableStatement</code>
1982: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1983: * this method
1984: * @since 1.6
1985: */
1986: NClob getNClob(String parameterName) throws SQLException;
1987:
1988: /**
1989: * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1990: * <code>SQL XML</code> value when it sends it to the database.
1991: *
1992: * @param parameterName the name of the parameter
1993: * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1994: * @throws SQLException if parameterName does not correspond to a named
1995: * parameter; if a database access error occurs;
1996: * this method is called on a closed <code>CallableStatement</code> or
1997: * the <code>java.xml.transform.Result</code>,
1998: * <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object
1999: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2000: * this method
2001: *
2002: * @since 1.6
2003: */
2004: void setSQLXML(String parameterName, SQLXML xmlObject)
2005: throws SQLException;
2006:
2007: /**
2008: * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2009: * <code>java.sql.SQLXML</code> object in the Java programming language.
2010: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2011: * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2012: * @throws SQLException if the parameterIndex is not valid;
2013: * if a database access error occurs or
2014: * this method is called on a closed <code>CallableStatement</code>
2015: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2016: * this method
2017: * @since 1.6
2018: */
2019: SQLXML getSQLXML(int parameterIndex) throws SQLException;
2020:
2021: /**
2022: * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2023: * <code>java.sql.SQLXML</code> object in the Java programming language.
2024: * @param parameterName the name of the parameter
2025: * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2026: * @throws SQLException if parameterName does not correspond to a named
2027: * parameter; if a database access error occurs or
2028: * this method is called on a closed <code>CallableStatement</code>
2029: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2030: * this method
2031: * @since 1.6
2032: */
2033: SQLXML getSQLXML(String parameterName) throws SQLException;
2034:
2035: /**
2036: * Retrieves the value of the designated <code>NCHAR</code>,
2037: * <code>NVARCHAR</code>
2038: * or <code>LONGNVARCHAR</code> parameter as
2039: * a <code>String</code> in the Java programming language.
2040: * <p>
2041: * For the fixed-length type JDBC <code>NCHAR</code>,
2042: * the <code>String</code> object
2043: * returned has exactly the same value the SQL
2044: * <code>NCHAR</code> value had in the
2045: * database, including any padding added by the database.
2046: *
2047: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2048: * @return a <code>String</code> object that maps an
2049: * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2050: * @exception SQLException if the parameterIndex is not valid;
2051: * if a database access error occurs or
2052: * this method is called on a closed <code>CallableStatement</code>
2053: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2054: * this method
2055: * @since 1.6
2056: * @see #setNString
2057: */
2058: String getNString(int parameterIndex) throws SQLException;
2059:
2060: /**
2061: * Retrieves the value of the designated <code>NCHAR</code>,
2062: * <code>NVARCHAR</code>
2063: * or <code>LONGNVARCHAR</code> parameter as
2064: * a <code>String</code> in the Java programming language.
2065: * <p>
2066: * For the fixed-length type JDBC <code>NCHAR</code>,
2067: * the <code>String</code> object
2068: * returned has exactly the same value the SQL
2069: * <code>NCHAR</code> value had in the
2070: * database, including any padding added by the database.
2071: *
2072: * @param parameterName the name of the parameter
2073: * @return a <code>String</code> object that maps an
2074: * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2075: * @exception SQLException if parameterName does not correspond to a named
2076: * parameter;
2077: * if a database access error occurs or
2078: * this method is called on a closed <code>CallableStatement</code>
2079: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2080: * this method
2081: * @since 1.6
2082: * @see #setNString
2083: */
2084: String getNString(String parameterName) throws SQLException;
2085:
2086: /**
2087: * Retrieves the value of the designated parameter as a
2088: * <code>java.io.Reader</code> object in the Java programming language.
2089: * It is intended for use when
2090: * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
2091: * and <code>LONGNVARCHAR</code> parameters.
2092: *
2093: * @return a <code>java.io.Reader</code> object that contains the parameter
2094: * value; if the value is SQL <code>NULL</code>, the value returned is
2095: * <code>null</code> in the Java programming language.
2096: * @param parameterIndex the first parameter is 1, the second is 2, ...
2097: * @exception SQLException if the parameterIndex is not valid;
2098: * if a database access error occurs or
2099: * this method is called on a closed <code>CallableStatement</code>
2100: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2101: * this method
2102: * @since 1.6
2103: */
2104: java.io.Reader getNCharacterStream(int parameterIndex)
2105: throws SQLException;
2106:
2107: /**
2108: * Retrieves the value of the designated parameter as a
2109: * <code>java.io.Reader</code> object in the Java programming language.
2110: * It is intended for use when
2111: * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
2112: * and <code>LONGNVARCHAR</code> parameters.
2113: *
2114: * @param parameterName the name of the parameter
2115: * @return a <code>java.io.Reader</code> object that contains the parameter
2116: * value; if the value is SQL <code>NULL</code>, the value returned is
2117: * <code>null</code> in the Java programming language
2118: * @exception SQLException if parameterName does not correspond to a named
2119: * parameter; if a database access error occurs or
2120: * this method is called on a closed <code>CallableStatement</code>
2121: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2122: * this method
2123: * @since 1.6
2124: */
2125: java.io.Reader getNCharacterStream(String parameterName)
2126: throws SQLException;
2127:
2128: /**
2129: * Retrieves the value of the designated parameter as a
2130: * <code>java.io.Reader</code> object in the Java programming language.
2131: *
2132: * @return a <code>java.io.Reader</code> object that contains the parameter
2133: * value; if the value is SQL <code>NULL</code>, the value returned is
2134: * <code>null</code> in the Java programming language.
2135: * @param parameterIndex the first parameter is 1, the second is 2, ...
2136: * @exception SQLException if the parameterIndex is not valid; if a database access error occurs or
2137: * this method is called on a closed <code>CallableStatement</code>
2138: * @since 1.6
2139: */
2140: java.io.Reader getCharacterStream(int parameterIndex)
2141: throws SQLException;
2142:
2143: /**
2144: * Retrieves the value of the designated parameter as a
2145: * <code>java.io.Reader</code> object in the Java programming language.
2146: *
2147: * @param parameterName the name of the parameter
2148: * @return a <code>java.io.Reader</code> object that contains the parameter
2149: * value; if the value is SQL <code>NULL</code>, the value returned is
2150: * <code>null</code> in the Java programming language
2151: * @exception SQLException if parameterName does not correspond to a named
2152: * parameter; if a database access error occurs or
2153: * this method is called on a closed <code>CallableStatement</code>
2154: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2155: * this method
2156: * @since 1.6
2157: */
2158: java.io.Reader getCharacterStream(String parameterName)
2159: throws SQLException;
2160:
2161: /**
2162: * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
2163: * The driver converts this to an SQL <code>BLOB</code> value when it
2164: * sends it to the database.
2165: *
2166: * @param parameterName the name of the parameter
2167: * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
2168: * @exception SQLException if parameterName does not correspond to a named
2169: * parameter; if a database access error occurs or
2170: * this method is called on a closed <code>CallableStatement</code>
2171: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2172: * this method
2173: * @since 1.6
2174: */
2175: void setBlob(String parameterName, Blob x) throws SQLException;
2176:
2177: /**
2178: * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
2179: * The driver converts this to an SQL <code>CLOB</code> value when it
2180: * sends it to the database.
2181: *
2182: * @param parameterName the name of the parameter
2183: * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
2184: * @exception SQLException if parameterName does not correspond to a named
2185: * parameter; if a database access error occurs or
2186: * this method is called on a closed <code>CallableStatement</code>
2187: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2188: * this method
2189: * @since 1.6
2190: */
2191: void setClob(String parameterName, Clob x) throws SQLException;
2192:
2193: /**
2194: * Sets the designated parameter to the given input stream, which will have
2195: * the specified number of bytes.
2196: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2197: * parameter, it may be more practical to send it via a
2198: * <code>java.io.InputStream</code>. Data will be read from the stream
2199: * as needed until end-of-file is reached. The JDBC driver will
2200: * do any necessary conversion from ASCII to the database char format.
2201: *
2202: * <P><B>Note:</B> This stream object can either be a standard
2203: * Java stream object or your own subclass that implements the
2204: * standard interface.
2205: *
2206: * @param parameterName the name of the parameter
2207: * @param x the Java input stream that contains the ASCII parameter value
2208: * @param length the number of bytes in the stream
2209: * @exception SQLException if parameterName does not correspond to a named
2210: * parameter; if a database access error occurs or
2211: * this method is called on a closed <code>CallableStatement</code>
2212: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2213: * this method
2214: * @since 1.6
2215: */
2216: void setAsciiStream(String parameterName, java.io.InputStream x,
2217: long length) throws SQLException;
2218:
2219: /**
2220: * Sets the designated parameter to the given input stream, which will have
2221: * the specified number of bytes.
2222: * When a very large binary value is input to a <code>LONGVARBINARY</code>
2223: * parameter, it may be more practical to send it via a
2224: * <code>java.io.InputStream</code> object. The data will be read from the stream
2225: * as needed until end-of-file is reached.
2226: *
2227: * <P><B>Note:</B> This stream object can either be a standard
2228: * Java stream object or your own subclass that implements the
2229: * standard interface.
2230: *
2231: * @param parameterName the name of the parameter
2232: * @param x the java input stream which contains the binary parameter value
2233: * @param length the number of bytes in the stream
2234: * @exception SQLException if parameterName does not correspond to a named
2235: * parameter; if a database access error occurs or
2236: * this method is called on a closed <code>CallableStatement</code>
2237: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2238: * this method
2239: * @since 1.6
2240: */
2241: void setBinaryStream(String parameterName, java.io.InputStream x,
2242: long length) throws SQLException;
2243:
2244: /**
2245: * Sets the designated parameter to the given <code>Reader</code>
2246: * object, which is the given number of characters long.
2247: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2248: * parameter, it may be more practical to send it via a
2249: * <code>java.io.Reader</code> object. The data will be read from the stream
2250: * as needed until end-of-file is reached. The JDBC driver will
2251: * do any necessary conversion from UNICODE to the database char format.
2252: *
2253: * <P><B>Note:</B> This stream object can either be a standard
2254: * Java stream object or your own subclass that implements the
2255: * standard interface.
2256: *
2257: * @param parameterName the name of the parameter
2258: * @param reader the <code>java.io.Reader</code> object that
2259: * contains the UNICODE data used as the designated parameter
2260: * @param length the number of characters in the stream
2261: * @exception SQLException if parameterName does not correspond to a named
2262: * parameter; if a database access error occurs or
2263: * this method is called on a closed <code>CallableStatement</code>
2264: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2265: * this method
2266: * @since 1.6
2267: */
2268: void setCharacterStream(String parameterName,
2269: java.io.Reader reader, long length) throws SQLException;
2270:
2271: //--
2272: /**
2273: * Sets the designated parameter to the given input stream.
2274: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2275: * parameter, it may be more practical to send it via a
2276: * <code>java.io.InputStream</code>. Data will be read from the stream
2277: * as needed until end-of-file is reached. The JDBC driver will
2278: * do any necessary conversion from ASCII to the database char format.
2279: *
2280: * <P><B>Note:</B> This stream object can either be a standard
2281: * Java stream object or your own subclass that implements the
2282: * standard interface.
2283: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2284: * it might be more efficient to use a version of
2285: * <code>setAsciiStream</code> which takes a length parameter.
2286: *
2287: * @param parameterName the name of the parameter
2288: * @param x the Java input stream that contains the ASCII parameter value
2289: * @exception SQLException if parameterName does not correspond to a named
2290: * parameter; if a database access error occurs or
2291: * this method is called on a closed <code>CallableStatement</code>
2292: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2293: * @since 1.6
2294: */
2295: void setAsciiStream(String parameterName, java.io.InputStream x)
2296: throws SQLException;
2297:
2298: /**
2299: * Sets the designated parameter to the given input stream.
2300: * When a very large binary value is input to a <code>LONGVARBINARY</code>
2301: * parameter, it may be more practical to send it via a
2302: * <code>java.io.InputStream</code> object. The data will be read from the
2303: * stream as needed until end-of-file is reached.
2304: *
2305: * <P><B>Note:</B> This stream object can either be a standard
2306: * Java stream object or your own subclass that implements the
2307: * standard interface.
2308: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2309: * it might be more efficient to use a version of
2310: * <code>setBinaryStream</code> which takes a length parameter.
2311: *
2312: * @param parameterName the name of the parameter
2313: * @param x the java input stream which contains the binary parameter value
2314: * @exception SQLException if parameterName does not correspond to a named
2315: * parameter; if a database access error occurs or
2316: * this method is called on a closed <code>CallableStatement</code>
2317: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2318: * @since 1.6
2319: */
2320: void setBinaryStream(String parameterName, java.io.InputStream x)
2321: throws SQLException;
2322:
2323: /**
2324: * Sets the designated parameter to the given <code>Reader</code>
2325: * object.
2326: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2327: * parameter, it may be more practical to send it via a
2328: * <code>java.io.Reader</code> object. The data will be read from the stream
2329: * as needed until end-of-file is reached. The JDBC driver will
2330: * do any necessary conversion from UNICODE to the database char format.
2331: *
2332: * <P><B>Note:</B> This stream object can either be a standard
2333: * Java stream object or your own subclass that implements the
2334: * standard interface.
2335: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2336: * it might be more efficient to use a version of
2337: * <code>setCharacterStream</code> which takes a length parameter.
2338: *
2339: * @param parameterName the name of the parameter
2340: * @param reader the <code>java.io.Reader</code> object that contains the
2341: * Unicode data
2342: * @exception SQLException if parameterName does not correspond to a named
2343: * parameter; if a database access error occurs or
2344: * this method is called on a closed <code>CallableStatement</code>
2345: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2346: * @since 1.6
2347: */
2348: void setCharacterStream(String parameterName, java.io.Reader reader)
2349: throws SQLException;
2350:
2351: /**
2352: * Sets the designated parameter to a <code>Reader</code> object. The
2353: * <code>Reader</code> reads the data till end-of-file is reached. The
2354: * driver does the necessary conversion from Java character format to
2355: * the national character set in the database.
2356:
2357: * <P><B>Note:</B> This stream object can either be a standard
2358: * Java stream object or your own subclass that implements the
2359: * standard interface.
2360: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2361: * it might be more efficient to use a version of
2362: * <code>setNCharacterStream</code> which takes a length parameter.
2363: *
2364: * @param parameterName the name of the parameter
2365: * @param value the parameter value
2366: * @throws SQLException if parameterName does not correspond to a named
2367: * parameter; if the driver does not support national
2368: * character sets; if the driver can detect that a data conversion
2369: * error could occur; if a database access error occurs; or
2370: * this method is called on a closed <code>CallableStatement</code>
2371: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2372: * @since 1.6
2373: */
2374: void setNCharacterStream(String parameterName, Reader value)
2375: throws SQLException;
2376:
2377: /**
2378: * Sets the designated parameter to a <code>Reader</code> object.
2379: * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2380: * because it informs the driver that the parameter value should be sent to
2381: * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
2382: * driver may have to do extra work to determine whether the parameter
2383: * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
2384: *
2385: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2386: * it might be more efficient to use a version of
2387: * <code>setClob</code> which takes a length parameter.
2388: *
2389: * @param parameterName the name of the parameter
2390: * @param reader An object that contains the data to set the parameter value to.
2391: * @throws SQLException if parameterName does not correspond to a named
2392: * parameter; if a database access error occurs or this method is called on
2393: * a closed <code>CallableStatement</code>
2394: *
2395: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2396: * @since 1.6
2397: */
2398: void setClob(String parameterName, Reader reader)
2399: throws SQLException;
2400:
2401: /**
2402: * Sets the designated parameter to a <code>InputStream</code> object.
2403: * This method differs from the <code>setBinaryStream (int, InputStream)</code>
2404: * method because it informs the driver that the parameter value should be
2405: * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
2406: * the driver may have to do extra work to determine whether the parameter
2407: * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
2408: *
2409: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2410: * it might be more efficient to use a version of
2411: * <code>setBlob</code> which takes a length parameter.
2412: *
2413: * @param parameterName the name of the parameter
2414: * @param inputStream An object that contains the data to set the parameter
2415: * value to.
2416: * @throws SQLException if parameterName does not correspond to a named
2417: * parameter; if a database access error occurs or
2418: * this method is called on a closed <code>CallableStatement</code>
2419: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2420: *
2421: * @since 1.6
2422: */
2423: void setBlob(String parameterName, InputStream inputStream)
2424: throws SQLException;
2425:
2426: /**
2427: * Sets the designated parameter to a <code>Reader</code> object.
2428: * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2429: * because it informs the driver that the parameter value should be sent to
2430: * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2431: * driver may have to do extra work to determine whether the parameter
2432: * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2433: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2434: * it might be more efficient to use a version of
2435: * <code>setNClob</code> which takes a length parameter.
2436: *
2437: * @param parameterName the name of the parameter
2438: * @param reader An object that contains the data to set the parameter value to.
2439: * @throws SQLException if parameterName does not correspond to a named
2440: * parameter; if the driver does not support national character sets;
2441: * if the driver can detect that a data conversion
2442: * error could occur; if a database access error occurs or
2443: * this method is called on a closed <code>CallableStatement</code>
2444: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2445: *
2446: * @since 1.6
2447: */
2448: void setNClob(String parameterName, Reader reader)
2449: throws SQLException;
2450: }
|
