1. /*
  2. * @(#)CallableStatement.java 1.44 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.sql;
  8. import java.math.BigDecimal;
  9. import java.util.Calendar;
  10. /**
  11. * The interface used to execute SQL stored procedures. The JDBC API
  12. * provides a stored procedure SQL escape syntax that allows stored procedures
  13. * to be called in a standard way for all RDBMSs. This escape syntax has one
  14. * form that includes a result parameter and one that does not. If used, the result
  15. * parameter must be registered as an OUT parameter. The other parameters
  16. * can be used for input, output or both. Parameters are referred to
  17. * sequentially, by number, with the first parameter being 1.
  18. * <PRE>
  19. * {?= call <procedure-name>[<arg1>,<arg2>, ...]}
  20. * {call <procedure-name>[<arg1>,<arg2>, ...]}
  21. * </PRE>
  22. * <P>
  23. * IN parameter values are set using the <code>set</code> methods inherited from
  24. * {@link PreparedStatement}. The type of all OUT parameters must be
  25. * registered prior to executing the stored procedure; their values
  26. * are retrieved after execution via the <code>get</code> methods provided here.
  27. * <P>
  28. * A <code>CallableStatement</code> can return one {@link ResultSet} object or
  29. * multiple <code>ResultSet</code> objects. Multiple
  30. * <code>ResultSet</code> objects are handled using operations
  31. * inherited from {@link Statement}.
  32. * <P>
  33. * For maximum portability, a call's <code>ResultSet</code> objects and
  34. * update counts should be processed prior to getting the values of output
  35. * parameters.
  36. * <P>
  37. *
  38. * @see Connection#prepareCall
  39. * @see ResultSet
  40. */
  41. public interface CallableStatement extends PreparedStatement {
  42. /**
  43. * Registers the OUT parameter in ordinal position
  44. * <code>parameterIndex</code> to the JDBC type
  45. * <code>sqlType</code>. All OUT parameters must be registered
  46. * before a stored procedure is executed.
  47. * <p>
  48. * The JDBC type specified by <code>sqlType</code> for an OUT
  49. * parameter determines the Java type that must be used
  50. * in the <code>get</code> method to read the value of that parameter.
  51. * <p>
  52. * If the JDBC type expected to be returned to this output parameter
  53. * is specific to this particular database, <code>sqlType</code>
  54. * should be <code>java.sql.Types.OTHER</code>. The method
  55. * {@link #getObject} retrieves the value.
  56. *
  57. * @param parameterIndex the first parameter is 1, the second is 2,
  58. * and so on
  59. * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
  60. * If the parameter is of JDBC type <code>NUMERIC</code>
  61. * or <code>DECIMAL</code>, the version of
  62. * <code>registerOutParameter</code> that accepts a scale value
  63. * should be used.
  64. *
  65. * @exception SQLException if a database access error occurs
  66. * @see Types
  67. */
  68. void registerOutParameter(int parameterIndex, int sqlType)
  69. throws SQLException;
  70. /**
  71. * Registers the parameter in ordinal position
  72. * <code>parameterIndex</code> to be of JDBC type
  73. * <code>sqlType</code>. This method must be called
  74. * before a stored procedure is executed.
  75. * <p>
  76. * The JDBC type specified by <code>sqlType</code> for an OUT
  77. * parameter determines the Java type that must be used
  78. * in the <code>get</code> method to read the value of that parameter.
  79. * <p>
  80. * This version of <code>registerOutParameter</code> should be
  81. * used when the parameter is of JDBC type <code>NUMERIC</code>
  82. * or <code>DECIMAL</code>.
  83. *
  84. * @param parameterIndex the first parameter is 1, the second is 2,
  85. * and so on
  86. * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
  87. * @param scale the desired number of digits to the right of the
  88. * decimal point. It must be greater than or equal to zero.
  89. * @exception SQLException if a database access error occurs
  90. * @see Types
  91. */
  92. void registerOutParameter(int parameterIndex, int sqlType, int scale)
  93. throws SQLException;
  94. /**
  95. * Retrieves whether the last OUT parameter read had the value of
  96. * SQL <code>NULL</code>. Note that this method should be called only after
  97. * calling a getter method; otherwise, there is no value to use in
  98. * determining whether it is <code>null</code> or not.
  99. *
  100. * @return <code>true</code> if the last parameter read was SQL
  101. * <code>NULL</code> <code>false</code> otherwise
  102. * @exception SQLException if a database access error occurs
  103. */
  104. boolean wasNull() throws SQLException;
  105. /**
  106. * Retrieves the value of the designated JDBC <code>CHAR</code>,
  107. * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
  108. * <code>String</code> in the Java programming language.
  109. * <p>
  110. * For the fixed-length type JDBC <code>CHAR</code>,
  111. * the <code>String</code> object
  112. * returned has exactly the same value the JDBC
  113. * <code>CHAR</code> value had in the
  114. * database, including any padding added by the database.
  115. *
  116. * @param parameterIndex the first parameter is 1, the second is 2,
  117. * and so on
  118. * @return the parameter value. If the value is SQL <code>NULL</code>,
  119. * the result
  120. * is <code>null</code>.
  121. * @exception SQLException if a database access error occurs
  122. * @see #setString
  123. */
  124. String getString(int parameterIndex) throws SQLException;
  125. /**
  126. * Retrieves the value of the designated JDBC <code>BIT</code> parameter as a
  127. * <code>boolean</code> in the Java programming language.
  128. *
  129. * @param parameterIndex the first parameter is 1, the second is 2,
  130. * and so on
  131. * @return the parameter value. If the value is SQL <code>NULL</code>,
  132. * the result is <code>false</code>.
  133. * @exception SQLException if a database access error occurs
  134. * @see #setBoolean
  135. */
  136. boolean getBoolean(int parameterIndex) throws SQLException;
  137. /**
  138. * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
  139. * as a <code>byte</code> in the Java programming language.
  140. *
  141. * @param parameterIndex the first parameter is 1, the second is 2,
  142. * and so on
  143. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  144. * is <code>0</code>.
  145. * @exception SQLException if a database access error occurs
  146. * @see #setByte
  147. */
  148. byte getByte(int parameterIndex) throws SQLException;
  149. /**
  150. * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
  151. * as a <code>short</code> in the Java programming language.
  152. *
  153. * @param parameterIndex the first parameter is 1, the second is 2,
  154. * and so on
  155. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  156. * is <code>0</code>.
  157. * @exception SQLException if a database access error occurs
  158. * @see #setShort
  159. */
  160. short getShort(int parameterIndex) throws SQLException;
  161. /**
  162. * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
  163. * as an <code>int</code> in the Java programming language.
  164. *
  165. * @param parameterIndex the first parameter is 1, the second is 2,
  166. * and so on
  167. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  168. * is <code>0</code>.
  169. * @exception SQLException if a database access error occurs
  170. * @see #setInt
  171. */
  172. int getInt(int parameterIndex) throws SQLException;
  173. /**
  174. * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
  175. * as a <code>long</code> in the Java programming language.
  176. *
  177. * @param parameterIndex the first parameter is 1, the second is 2,
  178. * and so on
  179. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  180. * is <code>0</code>.
  181. * @exception SQLException if a database access error occurs
  182. * @see #setLong
  183. */
  184. long getLong(int parameterIndex) throws SQLException;
  185. /**
  186. * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
  187. * as a <code>float</code> in the Java programming language.
  188. *
  189. * @param parameterIndex the first parameter is 1, the second is 2,
  190. * and so on
  191. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  192. * is <code>0</code>.
  193. * @exception SQLException if a database access error occurs
  194. * @see #setFloat
  195. */
  196. float getFloat(int parameterIndex) throws SQLException;
  197. /**
  198. * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
  199. * in the Java programming language.
  200. * @param parameterIndex the first parameter is 1, the second is 2,
  201. * and so on
  202. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  203. * is <code>0</code>.
  204. * @exception SQLException if a database access error occurs
  205. * @see #setDouble
  206. */
  207. double getDouble(int parameterIndex) throws SQLException;
  208. /**
  209. * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
  210. * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
  211. * the right of the decimal point.
  212. * @param parameterIndex the first parameter is 1, the second is 2,
  213. * and so on
  214. * @param scale the number of digits to the right of the decimal point
  215. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  216. * is <code>null</code>.
  217. * @exception SQLException if a database access error occurs
  218. * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
  219. * or <code>getBigDecimal(String parameterName)</code>
  220. * @see #setBigDecimal
  221. */
  222. BigDecimal getBigDecimal(int parameterIndex, int scale)
  223. throws SQLException;
  224. /**
  225. * Retrieves the value of the designated JDBC <code>BINARY</code> or
  226. * <code>VARBINARY</code> parameter as an array of <code>byte</code>
  227. * values in the Java programming language.
  228. * @param parameterIndex the first parameter is 1, the second is 2,
  229. * and so on
  230. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  231. * is <code>null</code>.
  232. * @exception SQLException if a database access error occurs
  233. * @see #setBytes
  234. */
  235. byte[] getBytes(int parameterIndex) throws SQLException;
  236. /**
  237. * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
  238. * <code>java.sql.Date</code> object.
  239. * @param parameterIndex the first parameter is 1, the second is 2,
  240. * and so on
  241. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  242. * is <code>null</code>.
  243. * @exception SQLException if a database access error occurs
  244. * @see #setDate
  245. */
  246. java.sql.Date getDate(int parameterIndex) throws SQLException;
  247. /**
  248. * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
  249. * <code>java.sql.Time</code> object.
  250. *
  251. * @param parameterIndex the first parameter is 1, the second is 2,
  252. * and so on
  253. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  254. * is <code>null</code>.
  255. * @exception SQLException if a database access error occurs
  256. * @see #setTime
  257. */
  258. java.sql.Time getTime(int parameterIndex) throws SQLException;
  259. /**
  260. * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
  261. * <code>java.sql.Timestamp</code> object.
  262. *
  263. * @param parameterIndex the first parameter is 1, the second is 2,
  264. * and so on
  265. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  266. * is <code>null</code>.
  267. * @exception SQLException if a database access error occurs
  268. * @see #setTimestamp
  269. */
  270. java.sql.Timestamp getTimestamp(int parameterIndex)
  271. throws SQLException;
  272. //----------------------------------------------------------------------
  273. // Advanced features:
  274. /**
  275. * Retrieves the value of the designated parameter as an <code>Object</code>
  276. * in the Java programming language. If the value is an SQL <code>NULL</code>,
  277. * the driver returns a Java <code>null</code>.
  278. * <p>
  279. * This method returns a Java object whose type corresponds to the JDBC
  280. * type that was registered for this parameter using the method
  281. * <code>registerOutParameter</code>. By registering the target JDBC
  282. * type as <code>java.sql.Types.OTHER</code>, this method can be used
  283. * to read database-specific abstract data types.
  284. *
  285. * @param parameterIndex the first parameter is 1, the second is 2,
  286. * and so on
  287. * @return A <code>java.lang.Object</code> holding the OUT parameter value
  288. * @exception SQLException if a database access error occurs
  289. * @see Types
  290. * @see #setObject
  291. */
  292. Object getObject(int parameterIndex) throws SQLException;
  293. //--------------------------JDBC 2.0-----------------------------
  294. /**
  295. * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
  296. * <code>java.math.BigDecimal</code> object with as many digits to the
  297. * right of the decimal point as the value contains.
  298. * @param parameterIndex the first parameter is 1, the second is 2,
  299. * and so on
  300. * @return the parameter value in full precision. If the value is
  301. * SQL <code>NULL</code>, the result is <code>null</code>.
  302. * @exception SQLException if a database access error occurs
  303. * @see #setBigDecimal
  304. * @since 1.2
  305. */
  306. BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
  307. /**
  308. * Returns an object representing the value of OUT parameter
  309. * <code>i</code> and uses <code>map</code> for the custom
  310. * mapping of the parameter value.
  311. * <p>
  312. * This method returns a Java object whose type corresponds to the
  313. * JDBC type that was registered for this parameter using the method
  314. * <code>registerOutParameter</code>. By registering the target
  315. * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
  316. * be used to read database-specific abstract data types.
  317. * @param i the first parameter is 1, the second is 2, and so on
  318. * @param map the mapping from SQL type names to Java classes
  319. * @return a <code>java.lang.Object</code> holding the OUT parameter value
  320. * @exception SQLException if a database access error occurs
  321. * @see #setObject
  322. * @since 1.2
  323. */
  324. Object getObject (int i, java.util.Map map) throws SQLException;
  325. /**
  326. * Retrieves the value of the designated JDBC <code>REF(<structured-type>)</code>
  327. * parameter as a {@link Ref} object in the Java programming language.
  328. * @param i the first parameter is 1, the second is 2,
  329. * and so on
  330. * @return the parameter value as a <code>Ref</code> object in the
  331. * Java programming language. If the value was SQL <code>NULL</code>, the value
  332. * <code>null</code> is returned.
  333. * @exception SQLException if a database access error occurs
  334. * @since 1.2
  335. */
  336. Ref getRef (int i) throws SQLException;
  337. /**
  338. * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
  339. * {@link Blob} object in the Java programming language.
  340. * @param i the first parameter is 1, the second is 2, and so on
  341. * @return the parameter value as a <code>Blob</code> object in the
  342. * Java programming language. If the value was SQL <code>NULL</code>, the value
  343. * <code>null</code> is returned.
  344. * @exception SQLException if a database access error occurs
  345. * @since 1.2
  346. */
  347. Blob getBlob (int i) throws SQLException;
  348. /**
  349. * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
  350. * <code>Clob</code> object in the Java programming language.
  351. * @param i the first parameter is 1, the second is 2, and
  352. * so on
  353. * @return the parameter value as a <code>Clob</code> object in the
  354. * Java programming language. If the value was SQL <code>NULL</code>, the
  355. * value <code>null</code> is returned.
  356. * @exception SQLException if a database access error occurs
  357. * @since 1.2
  358. */
  359. Clob getClob (int i) throws SQLException;
  360. /**
  361. *
  362. * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
  363. * {@link Array} object in the Java programming language.
  364. * @param i the first parameter is 1, the second is 2, and
  365. * so on
  366. * @return the parameter value as an <code>Array</code> object in
  367. * the Java programming language. If the value was SQL <code>NULL</code>, the
  368. * value <code>null</code> is returned.
  369. * @exception SQLException if a database access error occurs
  370. * @since 1.2
  371. */
  372. Array getArray (int i) throws SQLException;
  373. /**
  374. * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
  375. * <code>java.sql.Date</code> object, using
  376. * the given <code>Calendar</code> object
  377. * to construct the date.
  378. * With a <code>Calendar</code> object, the driver
  379. * can calculate the date taking into account a custom timezone and locale.
  380. * If no <code>Calendar</code> object is specified, the driver uses the
  381. * default timezone and locale.
  382. *
  383. * @param parameterIndex the first parameter is 1, the second is 2,
  384. * and so on
  385. * @param cal the <code>Calendar</code> object the driver will use
  386. * to construct the date
  387. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  388. * is <code>null</code>.
  389. * @exception SQLException if a database access error occurs
  390. * @see #setDate
  391. * @since 1.2
  392. */
  393. java.sql.Date getDate(int parameterIndex, Calendar cal)
  394. throws SQLException;
  395. /**
  396. * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
  397. * <code>java.sql.Time</code> object, using
  398. * the given <code>Calendar</code> object
  399. * to construct the time.
  400. * With a <code>Calendar</code> object, the driver
  401. * can calculate the time taking into account a custom timezone and locale.
  402. * If no <code>Calendar</code> object is specified, the driver uses the
  403. * default timezone and locale.
  404. *
  405. * @param parameterIndex the first parameter is 1, the second is 2,
  406. * and so on
  407. * @param cal the <code>Calendar</code> object the driver will use
  408. * to construct the time
  409. * @return the parameter value; if the value is SQL <code>NULL</code>, the result
  410. * is <code>null</code>.
  411. * @exception SQLException if a database access error occurs
  412. * @see #setTime
  413. * @since 1.2
  414. */
  415. java.sql.Time getTime(int parameterIndex, Calendar cal)
  416. throws SQLException;
  417. /**
  418. * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
  419. * <code>java.sql.Timestamp</code> object, using
  420. * the given <code>Calendar</code> object to construct
  421. * the <code>Timestamp</code> object.
  422. * With a <code>Calendar</code> object, the driver
  423. * can calculate the timestamp taking into account a custom timezone and locale.
  424. * If no <code>Calendar</code> object is specified, the driver uses the
  425. * default timezone and locale.
  426. *
  427. *
  428. * @param parameterIndex the first parameter is 1, the second is 2,
  429. * and so on
  430. * @param cal the <code>Calendar</code> object the driver will use
  431. * to construct the timestamp
  432. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  433. * is <code>null</code>.
  434. * @exception SQLException if a database access error occurs
  435. * @see #setTimestamp
  436. * @since 1.2
  437. */
  438. java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
  439. throws SQLException;
  440. /**
  441. * Registers the designated output parameter. This version of
  442. * the method <code>registerOutParameter</code>
  443. * should be used for a user-defined or <code>REF</code> output parameter. Examples
  444. * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
  445. * <code>JAVA_OBJECT</code>, and named array types.
  446. *
  447. * Before executing a stored procedure call, you must explicitly
  448. * call <code>registerOutParameter</code> to register the type from
  449. * <code>java.sql.Types</code> for each
  450. * OUT parameter. For a user-defined parameter, the fully-qualified SQL
  451. * type name of the parameter should also be given, while a <code>REF</code>
  452. * parameter requires that the fully-qualified type name of the
  453. * referenced type be given. A JDBC driver that does not need the
  454. * type code and type name information may ignore it. To be portable,
  455. * however, applications should always provide these values for
  456. * user-defined and <code>REF</code> parameters.
  457. *
  458. * Although it is intended for user-defined and <code>REF</code> parameters,
  459. * this method may be used to register a parameter of any JDBC type.
  460. * If the parameter does not have a user-defined or <code>REF</code> type, the
  461. * <i>typeName</i> parameter is ignored.
  462. *
  463. * <P><B>Note:</B> When reading the value of an out parameter, you
  464. * must use the getter method whose Java type corresponds to the
  465. * parameter's registered SQL type.
  466. *
  467. * @param paramIndex the first parameter is 1, the second is 2,...
  468. * @param sqlType a value from {@link java.sql.Types}
  469. * @param typeName the fully-qualified name of an SQL structured type
  470. * @exception SQLException if a database access error occurs
  471. * @see Types
  472. * @since 1.2
  473. */
  474. void registerOutParameter (int paramIndex, int sqlType, String typeName)
  475. throws SQLException;
  476. //--------------------------JDBC 3.0-----------------------------
  477. /**
  478. * Registers the OUT parameter named
  479. * <code>parameterName</code> to the JDBC type
  480. * <code>sqlType</code>. All OUT parameters must be registered
  481. * before a stored procedure is executed.
  482. * <p>
  483. * The JDBC type specified by <code>sqlType</code> for an OUT
  484. * parameter determines the Java type that must be used
  485. * in the <code>get</code> method to read the value of that parameter.
  486. * <p>
  487. * If the JDBC type expected to be returned to this output parameter
  488. * is specific to this particular database, <code>sqlType</code>
  489. * should be <code>java.sql.Types.OTHER</code>. The method
  490. * {@link #getObject} retrieves the value.
  491. * @param parameterName the name of the parameter
  492. * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
  493. * If the parameter is of JDBC type <code>NUMERIC</code>
  494. * or <code>DECIMAL</code>, the version of
  495. * <code>registerOutParameter</code> that accepts a scale value
  496. * should be used.
  497. * @exception SQLException if a database access error occurs
  498. * @since 1.4
  499. * @see Types
  500. */
  501. void registerOutParameter(String parameterName, int sqlType)
  502. throws SQLException;
  503. /**
  504. * Registers the parameter named
  505. * <code>parameterName</code> to be of JDBC type
  506. * <code>sqlType</code>. This method must be called
  507. * before a stored procedure is executed.
  508. * <p>
  509. * The JDBC type specified by <code>sqlType</code> for an OUT
  510. * parameter determines the Java type that must be used
  511. * in the <code>get</code> method to read the value of that parameter.
  512. * <p>
  513. * This version of <code>registerOutParameter</code> should be
  514. * used when the parameter is of JDBC type <code>NUMERIC</code>
  515. * or <code>DECIMAL</code>.
  516. * @param parameterName the name of the parameter
  517. * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
  518. * @param scale the desired number of digits to the right of the
  519. * decimal point. It must be greater than or equal to zero.
  520. * @exception SQLException if a database access error occurs
  521. * @since 1.4
  522. * @see Types
  523. */
  524. void registerOutParameter(String parameterName, int sqlType, int scale)
  525. throws SQLException;
  526. /**
  527. * Registers the designated output parameter. This version of
  528. * the method <code>registerOutParameter</code>
  529. * should be used for a user-named or REF output parameter. Examples
  530. * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
  531. * named array types.
  532. *
  533. * Before executing a stored procedure call, you must explicitly
  534. * call <code>registerOutParameter</code> to register the type from
  535. * <code>java.sql.Types</code> for each
  536. * OUT parameter. For a user-named parameter the fully-qualified SQL
  537. * type name of the parameter should also be given, while a REF
  538. * parameter requires that the fully-qualified type name of the
  539. * referenced type be given. A JDBC driver that does not need the
  540. * type code and type name information may ignore it. To be portable,
  541. * however, applications should always provide these values for
  542. * user-named and REF parameters.
  543. *
  544. * Although it is intended for user-named and REF parameters,
  545. * this method may be used to register a parameter of any JDBC type.
  546. * If the parameter does not have a user-named or REF type, the
  547. * typeName parameter is ignored.
  548. *
  549. * <P><B>Note:</B> When reading the value of an out parameter, you
  550. * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
  551. * parameter's registered SQL type.
  552. *
  553. * @param parameterName the name of the parameter
  554. * @param sqlType a value from {@link java.sql.Types}
  555. * @param typeName the fully-qualified name of an SQL structured type
  556. * @exception SQLException if a database access error occurs
  557. * @see Types
  558. * @since 1.4
  559. */
  560. void registerOutParameter (String parameterName, int sqlType, String typeName)
  561. throws SQLException;
  562. /**
  563. * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
  564. * <code>java.net.URL</code> object.
  565. *
  566. * @param parameterIndex the first parameter is 1, the second is 2,...
  567. * @return a <code>java.net.URL</code> object that represents the
  568. * JDBC <code>DATALINK</code> value used as the designated
  569. * parameter
  570. * @exception SQLException if a database access error occurs,
  571. * or if the URL being returned is
  572. * not a valid URL on the Java platform
  573. * @see #setURL
  574. * @since 1.4
  575. */
  576. java.net.URL getURL(int parameterIndex) throws SQLException;
  577. /**
  578. * Sets the designated parameter to the given <code>java.net.URL</code> object.
  579. * The driver converts this to an SQL <code>DATALINK</code> value when
  580. * it sends it to the database.
  581. *
  582. * @param parameterName the name of the parameter
  583. * @param val the parameter value
  584. * @exception SQLException if a database access error occurs,
  585. * or if a URL is malformed
  586. * @see #getURL
  587. * @since 1.4
  588. */
  589. void setURL(String parameterName, java.net.URL val) throws SQLException;
  590. /**
  591. * Sets the designated parameter to SQL <code>NULL</code>.
  592. *
  593. * <P><B>Note:</B> You must specify the parameter's SQL type.
  594. *
  595. * @param parameterName the name of the parameter
  596. * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
  597. * @exception SQLException if a database access error occurs
  598. * @since 1.4
  599. */
  600. void setNull(String parameterName, int sqlType) throws SQLException;
  601. /**
  602. * Sets the designated parameter to the given Java <code>boolean</code> value.
  603. * The driver converts this
  604. * to an SQL <code>BIT</code> value when it sends it to the database.
  605. *
  606. * @param parameterName the name of the parameter
  607. * @param x the parameter value
  608. * @exception SQLException if a database access error occurs
  609. * @see #getBoolean
  610. * @since 1.4
  611. */
  612. void setBoolean(String parameterName, boolean x) throws SQLException;
  613. /**
  614. * Sets the designated parameter to the given Java <code>byte</code> value.
  615. * The driver converts this
  616. * to an SQL <code>TINYINT</code> value when it sends it to the database.
  617. *
  618. * @param parameterName the name of the parameter
  619. * @param x the parameter value
  620. * @exception SQLException if a database access error occurs
  621. * @see #getByte
  622. * @since 1.4
  623. */
  624. void setByte(String parameterName, byte x) throws SQLException;
  625. /**
  626. * Sets the designated parameter to the given Java <code>short</code> value.
  627. * The driver converts this
  628. * to an SQL <code>SMALLINT</code> value when it sends it to the database.
  629. *
  630. * @param parameterName the name of the parameter
  631. * @param x the parameter value
  632. * @exception SQLException if a database access error occurs
  633. * @see #getShort
  634. * @since 1.4
  635. */
  636. void setShort(String parameterName, short x) throws SQLException;
  637. /**
  638. * Sets the designated parameter to the given Java <code>int</code> value.
  639. * The driver converts this
  640. * to an SQL <code>INTEGER</code> value when it sends it to the database.
  641. *
  642. * @param parameterName the name of the parameter
  643. * @param x the parameter value
  644. * @exception SQLException if a database access error occurs
  645. * @see #getInt
  646. * @since 1.4
  647. */
  648. void setInt(String parameterName, int x) throws SQLException;
  649. /**
  650. * Sets the designated parameter to the given Java <code>long</code> value.
  651. * The driver converts this
  652. * to an SQL <code>BIGINT</code> value when it sends it to the database.
  653. *
  654. * @param parameterName the name of the parameter
  655. * @param x the parameter value
  656. * @exception SQLException if a database access error occurs
  657. * @see #getLong
  658. * @since 1.4
  659. */
  660. void setLong(String parameterName, long x) throws SQLException;
  661. /**
  662. * Sets the designated parameter to the given Java <code>float</code> value.
  663. * The driver converts this
  664. * to an SQL <code>FLOAT</code> value when it sends it to the database.
  665. *
  666. * @param parameterName the name of the parameter
  667. * @param x the parameter value
  668. * @exception SQLException if a database access error occurs
  669. * @see #getFloat
  670. * @since 1.4
  671. */
  672. void setFloat(String parameterName, float x) throws SQLException;
  673. /**
  674. * Sets the designated parameter to the given Java <code>double</code> value.
  675. * The driver converts this
  676. * to an SQL <code>DOUBLE</code> value when it sends it to the database.
  677. *
  678. * @param parameterName the name of the parameter
  679. * @param x the parameter value
  680. * @exception SQLException if a database access error occurs
  681. * @see #getDouble
  682. * @since 1.4
  683. */
  684. void setDouble(String parameterName, double x) throws SQLException;
  685. /**
  686. * Sets the designated parameter to the given
  687. * <code>java.math.BigDecimal</code> value.
  688. * The driver converts this to an SQL <code>NUMERIC</code> value when
  689. * it sends it to the database.
  690. *
  691. * @param parameterName the name of the parameter
  692. * @param x the parameter value
  693. * @exception SQLException if a database access error occurs
  694. * @see #getBigDecimal
  695. * @since 1.4
  696. */
  697. void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
  698. /**
  699. * Sets the designated parameter to the given Java <code>String</code> value.
  700. * The driver converts this
  701. * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
  702. * (depending on the argument's
  703. * size relative to the driver's limits on <code>VARCHAR</code> values)
  704. * when it sends it to the database.
  705. *
  706. * @param parameterName the name of the parameter
  707. * @param x the parameter value
  708. * @exception SQLException if a database access error occurs
  709. * @see #getString
  710. * @since 1.4
  711. */
  712. void setString(String parameterName, String x) throws SQLException;
  713. /**
  714. * Sets the designated parameter to the given Java array of bytes.
  715. * The driver converts this to an SQL <code>VARBINARY</code> or
  716. * <code>LONGVARBINARY</code> (depending on the argument's size relative
  717. * to the driver's limits on <code>VARBINARY</code> values) when it sends
  718. * it to the database.
  719. *
  720. * @param parameterName the name of the parameter
  721. * @param x the parameter value
  722. * @exception SQLException if a database access error occurs
  723. * @see #getBytes
  724. * @since 1.4
  725. */
  726. void setBytes(String parameterName, byte x[]) throws SQLException;
  727. /**
  728. * Sets the designated parameter to the given <code>java.sql.Date</code> value.
  729. * The driver converts this
  730. * to an SQL <code>DATE</code> value when it sends it to the database.
  731. *
  732. * @param parameterName the name of the parameter
  733. * @param x the parameter value
  734. * @exception SQLException if a database access error occurs
  735. * @see #getDate
  736. * @since 1.4
  737. */
  738. void setDate(String parameterName, java.sql.Date x)
  739. throws SQLException;
  740. /**
  741. * Sets the designated parameter to the given <code>java.sql.Time</code> value.
  742. * The driver converts this
  743. * to an SQL <code>TIME</code> value when it sends it to the database.
  744. *
  745. * @param parameterName the name of the parameter
  746. * @param x the parameter value
  747. * @exception SQLException if a database access error occurs
  748. * @see #getTime
  749. * @since 1.4
  750. */
  751. void setTime(String parameterName, java.sql.Time x)
  752. throws SQLException;
  753. /**
  754. * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
  755. * The driver
  756. * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
  757. * database.
  758. *
  759. * @param parameterName the name of the parameter
  760. * @param x the parameter value
  761. * @exception SQLException if a database access error occurs
  762. * @see #getTimestamp
  763. * @since 1.4
  764. */
  765. void setTimestamp(String parameterName, java.sql.Timestamp x)
  766. throws SQLException;
  767. /**
  768. * Sets the designated parameter to the given input stream, which will have
  769. * the specified number of bytes.
  770. * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
  771. * parameter, it may be more practical to send it via a
  772. * <code>java.io.InputStream</code>. Data will be read from the stream
  773. * as needed until end-of-file is reached. The JDBC driver will
  774. * do any necessary conversion from ASCII to the database char format.
  775. *
  776. * <P><B>Note:</B> This stream object can either be a standard
  777. * Java stream object or your own subclass that implements the
  778. * standard interface.
  779. *
  780. * @param parameterName the name of the parameter
  781. * @param x the Java input stream that contains the ASCII parameter value
  782. * @param length the number of bytes in the stream
  783. * @exception SQLException if a database access error occurs
  784. * @since 1.4
  785. */
  786. void setAsciiStream(String parameterName, java.io.InputStream x, int length)
  787. throws SQLException;
  788. /**
  789. * Sets the designated parameter to the given input stream, which will have
  790. * the specified number of bytes.
  791. * When a very large binary value is input to a <code>LONGVARBINARY</code>
  792. * parameter, it may be more practical to send it via a
  793. * <code>java.io.InputStream</code> object. The data will be read from the stream
  794. * as needed until end-of-file is reached.
  795. *
  796. * <P><B>Note:</B> This stream object can either be a standard
  797. * Java stream object or your own subclass that implements the
  798. * standard interface.
  799. *
  800. * @param parameterName the name of the parameter
  801. * @param x the java input stream which contains the binary parameter value
  802. * @param length the number of bytes in the stream
  803. * @exception SQLException if a database access error occurs
  804. * @since 1.4
  805. */
  806. void setBinaryStream(String parameterName, java.io.InputStream x,
  807. int length) throws SQLException;
  808. /**
  809. * Sets the value of the designated parameter with the given object. The second
  810. * argument must be an object type; for integral values, the
  811. * <code>java.lang</code> equivalent objects should be used.
  812. *
  813. * <p>The given Java object will be converted to the given targetSqlType
  814. * before being sent to the database.
  815. *
  816. * If the object has a custom mapping (is of a class implementing the
  817. * interface <code>SQLData</code>),
  818. * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
  819. * to the SQL data stream.
  820. * If, on the other hand, the object is of a class implementing
  821. * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>Struct</code>,
  822. * or <code>Array</code>, the driver should pass it to the database as a
  823. * value of the corresponding SQL type.
  824. * <P>
  825. * Note that this method may be used to pass datatabase-
  826. * specific abstract data types.
  827. *
  828. * @param parameterName the name of the parameter
  829. * @param x the object containing the input parameter value
  830. * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
  831. * sent to the database. The scale argument may further qualify this type.
  832. * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
  833. * this is the number of digits after the decimal point. For all other
  834. * types, this value will be ignored.
  835. * @exception SQLException if a database access error occurs
  836. * @see Types
  837. * @see #getObject
  838. * @since 1.4
  839. */
  840. void setObject(String parameterName, Object x, int targetSqlType, int scale)
  841. throws SQLException;
  842. /**
  843. * Sets the value of the designated parameter with the given object.
  844. * This method is like the method <code>setObject</code>
  845. * above, except that it assumes a scale of zero.
  846. *
  847. * @param parameterName the name of the parameter
  848. * @param x the object containing the input parameter value
  849. * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
  850. * sent to the database
  851. * @exception SQLException if a database access error occurs
  852. * @see #getObject
  853. * @since 1.4
  854. */
  855. void setObject(String parameterName, Object x, int targetSqlType)
  856. throws SQLException;
  857. /**
  858. * Sets the value of the designated parameter with the given object.
  859. * The second parameter must be of type <code>Object</code> therefore, the
  860. * <code>java.lang</code> equivalent objects should be used for built-in types.
  861. *
  862. * <p>The JDBC specification specifies a standard mapping from
  863. * Java <code>Object</code> types to SQL types. The given argument
  864. * will be converted to the corresponding SQL type before being
  865. * sent to the database.
  866. *
  867. * <p>Note that this method may be used to pass datatabase-
  868. * specific abstract data types, by using a driver-specific Java
  869. * type.
  870. *
  871. * If the object is of a class implementing the interface <code>SQLData</code>,
  872. * the JDBC driver should call the method <code>SQLData.writeSQL</code>
  873. * to write it to the SQL data stream.
  874. * If, on the other hand, the object is of a class implementing
  875. * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>Struct</code>,
  876. * or <code>Array</code>, the driver should pass it to the database as a
  877. * value of the corresponding SQL type.
  878. * <P>
  879. * This method throws an exception if there is an ambiguity, for example, if the
  880. * object is of a class implementing more than one of the interfaces named above.
  881. *
  882. * @param parameterName the name of the parameter
  883. * @param x the object containing the input parameter value
  884. * @exception SQLException if a database access error occurs or if the given
  885. * <code>Object</code> parameter is ambiguous
  886. * @see #getObject
  887. * @since 1.4
  888. */
  889. void setObject(String parameterName, Object x) throws SQLException;
  890. /**
  891. * Sets the designated parameter to the given <code>Reader</code>
  892. * object, which is the given number of characters long.
  893. * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
  894. * parameter, it may be more practical to send it via a
  895. * <code>java.io.Reader</code> object. The data will be read from the stream
  896. * as needed until end-of-file is reached. The JDBC driver will
  897. * do any necessary conversion from UNICODE to the database char format.
  898. *
  899. * <P><B>Note:</B> This stream object can either be a standard
  900. * Java stream object or your own subclass that implements the
  901. * standard interface.
  902. *
  903. * @param parameterName the name of the parameter
  904. * @param reader the <code>java.io.Reader</code> object that
  905. * contains the UNICODE data used as the designated parameter
  906. * @param length the number of characters in the stream
  907. * @exception SQLException if a database access error occurs
  908. * @since 1.4
  909. */
  910. void setCharacterStream(String parameterName,
  911. java.io.Reader reader,
  912. int length) throws SQLException;
  913. /**
  914. * Sets the designated parameter to the given <code>java.sql.Date</code> value,
  915. * using the given <code>Calendar</code> object. The driver uses
  916. * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
  917. * which the driver then sends to the database. With a
  918. * a <code>Calendar</code> object, the driver can calculate the date
  919. * taking into account a custom timezone. If no
  920. * <code>Calendar</code> object is specified, the driver uses the default
  921. * timezone, which is that of the virtual machine running the application.
  922. *
  923. * @param parameterName the name of the parameter
  924. * @param x the parameter value
  925. * @param cal the <code>Calendar</code> object the driver will use
  926. * to construct the date
  927. * @exception SQLException if a database access error occurs
  928. * @see #getDate
  929. * @since 1.4
  930. */
  931. void setDate(String parameterName, java.sql.Date x, Calendar cal)
  932. throws SQLException;
  933. /**
  934. * Sets the designated parameter to the given <code>java.sql.Time</code> value,
  935. * using the given <code>Calendar</code> object. The driver uses
  936. * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
  937. * which the driver then sends to the database. With a
  938. * a <code>Calendar</code> object, the driver can calculate the time
  939. * taking into account a custom timezone. If no
  940. * <code>Calendar</code> object is specified, the driver uses the default
  941. * timezone, which is that of the virtual machine running the application.
  942. *
  943. * @param parameterName the name of the parameter
  944. * @param x the parameter value
  945. * @param cal the <code>Calendar</code> object the driver will use
  946. * to construct the time
  947. * @exception SQLException if a database access error occurs
  948. * @see #getTime
  949. * @since 1.4
  950. */
  951. void setTime(String parameterName, java.sql.Time x, Calendar cal)
  952. throws SQLException;
  953. /**
  954. * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
  955. * using the given <code>Calendar</code> object. The driver uses
  956. * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
  957. * which the driver then sends to the database. With a
  958. * a <code>Calendar</code> object, the driver can calculate the timestamp
  959. * taking into account a custom timezone. If no
  960. * <code>Calendar</code> object is specified, the driver uses the default
  961. * timezone, which is that of the virtual machine running the application.
  962. *
  963. * @param parameterName the name of the parameter
  964. * @param x the parameter value
  965. * @param cal the <code>Calendar</code> object the driver will use
  966. * to construct the timestamp
  967. * @exception SQLException if a database access error occurs
  968. * @see #getTimestamp
  969. * @since 1.4
  970. */
  971. void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
  972. throws SQLException;
  973. /**
  974. * Sets the designated parameter to SQL <code>NULL</code>.
  975. * This version of the method <code>setNull</code> should
  976. * be used for user-defined types and REF type parameters. Examples
  977. * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
  978. * named array types.
  979. *
  980. * <P><B>Note:</B> To be portable, applications must give the
  981. * SQL type code and the fully-qualified SQL type name when specifying
  982. * a NULL user-defined or REF parameter. In the case of a user-defined type
  983. * the name is the type name of the parameter itself. For a REF
  984. * parameter, the name is the type name of the referenced type. If
  985. * a JDBC driver does not need the type code or type name information,
  986. * it may ignore it.
  987. *
  988. * Although it is intended for user-defined and Ref parameters,
  989. * this method may be used to set a null parameter of any JDBC type.
  990. * If the parameter does not have a user-defined or REF type, the given
  991. * typeName is ignored.
  992. *
  993. *
  994. * @param parameterName the name of the parameter
  995. * @param sqlType a value from <code>java.sql.Types</code>
  996. * @param typeName the fully-qualified name of an SQL user-defined type;
  997. * ignored if the parameter is not a user-defined type or
  998. * SQL <code>REF</code> value
  999. * @exception SQLException if a database access error occurs
  1000. * @since 1.4
  1001. */
  1002. void setNull (String parameterName, int sqlType, String typeName)
  1003. throws SQLException;
  1004. /**
  1005. * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
  1006. * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
  1007. * the Java programming language.
  1008. * <p>
  1009. * For the fixed-length type JDBC <code>CHAR</code>,
  1010. * the <code>String</code> object
  1011. * returned has exactly the same value the JDBC
  1012. * <code>CHAR</code> value had in the
  1013. * database, including any padding added by the database.
  1014. * @param parameterName the name of the parameter
  1015. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1016. * is <code>null</code>.
  1017. * @exception SQLException if a database access error occurs
  1018. * @see #setString
  1019. * @since 1.4
  1020. */
  1021. String getString(String parameterName) throws SQLException;
  1022. /**
  1023. * Retrieves the value of a JDBC <code>BIT</code> parameter as a
  1024. * <code>boolean</code> in the Java programming language.
  1025. * @param parameterName the name of the parameter
  1026. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1027. * is <code>false</code>.
  1028. * @exception SQLException if a database access error occurs
  1029. * @see #setBoolean
  1030. * @since 1.4
  1031. */
  1032. boolean getBoolean(String parameterName) throws SQLException;
  1033. /**
  1034. * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
  1035. * in the Java programming language.
  1036. * @param parameterName the name of the parameter
  1037. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1038. * is <code>0</code>.
  1039. * @exception SQLException if a database access error occurs
  1040. * @see #setByte
  1041. * @since 1.4
  1042. */
  1043. byte getByte(String parameterName) throws SQLException;
  1044. /**
  1045. * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
  1046. * in the Java programming language.
  1047. * @param parameterName the name of the parameter
  1048. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1049. * is <code>0</code>.
  1050. * @exception SQLException if a database access error occurs
  1051. * @see #setShort
  1052. * @since 1.4
  1053. */
  1054. short getShort(String parameterName) throws SQLException;
  1055. /**
  1056. * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
  1057. * in the Java programming language.
  1058. *
  1059. * @param parameterName the name of the parameter
  1060. * @return the parameter value. If the value is SQL <code>NULL</code>,
  1061. * the result is <code>0</code>.
  1062. * @exception SQLException if a database access error occurs
  1063. * @see #setInt
  1064. * @since 1.4
  1065. */
  1066. int getInt(String parameterName) throws SQLException;
  1067. /**
  1068. * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
  1069. * in the Java programming language.
  1070. *
  1071. * @param parameterName the name of the parameter
  1072. * @return the parameter value. If the value is SQL <code>NULL</code>,
  1073. * the result is <code>0</code>.
  1074. * @exception SQLException if a database access error occurs
  1075. * @see #setLong
  1076. * @since 1.4
  1077. */
  1078. long getLong(String parameterName) throws SQLException;
  1079. /**
  1080. * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
  1081. * in the Java programming language.
  1082. * @param parameterName the name of the parameter
  1083. * @return the parameter value. If the value is SQL <code>NULL</code>,
  1084. * the result is <code>0</code>.
  1085. * @exception SQLException if a database access error occurs
  1086. * @see #setFloat
  1087. * @since 1.4
  1088. */
  1089. float getFloat(String parameterName) throws SQLException;
  1090. /**
  1091. * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
  1092. * in the Java programming language.
  1093. * @param parameterName the name of the parameter
  1094. * @return the parameter value. If the value is SQL <code>NULL</code>,
  1095. * the result is <code>0</code>.
  1096. * @exception SQLException if a database access error occurs
  1097. * @see #setDouble
  1098. * @since 1.4
  1099. */
  1100. double getDouble(String parameterName) throws SQLException;
  1101. /**
  1102. * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
  1103. * parameter as an array of <code>byte</code> values in the Java
  1104. * programming language.
  1105. * @param parameterName the name of the parameter
  1106. * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
  1107. * <code>null</code>.
  1108. * @exception SQLException if a database access error occurs
  1109. * @see #setBytes
  1110. * @since 1.4
  1111. */
  1112. byte[] getBytes(String parameterName) throws SQLException;
  1113. /**
  1114. * Retrieves the value of a JDBC <code>DATE</code> parameter as a
  1115. * <code>java.sql.Date</code> object.
  1116. * @param parameterName the name of the parameter
  1117. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1118. * is <code>null</code>.
  1119. * @exception SQLException if a database access error occurs
  1120. * @see #setDate
  1121. * @since 1.4
  1122. */
  1123. java.sql.Date getDate(String parameterName) throws SQLException;
  1124. /**
  1125. * Retrieves the value of a JDBC <code>TIME</code> parameter as a
  1126. * <code>java.sql.Time</code> object.
  1127. * @param parameterName the name of the parameter
  1128. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1129. * is <code>null</code>.
  1130. * @exception SQLException if a database access error occurs
  1131. * @see #setTime
  1132. * @since 1.4
  1133. */
  1134. java.sql.Time getTime(String parameterName) throws SQLException;
  1135. /**
  1136. * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
  1137. * <code>java.sql.Timestamp</code> object.
  1138. * @param parameterName the name of the parameter
  1139. * @return the parameter value. If the value is SQL <code>NULL</code>, the result
  1140. * is <code>null</code>.
  1141. * @exception SQLException if a database access error occurs
  1142. * @see #setTimestamp
  1143. * @since 1.4
  1144. */
  1145. java.sql.Timestamp getTimestamp(String parameterName) throws SQLException;
  1146. /**
  1147. * Retrieves the value of a parameter as an <code>Object</code> in the Java
  1148. * programming language. If the value is an SQL <code>NULL</code>, the
  1149. * driver returns a Java <code>null</code>.
  1150. * <p>
  1151. * This method returns a Java object whose type corresponds to the JDBC
  1152. * type that was registered for this parameter using the method
  1153. * <code>registerOutParameter</code>. By registering the target JDBC
  1154. * type as <code>java.sql.Types.OTHER</code>, this method can be used
  1155. * to read database-specific abstract data types.
  1156. * @param parameterName the name of the parameter
  1157. * @return A <code>java.lang.Object</code> holding the OUT parameter value.
  1158. * @exception SQLException if a database access error occurs
  1159. * @see Types
  1160. * @see #setObject
  1161. * @since 1.4
  1162. */
  1163. Object getObject(String parameterName) throws SQLException;
  1164. /**
  1165. * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
  1166. * <code>java.math.BigDecimal</code> object with as many digits to the
  1167. * right of the decimal point as the value contains.
  1168. * @param parameterName the name of the parameter
  1169. * @return the parameter value in full precision. If the value is
  1170. * SQL <code>NULL</code>, the result is <code>null</code>.
  1171. * @exception SQLException if a database access error occurs
  1172. * @see #setBigDecimal
  1173. * @since 1.4
  1174. */
  1175. BigDecimal getBigDecimal(String parameterName) throws SQLException;
  1176. /**
  1177. * Returns an object representing the value of OUT parameter
  1178. * <code>i</code> and uses <code>map</code> for the custom
  1179. * mapping of the parameter value.
  1180. * <p>
  1181. * This method returns a Java object whose type corresponds to the
  1182. * JDBC type that was registered for this parameter using the method
  1183. * <code>registerOutParameter</code>. By registering the target
  1184. * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
  1185. * be used to read database-specific abstract data types.
  1186. * @param parameterName the name of the parameter
  1187. * @param map the mapping from SQL type names to Java classes
  1188. * @return a <code>java.lang.Object</code> holding the OUT parameter value
  1189. * @exception SQLException if a database access error occurs
  1190. * @see #setObject
  1191. * @since 1.4
  1192. */
  1193. Object getObject (String parameterName, java.util.Map map) throws SQLException;
  1194. /**
  1195. * Retrieves the value of a JDBC <code>REF(<structured-type>)</code>
  1196. * parameter as a {@link Ref} object in the Java programming language.
  1197. *
  1198. * @param parameterName the name of the parameter
  1199. * @return the parameter value as a <code>Ref</code> object in the
  1200. * Java programming language. If the value was SQL <code>NULL</code>,
  1201. * the value <code>null</code> is returned.
  1202. * @exception SQLException if a database access error occurs
  1203. * @since 1.4
  1204. */
  1205. Ref getRef (String parameterName) throws SQLException;
  1206. /**
  1207. * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
  1208. * {@link Blob} object in the Java programming language.
  1209. *
  1210. * @param parameterName the name of the parameter
  1211. * @return the parameter value as a <code>Blob</code> object in the
  1212. * Java programming language. If the value was SQL <code>NULL</code>,
  1213. * the value <code>null</code> is returned.
  1214. * @exception SQLException if a database access error occurs
  1215. * @since 1.4
  1216. */
  1217. Blob getBlob (String parameterName) throws SQLException;
  1218. /**
  1219. * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
  1220. * <code>Clob</code> object in the Java programming language.
  1221. * @param parameterName the name of the parameter
  1222. * @return the parameter value as a <code>Clob</code> object in the
  1223. * Java programming language. If the value was SQL <code>NULL</code>,
  1224. * the value <code>null</code> is returned.
  1225. * @exception SQLException if a database access error occurs
  1226. * @since 1.4
  1227. */
  1228. Clob getClob (String parameterName) throws SQLException;
  1229. /**
  1230. * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
  1231. * {@link Array} object in the Java programming language.
  1232. *
  1233. * @param parameterName the name of the parameter
  1234. * @return the parameter value as an <code>Array</code> object in
  1235. * Java programming language. If the value was SQL <code>NULL</code>,
  1236. * the value <code>null</code> is returned.
  1237. * @exception SQLException if a database access error occurs
  1238. * @since 1.4
  1239. */
  1240. Array getArray (String parameterName) throws SQLException;
  1241. /**
  1242. * Retrieves the value of a JDBC <code>DATE</code> parameter as a
  1243. * <code>java.sql.Date</code> object, using
  1244. * the given <code>Calendar</code> object
  1245. * to construct the date.
  1246. * With a <code>Calendar</code> object, the driver
  1247. * can calculate the date taking into account a custom timezone and locale.
  1248. * If no <code>Calendar</code> object is specified, the driver uses the
  1249. * default timezone and locale.
  1250. *
  1251. * @param parameterName the name of the parameter
  1252. * @param cal the <code>Calendar</code> object the driver will use
  1253. * to construct the date
  1254. * @return the parameter value. If the value is SQL <code>NULL</code>,
  1255. * the result is <code>null</code>.
  1256. * @exception SQLException if a database access error occurs
  1257. * @see #setDate
  1258. * @since 1.4
  1259. */
  1260. java.sql.Date getDate(String parameterName, Calendar cal)
  1261. throws SQLException;
  1262. /**
  1263. * Retrieves the value of a JDBC <code>TIME</code> parameter as a
  1264. * <code>java.sql.Time</code> object, using
  1265. * the given <code>Calendar</code> object
  1266. * to construct the time.
  1267. * With a <code>Calendar</code> object, the driver
  1268. * can calculate the time taking into account a custom timezone and locale.
  1269. * If no <code>Calendar</code> object is specified, the driver uses the
  1270. * default timezone and locale.
  1271. *
  1272. * @param parameterName the name of the parameter
  1273. * @param cal the <code>Calendar</code> object the driver will use
  1274. * to construct the time
  1275. * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
  1276. * <code>null</code>.
  1277. * @exception SQLException if a database access error occurs
  1278. * @see #setTime
  1279. * @since 1.4
  1280. */
  1281. java.sql.Time getTime(String parameterName, Calendar cal)
  1282. throws SQLException;
  1283. /**
  1284. * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
  1285. * <code>java.sql.Timestamp</code> object, using
  1286. * the given <code>Calendar</code> object to construct
  1287. * the <code>Timestamp</code> object.
  1288. * With a <code>Calendar</code> object, the driver
  1289. * can calculate the timestamp taking into account a custom timezone and locale.
  1290. * If no <code>Calendar</code> object is specified, the driver uses the
  1291. * default timezone and locale.
  1292. *
  1293. *
  1294. * @param parameterName the name of the parameter
  1295. * @param cal the <code>Calendar</code> object the driver will use
  1296. * to construct the timestamp
  1297. * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
  1298. * <code>null</code>.
  1299. * @exception SQLException if a database access error occurs
  1300. * @see #setTimestamp
  1301. * @since 1.4
  1302. */
  1303. java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
  1304. throws SQLException;
  1305. /**
  1306. * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
  1307. * <code>java.net.URL</code> object.
  1308. *
  1309. * @param parameterName the name of the parameter
  1310. * @return the parameter value as a <code>java.net.URL</code> object in the
  1311. * Java programming language. If the value was SQL <code>NULL</code>, the
  1312. * value <code>null</code> is returned.
  1313. * @exception SQLException if a database access error occurs,
  1314. * or if there is a problem with the URL
  1315. * @see #setURL
  1316. * @since 1.4
  1317. */
  1318. java.net.URL getURL(String parameterName) throws SQLException;
  1319. }