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: * An object that represents a precompiled SQL statement.
0035: * <P>A SQL statement is precompiled and stored in a
0036: * <code>PreparedStatement</code> object. This object can then be used to
0037: * efficiently execute this statement multiple times.
0038: *
0039: * <P><B>Note:</B> The setter methods (<code>setShort</code>, <code>setString</code>,
0040: * and so on) for setting IN parameter values
0041: * must specify types that are compatible with the defined SQL type of
0042: * the input parameter. For instance, if the IN parameter has SQL type
0043: * <code>INTEGER</code>, then the method <code>setInt</code> should be used.
0044: *
0045: * <p>If arbitrary parameter type conversions are required, the method
0046: * <code>setObject</code> should be used with a target SQL type.
0047: * <P>
0048: * In the following example of setting a parameter, <code>con</code> represents
0049: * an active connection:
0050: * <PRE>
0051: * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES
0052: * SET SALARY = ? WHERE ID = ?");
0053: * pstmt.setBigDecimal(1, 153833.00)
0054: * pstmt.setInt(2, 110592)
0055: * </PRE>
0056: *
0057: * @see Connection#prepareStatement
0058: * @see ResultSet
0059: */
0060:
0061: public interface PreparedStatement extends Statement {
0062:
0063: /**
0064: * Executes the SQL query in this <code>PreparedStatement</code> object
0065: * and returns the <code>ResultSet</code> object generated by the query.
0066: *
0067: * @return a <code>ResultSet</code> object that contains the data produced by the
0068: * query; never <code>null</code>
0069: * @exception SQLException if a database access error occurs;
0070: * this method is called on a closed <code>PreparedStatement</code> or the SQL
0071: * statement does not return a <code>ResultSet</code> object
0072: */
0073: ResultSet executeQuery() throws SQLException;
0074:
0075: /**
0076: * Executes the SQL statement in this <code>PreparedStatement</code> object,
0077: * which must be an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
0078: * <code>DELETE</code>; or an SQL statement that returns nothing,
0079: * such as a DDL statement.
0080: *
0081: * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
0082: * or (2) 0 for SQL statements that return nothing
0083: * @exception SQLException if a database access error occurs;
0084: * this method is called on a closed <code>PreparedStatement</code>
0085: * or the SQL
0086: * statement returns a <code>ResultSet</code> object
0087: */
0088: int executeUpdate() throws SQLException;
0089:
0090: /**
0091: * Sets the designated parameter to SQL <code>NULL</code>.
0092: *
0093: * <P><B>Note:</B> You must specify the parameter's SQL type.
0094: *
0095: * @param parameterIndex the first parameter is 1, the second is 2, ...
0096: * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
0097: * @exception SQLException if parameterIndex does not correspond to a parameter
0098: * marker in the SQL statement; if a database access error occurs or
0099: * this method is called on a closed <code>PreparedStatement</code>
0100: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0101: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0102: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0103: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0104: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0105: * or <code>STRUCT</code> data type and the JDBC driver does not support
0106: * this data type
0107: */
0108: void setNull(int parameterIndex, int sqlType) throws SQLException;
0109:
0110: /**
0111: * Sets the designated parameter to the given Java <code>boolean</code> value.
0112: * The driver converts this
0113: * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
0114: *
0115: * @param parameterIndex the first parameter is 1, the second is 2, ...
0116: * @param x the parameter value
0117: * @exception SQLException if parameterIndex does not correspond to a parameter
0118: * marker in the SQL statement;
0119: * if a database access error occurs or
0120: * this method is called on a closed <code>PreparedStatement</code>
0121: */
0122: void setBoolean(int parameterIndex, boolean x) throws SQLException;
0123:
0124: /**
0125: * Sets the designated parameter to the given Java <code>byte</code> value.
0126: * The driver converts this
0127: * to an SQL <code>TINYINT</code> value when it sends it to the database.
0128: *
0129: * @param parameterIndex the first parameter is 1, the second is 2, ...
0130: * @param x the parameter value
0131: * @exception SQLException if parameterIndex does not correspond to a parameter
0132: * marker in the SQL statement; if a database access error occurs or
0133: * this method is called on a closed <code>PreparedStatement</code>
0134: */
0135: void setByte(int parameterIndex, byte x) throws SQLException;
0136:
0137: /**
0138: * Sets the designated parameter to the given Java <code>short</code> value.
0139: * The driver converts this
0140: * to an SQL <code>SMALLINT</code> value when it sends it to the database.
0141: *
0142: * @param parameterIndex the first parameter is 1, the second is 2, ...
0143: * @param x the parameter value
0144: * @exception SQLException if parameterIndex does not correspond to a parameter
0145: * marker in the SQL statement; if a database access error occurs or
0146: * this method is called on a closed <code>PreparedStatement</code>
0147: */
0148: void setShort(int parameterIndex, short x) throws SQLException;
0149:
0150: /**
0151: * Sets the designated parameter to the given Java <code>int</code> value.
0152: * The driver converts this
0153: * to an SQL <code>INTEGER</code> value when it sends it to the database.
0154: *
0155: * @param parameterIndex the first parameter is 1, the second is 2, ...
0156: * @param x the parameter value
0157: * @exception SQLException if parameterIndex does not correspond to a parameter
0158: * marker in the SQL statement; if a database access error occurs or
0159: * this method is called on a closed <code>PreparedStatement</code>
0160: */
0161: void setInt(int parameterIndex, int x) throws SQLException;
0162:
0163: /**
0164: * Sets the designated parameter to the given Java <code>long</code> value.
0165: * The driver converts this
0166: * to an SQL <code>BIGINT</code> value when it sends it to the database.
0167: *
0168: * @param parameterIndex the first parameter is 1, the second is 2, ...
0169: * @param x the parameter value
0170: * @exception SQLException if parameterIndex does not correspond to a parameter
0171: * marker in the SQL statement; if a database access error occurs or
0172: * this method is called on a closed <code>PreparedStatement</code>
0173: */
0174: void setLong(int parameterIndex, long x) throws SQLException;
0175:
0176: /**
0177: * Sets the designated parameter to the given Java <code>float</code> value.
0178: * The driver converts this
0179: * to an SQL <code>REAL</code> value when it sends it to the database.
0180: *
0181: * @param parameterIndex the first parameter is 1, the second is 2, ...
0182: * @param x the parameter value
0183: * @exception SQLException if parameterIndex does not correspond to a parameter
0184: * marker in the SQL statement; if a database access error occurs or
0185: * this method is called on a closed <code>PreparedStatement</code>
0186: */
0187: void setFloat(int parameterIndex, float x) throws SQLException;
0188:
0189: /**
0190: * Sets the designated parameter to the given Java <code>double</code> value.
0191: * The driver converts this
0192: * to an SQL <code>DOUBLE</code> value when it sends it to the database.
0193: *
0194: * @param parameterIndex the first parameter is 1, the second is 2, ...
0195: * @param x the parameter value
0196: * @exception SQLException if parameterIndex does not correspond to a parameter
0197: * marker in the SQL statement; if a database access error occurs or
0198: * this method is called on a closed <code>PreparedStatement</code>
0199: */
0200: void setDouble(int parameterIndex, double x) throws SQLException;
0201:
0202: /**
0203: * Sets the designated parameter to the given <code>java.math.BigDecimal</code> value.
0204: * The driver converts this to an SQL <code>NUMERIC</code> value when
0205: * it sends it to the database.
0206: *
0207: * @param parameterIndex the first parameter is 1, the second is 2, ...
0208: * @param x the parameter value
0209: * @exception SQLException if parameterIndex does not correspond to a parameter
0210: * marker in the SQL statement; if a database access error occurs or
0211: * this method is called on a closed <code>PreparedStatement</code>
0212: */
0213: void setBigDecimal(int parameterIndex, BigDecimal x)
0214: throws SQLException;
0215:
0216: /**
0217: * Sets the designated parameter to the given Java <code>String</code> value.
0218: * The driver converts this
0219: * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
0220: * (depending on the argument's
0221: * size relative to the driver's limits on <code>VARCHAR</code> values)
0222: * when it sends it to the database.
0223: *
0224: * @param parameterIndex the first parameter is 1, the second is 2, ...
0225: * @param x the parameter value
0226: * @exception SQLException if parameterIndex does not correspond to a parameter
0227: * marker in the SQL statement; if a database access error occurs or
0228: * this method is called on a closed <code>PreparedStatement</code>
0229: */
0230: void setString(int parameterIndex, String x) throws SQLException;
0231:
0232: /**
0233: * Sets the designated parameter to the given Java array of bytes. The driver converts
0234: * this to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code>
0235: * (depending on the argument's size relative to the driver's limits on
0236: * <code>VARBINARY</code> values) when it sends it to the database.
0237: *
0238: * @param parameterIndex the first parameter is 1, the second is 2, ...
0239: * @param x the parameter value
0240: * @exception SQLException if parameterIndex does not correspond to a parameter
0241: * marker in the SQL statement; if a database access error occurs or
0242: * this method is called on a closed <code>PreparedStatement</code>
0243: */
0244: void setBytes(int parameterIndex, byte x[]) throws SQLException;
0245:
0246: /**
0247: * Sets the designated parameter to the given <code>java.sql.Date</code> value
0248: * using the default time zone of the virtual machine that is running
0249: * the application.
0250: * The driver converts this
0251: * to an SQL <code>DATE</code> value when it sends it to the database.
0252: *
0253: * @param parameterIndex the first parameter is 1, the second is 2, ...
0254: * @param x the parameter value
0255: * @exception SQLException if parameterIndex does not correspond to a parameter
0256: * marker in the SQL statement; if a database access error occurs or
0257: * this method is called on a closed <code>PreparedStatement</code>
0258: */
0259: void setDate(int parameterIndex, java.sql.Date x)
0260: throws SQLException;
0261:
0262: /**
0263: * Sets the designated parameter to the given <code>java.sql.Time</code> value.
0264: * The driver converts this
0265: * to an SQL <code>TIME</code> value when it sends it to the database.
0266: *
0267: * @param parameterIndex the first parameter is 1, the second is 2, ...
0268: * @param x the parameter value
0269: * @exception SQLException if parameterIndex does not correspond to a parameter
0270: * marker in the SQL statement; if a database access error occurs or
0271: * this method is called on a closed <code>PreparedStatement</code>
0272: */
0273: void setTime(int parameterIndex, java.sql.Time x)
0274: throws SQLException;
0275:
0276: /**
0277: * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
0278: * The driver
0279: * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
0280: * database.
0281: *
0282: * @param parameterIndex the first parameter is 1, the second is 2, ...
0283: * @param x the parameter value
0284: * @exception SQLException if parameterIndex does not correspond to a parameter
0285: * marker in the SQL statement; if a database access error occurs or
0286: * this method is called on a closed <code>PreparedStatement</code> */
0287: void setTimestamp(int parameterIndex, java.sql.Timestamp x)
0288: throws SQLException;
0289:
0290: /**
0291: * Sets the designated parameter to the given input stream, which will have
0292: * the specified number of bytes.
0293: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
0294: * parameter, it may be more practical to send it via a
0295: * <code>java.io.InputStream</code>. Data will be read from the stream
0296: * as needed until end-of-file is reached. The JDBC driver will
0297: * do any necessary conversion from ASCII to the database char format.
0298: *
0299: * <P><B>Note:</B> This stream object can either be a standard
0300: * Java stream object or your own subclass that implements the
0301: * standard interface.
0302: *
0303: * @param parameterIndex the first parameter is 1, the second is 2, ...
0304: * @param x the Java input stream that contains the ASCII parameter value
0305: * @param length the number of bytes in the stream
0306: * @exception SQLException if parameterIndex does not correspond to a parameter
0307: * marker in the SQL statement; if a database access error occurs or
0308: * this method is called on a closed <code>PreparedStatement</code>
0309: */
0310: void setAsciiStream(int parameterIndex, java.io.InputStream x,
0311: int length) throws SQLException;
0312:
0313: /**
0314: * Sets the designated parameter to the given input stream, which
0315: * will have the specified number of bytes.
0316: *
0317: * When a very large Unicode value is input to a <code>LONGVARCHAR</code>
0318: * parameter, it may be more practical to send it via a
0319: * <code>java.io.InputStream</code> object. The data will be read from the
0320: * stream as needed until end-of-file is reached. The JDBC driver will
0321: * do any necessary conversion from Unicode to the database char format.
0322: *
0323: *The byte format of the Unicode stream must be a Java UTF-8, as defined in the
0324: *Java Virtual Machine Specification.
0325: *
0326: * <P><B>Note:</B> This stream object can either be a standard
0327: * Java stream object or your own subclass that implements the
0328: * standard interface.
0329: *
0330: * @param parameterIndex the first parameter is 1, the second is 2, ...
0331: * @param x a <code>java.io.InputStream</code> object that contains the
0332: * Unicode parameter value
0333: * @param length the number of bytes in the stream
0334: * @exception SQLException if parameterIndex does not correspond to a parameter
0335: * marker in the SQL statement; if a database access error occurs or
0336: * this method is called on a closed <code>PreparedStatement</code>
0337: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0338: * this method
0339: * @deprecated
0340: */
0341: void setUnicodeStream(int parameterIndex, java.io.InputStream x,
0342: int length) throws SQLException;
0343:
0344: /**
0345: * Sets the designated parameter to the given input stream, which will have
0346: * the specified number of bytes.
0347: * When a very large binary value is input to a <code>LONGVARBINARY</code>
0348: * parameter, it may be more practical to send it via a
0349: * <code>java.io.InputStream</code> object. The data will be read from the
0350: * stream as needed until end-of-file is reached.
0351: *
0352: * <P><B>Note:</B> This stream object can either be a standard
0353: * Java stream object or your own subclass that implements the
0354: * standard interface.
0355: *
0356: * @param parameterIndex the first parameter is 1, the second is 2, ...
0357: * @param x the java input stream which contains the binary parameter value
0358: * @param length the number of bytes in the stream
0359: * @exception SQLException if parameterIndex does not correspond to a parameter
0360: * marker in the SQL statement; if a database access error occurs or
0361: * this method is called on a closed <code>PreparedStatement</code>
0362: */
0363: void setBinaryStream(int parameterIndex, java.io.InputStream x,
0364: int length) throws SQLException;
0365:
0366: /**
0367: * Clears the current parameter values immediately.
0368: * <P>In general, parameter values remain in force for repeated use of a
0369: * statement. Setting a parameter value automatically clears its
0370: * previous value. However, in some cases it is useful to immediately
0371: * release the resources used by the current parameter values; this can
0372: * be done by calling the method <code>clearParameters</code>.
0373: *
0374: * @exception SQLException if a database access error occurs or
0375: * this method is called on a closed <code>PreparedStatement</code>
0376: */
0377: void clearParameters() throws SQLException;
0378:
0379: //----------------------------------------------------------------------
0380: // Advanced features:
0381:
0382: /**
0383: * Sets the value of the designated parameter with the given object.
0384: * This method is like the method <code>setObject</code>
0385: * above, except that it assumes a scale of zero.
0386: *
0387: * @param parameterIndex the first parameter is 1, the second is 2, ...
0388: * @param x the object containing the input parameter value
0389: * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
0390: * sent to the database
0391: * @exception SQLException if parameterIndex does not correspond to a parameter
0392: * marker in the SQL statement; if a database access error occurs or
0393: * this method is called on a closed <code>PreparedStatement</code>
0394: * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
0395: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0396: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0397: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0398: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0399: * or <code>STRUCT</code> data type and the JDBC driver does not support
0400: * this data type
0401: * @see Types
0402: */
0403: void setObject(int parameterIndex, Object x, int targetSqlType)
0404: throws SQLException;
0405:
0406: /**
0407: * <p>Sets the value of the designated parameter using the given object.
0408: * The second parameter must be of type <code>Object</code>; therefore, the
0409: * <code>java.lang</code> equivalent objects should be used for built-in types.
0410: *
0411: * <p>The JDBC specification specifies a standard mapping from
0412: * Java <code>Object</code> types to SQL types. The given argument
0413: * will be converted to the corresponding SQL type before being
0414: * sent to the database.
0415: *
0416: * <p>Note that this method may be used to pass datatabase-
0417: * specific abstract data types, by using a driver-specific Java
0418: * type.
0419: *
0420: * If the object is of a class implementing the interface <code>SQLData</code>,
0421: * the JDBC driver should call the method <code>SQLData.writeSQL</code>
0422: * to write it to the SQL data stream.
0423: * If, on the other hand, the object is of a class implementing
0424: * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
0425: * <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code>
0426: * or <code>Array</code>, the driver should pass it to the database as a
0427: * value of the corresponding SQL type.
0428: * <P>
0429: *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
0430: * the backend. For maximum portability, the <code>setNull</code> or the
0431: * <code>setObject(int parameterIndex, Object x, int sqlType)</code>
0432: * method should be used
0433: * instead of <code>setObject(int parameterIndex, Object x)</code>.
0434: *<p>
0435: * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the
0436: * object is of a class implementing more than one of the interfaces named above.
0437: *
0438: * @param parameterIndex the first parameter is 1, the second is 2, ...
0439: * @param x the object containing the input parameter value
0440: * @exception SQLException if parameterIndex does not correspond to a parameter
0441: * marker in the SQL statement; if a database access error occurs;
0442: * this method is called on a closed <code>PreparedStatement</code>
0443: * or the type of the given object is ambiguous
0444: */
0445: void setObject(int parameterIndex, Object x) throws SQLException;
0446:
0447: /**
0448: * Executes the SQL statement in this <code>PreparedStatement</code> object,
0449: * which may be any kind of SQL statement.
0450: * Some prepared statements return multiple results; the <code>execute</code>
0451: * method handles these complex statements as well as the simpler
0452: * form of statements handled by the methods <code>executeQuery</code>
0453: * and <code>executeUpdate</code>.
0454: * <P>
0455: * The <code>execute</code> method returns a <code>boolean</code> to
0456: * indicate the form of the first result. You must call either the method
0457: * <code>getResultSet</code> or <code>getUpdateCount</code>
0458: * to retrieve the result; you must call <code>getMoreResults</code> to
0459: * move to any subsequent result(s).
0460: *
0461: * @return <code>true</code> if the first result is a <code>ResultSet</code>
0462: * object; <code>false</code> if the first result is an update
0463: * count or there is no result
0464: * @exception SQLException if a database access error occurs;
0465: * this method is called on a closed <code>PreparedStatement</code>
0466: * or an argument is supplied to this method
0467: * @see Statement#execute
0468: * @see Statement#getResultSet
0469: * @see Statement#getUpdateCount
0470: * @see Statement#getMoreResults
0471:
0472: */
0473: boolean execute() throws SQLException;
0474:
0475: //--------------------------JDBC 2.0-----------------------------
0476:
0477: /**
0478: * Adds a set of parameters to this <code>PreparedStatement</code>
0479: * object's batch of commands.
0480: *
0481: * @exception SQLException if a database access error occurs or
0482: * this method is called on a closed <code>PreparedStatement</code>
0483: * @see Statement#addBatch
0484: * @since 1.2
0485: */
0486: void addBatch() throws SQLException;
0487:
0488: /**
0489: * Sets the designated parameter to the given <code>Reader</code>
0490: * object, which is the given number of characters long.
0491: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
0492: * parameter, it may be more practical to send it via a
0493: * <code>java.io.Reader</code> object. The data will be read from the stream
0494: * as needed until end-of-file is reached. The JDBC driver will
0495: * do any necessary conversion from UNICODE to the database char format.
0496: *
0497: * <P><B>Note:</B> This stream object can either be a standard
0498: * Java stream object or your own subclass that implements the
0499: * standard interface.
0500: *
0501: * @param parameterIndex the first parameter is 1, the second is 2, ...
0502: * @param reader the <code>java.io.Reader</code> object that contains the
0503: * Unicode data
0504: * @param length the number of characters in the stream
0505: * @exception SQLException if parameterIndex does not correspond to a parameter
0506: * marker in the SQL statement; if a database access error occurs or
0507: * this method is called on a closed <code>PreparedStatement</code>
0508: * @since 1.2
0509: */
0510: void setCharacterStream(int parameterIndex, java.io.Reader reader,
0511: int length) throws SQLException;
0512:
0513: /**
0514: * Sets the designated parameter to the given
0515: * <code>REF(<structured-type>)</code> value.
0516: * The driver converts this to an SQL <code>REF</code> value when it
0517: * sends it to the database.
0518: *
0519: * @param parameterIndex the first parameter is 1, the second is 2, ...
0520: * @param x an SQL <code>REF</code> value
0521: * @exception SQLException if parameterIndex does not correspond to a parameter
0522: * marker in the SQL statement; if a database access error occurs or
0523: * this method is called on a closed <code>PreparedStatement</code>
0524: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0525: * @since 1.2
0526: */
0527: void setRef(int parameterIndex, Ref x) throws SQLException;
0528:
0529: /**
0530: * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
0531: * The driver converts this to an SQL <code>BLOB</code> value when it
0532: * sends it to the database.
0533: *
0534: * @param parameterIndex the first parameter is 1, the second is 2, ...
0535: * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
0536: * @exception SQLException if parameterIndex does not correspond to a parameter
0537: * marker in the SQL statement; if a database access error occurs or
0538: * this method is called on a closed <code>PreparedStatement</code>
0539: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0540: * @since 1.2
0541: */
0542: void setBlob(int parameterIndex, Blob x) throws SQLException;
0543:
0544: /**
0545: * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
0546: * The driver converts this to an SQL <code>CLOB</code> value when it
0547: * sends it to the database.
0548: *
0549: * @param parameterIndex the first parameter is 1, the second is 2, ...
0550: * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
0551: * @exception SQLException if parameterIndex does not correspond to a parameter
0552: * marker in the SQL statement; if a database access error occurs or
0553: * this method is called on a closed <code>PreparedStatement</code>
0554: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0555: * @since 1.2
0556: */
0557: void setClob(int parameterIndex, Clob x) throws SQLException;
0558:
0559: /**
0560: * Sets the designated parameter to the given <code>java.sql.Array</code> object.
0561: * The driver converts this to an SQL <code>ARRAY</code> value when it
0562: * sends it to the database.
0563: *
0564: * @param parameterIndex the first parameter is 1, the second is 2, ...
0565: * @param x an <code>Array</code> object that maps an SQL <code>ARRAY</code> value
0566: * @exception SQLException if parameterIndex does not correspond to a parameter
0567: * marker in the SQL statement; if a database access error occurs or
0568: * this method is called on a closed <code>PreparedStatement</code>
0569: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0570: * @since 1.2
0571: */
0572: void setArray(int parameterIndex, Array x) throws SQLException;
0573:
0574: /**
0575: * Retrieves a <code>ResultSetMetaData</code> object that contains
0576: * information about the columns of the <code>ResultSet</code> object
0577: * that will be returned when this <code>PreparedStatement</code> object
0578: * is executed.
0579: * <P>
0580: * Because a <code>PreparedStatement</code> object is precompiled, it is
0581: * possible to know about the <code>ResultSet</code> object that it will
0582: * return without having to execute it. Consequently, it is possible
0583: * to invoke the method <code>getMetaData</code> on a
0584: * <code>PreparedStatement</code> object rather than waiting to execute
0585: * it and then invoking the <code>ResultSet.getMetaData</code> method
0586: * on the <code>ResultSet</code> object that is returned.
0587: * <P>
0588: * <B>NOTE:</B> Using this method may be expensive for some drivers due
0589: * to the lack of underlying DBMS support.
0590: *
0591: * @return the description of a <code>ResultSet</code> object's columns or
0592: * <code>null</code> if the driver cannot return a
0593: * <code>ResultSetMetaData</code> object
0594: * @exception SQLException if a database access error occurs or
0595: * this method is called on a closed <code>PreparedStatement</code>
0596: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0597: * this method
0598: * @since 1.2
0599: */
0600: ResultSetMetaData getMetaData() throws SQLException;
0601:
0602: /**
0603: * Sets the designated parameter to the given <code>java.sql.Date</code> value,
0604: * using the given <code>Calendar</code> object. The driver uses
0605: * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
0606: * which the driver then sends to the database. With
0607: * a <code>Calendar</code> object, the driver can calculate the date
0608: * taking into account a custom timezone. If no
0609: * <code>Calendar</code> object is specified, the driver uses the default
0610: * timezone, which is that of the virtual machine running the application.
0611: *
0612: * @param parameterIndex the first parameter is 1, the second is 2, ...
0613: * @param x the parameter value
0614: * @param cal the <code>Calendar</code> object the driver will use
0615: * to construct the date
0616: * @exception SQLException if parameterIndex does not correspond to a parameter
0617: * marker in the SQL statement; if a database access error occurs or
0618: * this method is called on a closed <code>PreparedStatement</code>
0619: * @since 1.2
0620: */
0621: void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
0622: throws SQLException;
0623:
0624: /**
0625: * Sets the designated parameter to the given <code>java.sql.Time</code> value,
0626: * using the given <code>Calendar</code> object. The driver uses
0627: * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
0628: * which the driver then sends to the database. With
0629: * a <code>Calendar</code> object, the driver can calculate the time
0630: * taking into account a custom timezone. If no
0631: * <code>Calendar</code> object is specified, the driver uses the default
0632: * timezone, which is that of the virtual machine running the application.
0633: *
0634: * @param parameterIndex the first parameter is 1, the second is 2, ...
0635: * @param x the parameter value
0636: * @param cal the <code>Calendar</code> object the driver will use
0637: * to construct the time
0638: * @exception SQLException if parameterIndex does not correspond to a parameter
0639: * marker in the SQL statement; if a database access error occurs or
0640: * this method is called on a closed <code>PreparedStatement</code>
0641: * @since 1.2
0642: */
0643: void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
0644: throws SQLException;
0645:
0646: /**
0647: * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
0648: * using the given <code>Calendar</code> object. The driver uses
0649: * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
0650: * which the driver then sends to the database. With a
0651: * <code>Calendar</code> object, the driver can calculate the timestamp
0652: * taking into account a custom timezone. If no
0653: * <code>Calendar</code> object is specified, the driver uses the default
0654: * timezone, which is that of the virtual machine running the application.
0655: *
0656: * @param parameterIndex the first parameter is 1, the second is 2, ...
0657: * @param x the parameter value
0658: * @param cal the <code>Calendar</code> object the driver will use
0659: * to construct the timestamp
0660: * @exception SQLException if parameterIndex does not correspond to a parameter
0661: * marker in the SQL statement; if a database access error occurs or
0662: * this method is called on a closed <code>PreparedStatement</code>
0663: * @since 1.2
0664: */
0665: void setTimestamp(int parameterIndex, java.sql.Timestamp x,
0666: Calendar cal) throws SQLException;
0667:
0668: /**
0669: * Sets the designated parameter to SQL <code>NULL</code>.
0670: * This version of the method <code>setNull</code> should
0671: * be used for user-defined types and REF type parameters. Examples
0672: * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
0673: * named array types.
0674: *
0675: * <P><B>Note:</B> To be portable, applications must give the
0676: * SQL type code and the fully-qualified SQL type name when specifying
0677: * a NULL user-defined or REF parameter. In the case of a user-defined type
0678: * the name is the type name of the parameter itself. For a REF
0679: * parameter, the name is the type name of the referenced type. If
0680: * a JDBC driver does not need the type code or type name information,
0681: * it may ignore it.
0682: *
0683: * Although it is intended for user-defined and Ref parameters,
0684: * this method may be used to set a null parameter of any JDBC type.
0685: * If the parameter does not have a user-defined or REF type, the given
0686: * typeName is ignored.
0687: *
0688: *
0689: * @param parameterIndex the first parameter is 1, the second is 2, ...
0690: * @param sqlType a value from <code>java.sql.Types</code>
0691: * @param typeName the fully-qualified name of an SQL user-defined type;
0692: * ignored if the parameter is not a user-defined type or REF
0693: * @exception SQLException if parameterIndex does not correspond to a parameter
0694: * marker in the SQL statement; if a database access error occurs or
0695: * this method is called on a closed <code>PreparedStatement</code>
0696: * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0697: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0698: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0699: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0700: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0701: * or <code>STRUCT</code> data type and the JDBC driver does not support
0702: * this data type or if the JDBC driver does not support this method
0703: * @since 1.2
0704: */
0705: void setNull(int parameterIndex, int sqlType, String typeName)
0706: throws SQLException;
0707:
0708: //------------------------- JDBC 3.0 -----------------------------------
0709:
0710: /**
0711: * Sets the designated parameter to the given <code>java.net.URL</code> value.
0712: * The driver converts this to an SQL <code>DATALINK</code> value
0713: * when it sends it to the database.
0714: *
0715: * @param parameterIndex the first parameter is 1, the second is 2, ...
0716: * @param x the <code>java.net.URL</code> object to be set
0717: * @exception SQLException if parameterIndex does not correspond to a parameter
0718: * marker in the SQL statement; if a database access error occurs or
0719: * this method is called on a closed <code>PreparedStatement</code>
0720: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0721: * @since 1.4
0722: */
0723: void setURL(int parameterIndex, java.net.URL x) throws SQLException;
0724:
0725: /**
0726: * Retrieves the number, types and properties of this
0727: * <code>PreparedStatement</code> object's parameters.
0728: *
0729: * @return a <code>ParameterMetaData</code> object that contains information
0730: * about the number, types and properties for each
0731: * parameter marker of this <code>PreparedStatement</code> object
0732: * @exception SQLException if a database access error occurs or
0733: * this method is called on a closed <code>PreparedStatement</code>
0734: * @see ParameterMetaData
0735: * @since 1.4
0736: */
0737: ParameterMetaData getParameterMetaData() throws SQLException;
0738:
0739: //------------------------- JDBC 4.0 -----------------------------------
0740:
0741: /**
0742: * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
0743: * driver converts this to a SQL <code>ROWID</code> value when it sends it
0744: * to the database
0745: *
0746: * @param parameterIndex the first parameter is 1, the second is 2, ...
0747: * @param x the parameter value
0748: * @throws SQLException if parameterIndex does not correspond to a parameter
0749: * marker in the SQL statement; if a database access error occurs or
0750: * this method is called on a closed <code>PreparedStatement</code>
0751: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0752: *
0753: * @since 1.6
0754: */
0755: void setRowId(int parameterIndex, RowId x) throws SQLException;
0756:
0757: /**
0758: * Sets the designated paramter to the given <code>String</code> object.
0759: * The driver converts this to a SQL <code>NCHAR</code> or
0760: * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
0761: * (depending on the argument's
0762: * size relative to the driver's limits on <code>NVARCHAR</code> values)
0763: * when it sends it to the database.
0764: *
0765: * @param parameterIndex of the first parameter is 1, the second is 2, ...
0766: * @param value the parameter value
0767: * @throws SQLException if parameterIndex does not correspond to a parameter
0768: * marker in the SQL statement; if the driver does not support national
0769: * character sets; if the driver can detect that a data conversion
0770: * error could occur; if a database access error occurs; or
0771: * this method is called on a closed <code>PreparedStatement</code>
0772: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0773: * @since 1.6
0774: */
0775: void setNString(int parameterIndex, String value)
0776: throws SQLException;
0777:
0778: /**
0779: * Sets the designated parameter to a <code>Reader</code> object. The
0780: * <code>Reader</code> reads the data till end-of-file is reached. The
0781: * driver does the necessary conversion from Java character format to
0782: * the national character set in the database.
0783: * @param parameterIndex of the first parameter is 1, the second is 2, ...
0784: * @param value the parameter value
0785: * @param length the number of characters in the parameter data.
0786: * @throws SQLException if parameterIndex does not correspond to a parameter
0787: * marker in the SQL statement; if the driver does not support national
0788: * character sets; if the driver can detect that a data conversion
0789: * error could occur; if a database access error occurs; or
0790: * this method is called on a closed <code>PreparedStatement</code>
0791: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0792: * @since 1.6
0793: */
0794: void setNCharacterStream(int parameterIndex, Reader value,
0795: long length) throws SQLException;
0796:
0797: /**
0798: * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
0799: * SQL <code>NCLOB</code> value when it sends it to the database.
0800: * @param parameterIndex of the first parameter is 1, the second is 2, ...
0801: * @param value the parameter value
0802: * @throws SQLException if parameterIndex does not correspond to a parameter
0803: * marker in the SQL statement; if the driver does not support national
0804: * character sets; if the driver can detect that a data conversion
0805: * error could occur; if a database access error occurs; or
0806: * this method is called on a closed <code>PreparedStatement</code>
0807: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0808: * @since 1.6
0809: */
0810: void setNClob(int parameterIndex, NClob value) throws SQLException;
0811:
0812: /**
0813: * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
0814: * of characters specified by length otherwise a <code>SQLException</code> will be
0815: * generated when the <code>PreparedStatement</code> is executed.
0816: *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
0817: * because it informs the driver that the parameter value should be sent to
0818: * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
0819: * driver may have to do extra work to determine whether the parameter
0820: * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
0821: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0822: * @param reader An object that contains the data to set the parameter value to.
0823: * @param length the number of characters in the parameter data.
0824: * @throws SQLException if parameterIndex does not correspond to a parameter
0825: * marker in the SQL statement; if a database access error occurs; this method is called on
0826: * a closed <code>PreparedStatement</code> or if the length specified is less than zero.
0827: *
0828: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0829: * @since 1.6
0830: */
0831: void setClob(int parameterIndex, Reader reader, long length)
0832: throws SQLException;
0833:
0834: /**
0835: * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
0836: * of characters specified by length otherwise a <code>SQLException</code> will be
0837: * generated when the <code>PreparedStatement</code> is executed.
0838: * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
0839: * method because it informs the driver that the parameter value should be
0840: * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
0841: * the driver may have to do extra work to determine whether the parameter
0842: * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
0843: * @param parameterIndex index of the first parameter is 1,
0844: * the second is 2, ...
0845: * @param inputStream An object that contains the data to set the parameter
0846: * value to.
0847: * @param length the number of bytes in the parameter data.
0848: * @throws SQLException if parameterIndex does not correspond to a parameter
0849: * marker in the SQL statement; if a database access error occurs;
0850: * this method is called on a closed <code>PreparedStatement</code>;
0851: * if the length specified
0852: * is less than zero or if the number of bytes in the inputstream does not match
0853: * the specfied length.
0854: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0855: *
0856: * @since 1.6
0857: */
0858: void setBlob(int parameterIndex, InputStream inputStream,
0859: long length) throws SQLException;
0860:
0861: /**
0862: * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
0863: * of characters specified by length otherwise a <code>SQLException</code> will be
0864: * generated when the <code>PreparedStatement</code> is executed.
0865: * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
0866: * because it informs the driver that the parameter value should be sent to
0867: * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
0868: * driver may have to do extra work to determine whether the parameter
0869: * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
0870: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0871: * @param reader An object that contains the data to set the parameter value to.
0872: * @param length the number of characters in the parameter data.
0873: * @throws SQLException if parameterIndex does not correspond to a parameter
0874: * marker in the SQL statement; if the length specified is less than zero;
0875: * if the driver does not support national character sets;
0876: * if the driver can detect that a data conversion
0877: * error could occur; if a database access error occurs or
0878: * this method is called on a closed <code>PreparedStatement</code>
0879: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0880: *
0881: * @since 1.6
0882: */
0883: void setNClob(int parameterIndex, Reader reader, long length)
0884: throws SQLException;
0885:
0886: /**
0887: * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object.
0888: * The driver converts this to an
0889: * SQL <code>XML</code> value when it sends it to the database.
0890: * <p>
0891: *
0892: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0893: * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
0894: * @throws SQLException if parameterIndex does not correspond to a parameter
0895: * marker in the SQL statement; if a database access error occurs;
0896: * this method is called on a closed <code>PreparedStatement</code>
0897: * or the <code>java.xml.transform.Result</code>,
0898: * <code>Writer</code> or <code>OutputStream</code> has not been closed for
0899: * the <code>SQLXML</code> object
0900: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0901: *
0902: * @since 1.6
0903: */
0904: void setSQLXML(int parameterIndex, SQLXML xmlObject)
0905: throws SQLException;
0906:
0907: /**
0908: * <p>Sets the value of the designated parameter with the given object. The second
0909: * argument must be an object type; for integral values, the
0910: * <code>java.lang</code> equivalent objects should be used.
0911: *
0912: * If the second argument is an <code>InputStream</code> then the stream must contain
0913: * the number of bytes specified by scaleOrLength. If the second argument is a
0914: * <code>Reader</code> then the reader must contain the number of characters specified
0915: * by scaleOrLength. If these conditions are not true the driver will generate a
0916: * <code>SQLException</code> when the prepared statement is executed.
0917: *
0918: * <p>The given Java object will be converted to the given targetSqlType
0919: * before being sent to the database.
0920: *
0921: * If the object has a custom mapping (is of a class implementing the
0922: * interface <code>SQLData</code>),
0923: * the JDBC driver should call the method <code>SQLData.writeSQL</code> to
0924: * write it to the SQL data stream.
0925: * If, on the other hand, the object is of a class implementing
0926: * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
0927: * <code>Struct</code>, <code>java.net.URL</code>,
0928: * or <code>Array</code>, the driver should pass it to the database as a
0929: * value of the corresponding SQL type.
0930: *
0931: * <p>Note that this method may be used to pass database-specific
0932: * abstract data types.
0933: *
0934: * @param parameterIndex the first parameter is 1, the second is 2, ...
0935: * @param x the object containing the input parameter value
0936: * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
0937: * sent to the database. The scale argument may further qualify this type.
0938: * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
0939: * or <code>java.sql.Types.NUMERIC types</code>,
0940: * this is the number of digits after the decimal point. For
0941: * Java Object types <code>InputStream</code> and <code>Reader</code>,
0942: * this is the length
0943: * of the data in the stream or reader. For all other types,
0944: * this value will be ignored.
0945: * @exception SQLException if parameterIndex does not correspond to a parameter
0946: * marker in the SQL statement; if a database access error occurs;
0947: * this method is called on a closed <code>PreparedStatement</code> or
0948: * if the Java Object specified by x is an InputStream
0949: * or Reader object and the value of the scale parameter is less
0950: * than zero
0951: * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
0952: * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0953: * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0954: * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0955: * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0956: * or <code>STRUCT</code> data type and the JDBC driver does not support
0957: * this data type
0958: * @see Types
0959: *
0960: * @since 1.6
0961: */
0962: void setObject(int parameterIndex, Object x, int targetSqlType,
0963: int scaleOrLength) throws SQLException;
0964:
0965: /**
0966: * Sets the designated parameter to the given input stream, which will have
0967: * the specified number of bytes.
0968: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
0969: * parameter, it may be more practical to send it via a
0970: * <code>java.io.InputStream</code>. Data will be read from the stream
0971: * as needed until end-of-file is reached. The JDBC driver will
0972: * do any necessary conversion from ASCII to the database char format.
0973: *
0974: * <P><B>Note:</B> This stream object can either be a standard
0975: * Java stream object or your own subclass that implements the
0976: * standard interface.
0977: *
0978: * @param parameterIndex the first parameter is 1, the second is 2, ...
0979: * @param x the Java input stream that contains the ASCII parameter value
0980: * @param length the number of bytes in the stream
0981: * @exception SQLException if parameterIndex does not correspond to a parameter
0982: * marker in the SQL statement; if a database access error occurs or
0983: * this method is called on a closed <code>PreparedStatement</code>
0984: * @since 1.6
0985: */
0986: void setAsciiStream(int parameterIndex, java.io.InputStream x,
0987: long length) throws SQLException;
0988:
0989: /**
0990: * Sets the designated parameter to the given input stream, which will have
0991: * the specified number of bytes.
0992: * When a very large binary value is input to a <code>LONGVARBINARY</code>
0993: * parameter, it may be more practical to send it via a
0994: * <code>java.io.InputStream</code> object. The data will be read from the
0995: * stream as needed until end-of-file is reached.
0996: *
0997: * <P><B>Note:</B> This stream object can either be a standard
0998: * Java stream object or your own subclass that implements the
0999: * standard interface.
1000: *
1001: * @param parameterIndex the first parameter is 1, the second is 2, ...
1002: * @param x the java input stream which contains the binary parameter value
1003: * @param length the number of bytes in the stream
1004: * @exception SQLException if parameterIndex does not correspond to a parameter
1005: * marker in the SQL statement; if a database access error occurs or
1006: * this method is called on a closed <code>PreparedStatement</code>
1007: * @since 1.6
1008: */
1009: void setBinaryStream(int parameterIndex, java.io.InputStream x,
1010: long length) throws SQLException;
1011:
1012: /**
1013: * Sets the designated parameter to the given <code>Reader</code>
1014: * object, which is the given number of characters long.
1015: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1016: * parameter, it may be more practical to send it via a
1017: * <code>java.io.Reader</code> object. The data will be read from the stream
1018: * as needed until end-of-file is reached. The JDBC driver will
1019: * do any necessary conversion from UNICODE to the database char format.
1020: *
1021: * <P><B>Note:</B> This stream object can either be a standard
1022: * Java stream object or your own subclass that implements the
1023: * standard interface.
1024: *
1025: * @param parameterIndex the first parameter is 1, the second is 2, ...
1026: * @param reader the <code>java.io.Reader</code> object that contains the
1027: * Unicode data
1028: * @param length the number of characters in the stream
1029: * @exception SQLException if parameterIndex does not correspond to a parameter
1030: * marker in the SQL statement; if a database access error occurs or
1031: * this method is called on a closed <code>PreparedStatement</code>
1032: * @since 1.6
1033: */
1034: void setCharacterStream(int parameterIndex, java.io.Reader reader,
1035: long length) throws SQLException;
1036:
1037: //-----
1038: /**
1039: * Sets the designated parameter to the given input stream.
1040: * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1041: * parameter, it may be more practical to send it via a
1042: * <code>java.io.InputStream</code>. Data will be read from the stream
1043: * as needed until end-of-file is reached. The JDBC driver will
1044: * do any necessary conversion from ASCII to the database char format.
1045: *
1046: * <P><B>Note:</B> This stream object can either be a standard
1047: * Java stream object or your own subclass that implements the
1048: * standard interface.
1049: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1050: * it might be more efficient to use a version of
1051: * <code>setAsciiStream</code> which takes a length parameter.
1052: *
1053: * @param parameterIndex the first parameter is 1, the second is 2, ...
1054: * @param x the Java input stream that contains the ASCII parameter value
1055: * @exception SQLException if parameterIndex does not correspond to a parameter
1056: * marker in the SQL statement; if a database access error occurs or
1057: * this method is called on a closed <code>PreparedStatement</code>
1058: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1059: * @since 1.6
1060: */
1061: void setAsciiStream(int parameterIndex, java.io.InputStream x)
1062: throws SQLException;
1063:
1064: /**
1065: * Sets the designated parameter to the given input stream.
1066: * When a very large binary value is input to a <code>LONGVARBINARY</code>
1067: * parameter, it may be more practical to send it via a
1068: * <code>java.io.InputStream</code> object. The data will be read from the
1069: * stream as needed until end-of-file is reached.
1070: *
1071: * <P><B>Note:</B> This stream object can either be a standard
1072: * Java stream object or your own subclass that implements the
1073: * standard interface.
1074: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1075: * it might be more efficient to use a version of
1076: * <code>setBinaryStream</code> which takes a length parameter.
1077: *
1078: * @param parameterIndex the first parameter is 1, the second is 2, ...
1079: * @param x the java input stream which contains the binary parameter value
1080: * @exception SQLException if parameterIndex does not correspond to a parameter
1081: * marker in the SQL statement; if a database access error occurs or
1082: * this method is called on a closed <code>PreparedStatement</code>
1083: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1084: * @since 1.6
1085: */
1086: void setBinaryStream(int parameterIndex, java.io.InputStream x)
1087: throws SQLException;
1088:
1089: /**
1090: * Sets the designated parameter to the given <code>Reader</code>
1091: * object.
1092: * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1093: * parameter, it may be more practical to send it via a
1094: * <code>java.io.Reader</code> object. The data will be read from the stream
1095: * as needed until end-of-file is reached. The JDBC driver will
1096: * do any necessary conversion from UNICODE to the database char format.
1097: *
1098: * <P><B>Note:</B> This stream object can either be a standard
1099: * Java stream object or your own subclass that implements the
1100: * standard interface.
1101: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1102: * it might be more efficient to use a version of
1103: * <code>setCharacterStream</code> which takes a length parameter.
1104: *
1105: * @param parameterIndex the first parameter is 1, the second is 2, ...
1106: * @param reader the <code>java.io.Reader</code> object that contains the
1107: * Unicode data
1108: * @exception SQLException if parameterIndex does not correspond to a parameter
1109: * marker in the SQL statement; if a database access error occurs or
1110: * this method is called on a closed <code>PreparedStatement</code>
1111: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1112: * @since 1.6
1113: */
1114: void setCharacterStream(int parameterIndex, java.io.Reader reader)
1115: throws SQLException;
1116:
1117: /**
1118: * Sets the designated parameter to a <code>Reader</code> object. The
1119: * <code>Reader</code> reads the data till end-of-file is reached. The
1120: * driver does the necessary conversion from Java character format to
1121: * the national character set in the database.
1122:
1123: * <P><B>Note:</B> This stream object can either be a standard
1124: * Java stream object or your own subclass that implements the
1125: * standard interface.
1126: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1127: * it might be more efficient to use a version of
1128: * <code>setNCharacterStream</code> which takes a length parameter.
1129: *
1130: * @param parameterIndex of the first parameter is 1, the second is 2, ...
1131: * @param value the parameter value
1132: * @throws SQLException if parameterIndex does not correspond to a parameter
1133: * marker in the SQL statement; if the driver does not support national
1134: * character sets; if the driver can detect that a data conversion
1135: * error could occur; if a database access error occurs; or
1136: * this method is called on a closed <code>PreparedStatement</code>
1137: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1138: * @since 1.6
1139: */
1140: void setNCharacterStream(int parameterIndex, Reader value)
1141: throws SQLException;
1142:
1143: /**
1144: * Sets the designated parameter to a <code>Reader</code> object.
1145: * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1146: * because it informs the driver that the parameter value should be sent to
1147: * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1148: * driver may have to do extra work to determine whether the parameter
1149: * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1150: *
1151: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1152: * it might be more efficient to use a version of
1153: * <code>setClob</code> which takes a length parameter.
1154: *
1155: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1156: * @param reader An object that contains the data to set the parameter value to.
1157: * @throws SQLException if parameterIndex does not correspond to a parameter
1158: * marker in the SQL statement; if a database access error occurs; this method is called on
1159: * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1160: * marker in the SQL statement
1161: *
1162: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1163: * @since 1.6
1164: */
1165: void setClob(int parameterIndex, Reader reader) throws SQLException;
1166:
1167: /**
1168: * Sets the designated parameter to a <code>InputStream</code> object.
1169: * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1170: * method because it informs the driver that the parameter value should be
1171: * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1172: * the driver may have to do extra work to determine whether the parameter
1173: * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1174: *
1175: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1176: * it might be more efficient to use a version of
1177: * <code>setBlob</code> which takes a length parameter.
1178: *
1179: * @param parameterIndex index of the first parameter is 1,
1180: * the second is 2, ...
1181: * @param inputStream An object that contains the data to set the parameter
1182: * value to.
1183: * @throws SQLException if parameterIndex does not correspond to a parameter
1184: * marker in the SQL statement; if a database access error occurs;
1185: * this method is called on a closed <code>PreparedStatement</code> or
1186: * if parameterIndex does not correspond
1187: * to a parameter marker in the SQL statement,
1188: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1189: *
1190: * @since 1.6
1191: */
1192: void setBlob(int parameterIndex, InputStream inputStream)
1193: throws SQLException;
1194:
1195: /**
1196: * Sets the designated parameter to a <code>Reader</code> object.
1197: * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1198: * because it informs the driver that the parameter value should be sent to
1199: * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
1200: * driver may have to do extra work to determine whether the parameter
1201: * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1202: * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1203: * it might be more efficient to use a version of
1204: * <code>setNClob</code> which takes a length parameter.
1205: *
1206: * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1207: * @param reader An object that contains the data to set the parameter value to.
1208: * @throws SQLException if parameterIndex does not correspond to a parameter
1209: * marker in the SQL statement;
1210: * if the driver does not support national character sets;
1211: * if the driver can detect that a data conversion
1212: * error could occur; if a database access error occurs or
1213: * this method is called on a closed <code>PreparedStatement</code>
1214: * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1215: *
1216: * @since 1.6
1217: */
1218: void setNClob(int parameterIndex, Reader reader)
1219: throws SQLException;
1220:
1221: }
|
