1 /*
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sql;
27
28 import java.sql.*;
29 import java.io.*;
30 import java.math.*;
31 import java.util.*;
32
33 /**
34 * The interface that adds support to the JDBC API for the
35 * JavaBeans™ component model.
36 * A rowset, which can be used as a JavaBeans component in
37 * a visual Bean development environment, can be created and
38 * configured at design time and executed at run time.
39 * <P>
40 * The <code>RowSet</code>
41 * interface provides a set of JavaBeans properties that allow a <code>RowSet</code>
42 * instance to be configured to connect to a JDBC data source and read
43 * some data from the data source. A group of setter methods (<code>setInt</code>,
44 * <code>setBytes</code>, <code>setString</code>, and so on)
45 * provide a way to pass input parameters to a rowset's command property.
46 * This command is the SQL query the rowset uses when it gets its data from
47 * a relational database, which is generally the case.
48 * <P>
49 * The <code>RowSet</code>
50 * interface supports JavaBeans events, allowing other components in an
51 * application to be notified when an event occurs on a rowset,
52 * such as a change in its value.
53 *
54 * <P>The <code>RowSet</code> interface is unique in that it is intended to be
55 * implemented using the rest of the JDBC API. In other words, a
56 * <code>RowSet</code> implementation is a layer of software that executes "on top"
57 * of a JDBC driver. Implementations of the <code>RowSet</code> interface can
58 * be provided by anyone, including JDBC driver vendors who want to
59 * provide a <code>RowSet</code> implementation as part of their JDBC products.
60 * <P>
61 * A <code>RowSet</code> object may make a connection with a data source and
62 * maintain that connection throughout its life cycle, in which case it is
63 * called a <i>connected</i> rowset. A rowset may also make a connection with
64 * a data source, get data from it, and then close the connection. Such a rowset
65 * is called a <i>disconnected</i> rowset. A disconnected rowset may make
66 * changes to its data while it is disconnected and then send the changes back
67 * to the original source of the data, but it must reestablish a connection to do so.
68 * <P>
69 * A disconnected rowset may have a reader (a <code>RowSetReader</code> object)
70 * and a writer (a <code>RowSetWriter</code> object) associated with it.
71 * The reader may be implemented in many different ways to populate a rowset
72 * with data, including getting data from a non-relational data source. The
73 * writer can also be implemented in many different ways to propagate changes
74 * made to the rowset's data back to the underlying data source.
75 * <P>
76 * Rowsets are easy to use. The <code>RowSet</code> interface extends the standard
77 * <code>java.sql.ResultSet</code> interface. The <code>RowSetMetaData</code>
78 * interface extends the <code>java.sql.ResultSetMetaData</code> interface.
79 * Thus, developers familiar
80 * with the JDBC API will have to learn a minimal number of new APIs to
81 * use rowsets. In addition, third-party software tools that work with
82 * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets.
83 *
84 * @since 1.4
85 */
86
87 public interface RowSet extends ResultSet {
88
89 //-----------------------------------------------------------------------
90 // Properties
91 //-----------------------------------------------------------------------
92
93 //-----------------------------------------------------------------------
94 // The following properties may be used to create a Connection.
95 //-----------------------------------------------------------------------
96
97 /**
98 * Retrieves the url property this <code>RowSet</code> object will use to
99 * create a connection if it uses the <code>DriverManager</code>
100 * instead of a <code>DataSource</code> object to establish the connection.
101 * The default value is <code>null</code>.
102 *
103 * @return a string url
104 * @exception SQLException if a database access error occurs
105 * @see #setUrl
106 */
107 String getUrl() throws SQLException;
108
109 /**
110 * Sets the URL this <code>RowSet</code> object will use when it uses the
111 * <code>DriverManager</code> to create a connection.
112 *
113 * Setting this property is optional. If a URL is used, a JDBC driver
114 * that accepts the URL must be loaded before the
115 * rowset is used to connect to a database. The rowset will use the URL
116 * internally to create a database connection when reading or writing
117 * data. Either a URL or a data source name is used to create a
118 * connection, whichever was set to non null value most recently.
119 *
120 * @param url a string value; may be <code>null</code>
121 * @exception SQLException if a database access error occurs
122 * @see #getUrl
123 */
124 void setUrl(String url) throws SQLException;
125
126 /**
127 * Retrieves the logical name that identifies the data source for this
128 * <code>RowSet</code> object.
129 *
130 * @return a data source name
131 * @see #setDataSourceName
132 * @see #setUrl
133 */
134 String getDataSourceName();
135
136 /**
137 * Sets the data source name property for this <code>RowSet</code> object to the
138 * given <code>String</code>.
139 * <P>
140 * The value of the data source name property can be used to do a lookup of
141 * a <code>DataSource</code> object that has been registered with a naming
142 * service. After being retrieved, the <code>DataSource</code> object can be
143 * used to create a connection to the data source that it represents.
144 *
145 * @param name the logical name of the data source for this <code>RowSet</code>
146 * object; may be <code>null</code>
147 * @exception SQLException if a database access error occurs
148 * @see #getDataSourceName
149 */
150 void setDataSourceName(String name) throws SQLException;
151
152 /**
153 * Retrieves the username used to create a database connection for this
154 * <code>RowSet</code> object.
155 * The username property is set at run time before calling the method
156 * <code>execute</code>. It is
157 * not usually part of the serialized state of a <code>RowSet</code> object.
158 *
159 * @return the username property
160 * @see #setUsername
161 */
162 String getUsername();
163
164 /**
165 * Sets the username property for this <code>RowSet</code> object to the
166 * given <code>String</code>.
167 *
168 * @param name a user name
169 * @exception SQLException if a database access error occurs
170 * @see #getUsername
171 */
172 void setUsername(String name) throws SQLException;
173
174 /**
175 * Retrieves the password used to create a database connection.
176 * The password property is set at run time before calling the method
177 * <code>execute</code>. It is not usually part of the serialized state
178 * of a <code>RowSet</code> object.
179 *
180 * @return the password for making a database connection
181 * @see #setPassword
182 */
183 String getPassword();
184
185 /**
186 * Sets the database password for this <code>RowSet</code> object to
187 * the given <code>String</code>.
188 *
189 * @param password the password string
190 * @exception SQLException if a database access error occurs
191 * @see #getPassword
192 */
193 void setPassword(String password) throws SQLException;
194
195 /**
196 * Retrieves the transaction isolation level set for this
197 * <code>RowSet</code> object.
198 *
199 * @return the transaction isolation level; one of
200 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
201 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
202 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
203 * <code>Connection.TRANSACTION_SERIALIZABLE</code>
204 * @see #setTransactionIsolation
205 */
206 int getTransactionIsolation();
207
208 /**
209 * Sets the transaction isolation level for this <code>RowSet</code> object.
210 *
211 * @param level the transaction isolation level; one of
212 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
213 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
214 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
215 * <code>Connection.TRANSACTION_SERIALIZABLE</code>
216 * @exception SQLException if a database access error occurs
217 * @see #getTransactionIsolation
218 */
219 void setTransactionIsolation(int level) throws SQLException;
220
221 /**
222 * Retrieves the <code>Map</code> object associated with this
223 * <code>RowSet</code> object, which specifies the custom mapping
224 * of SQL user-defined types, if any. The default is for the
225 * type map to be empty.
226 *
227 * @return a <code>java.util.Map</code> object containing the names of
228 * SQL user-defined types and the Java classes to which they are
229 * to be mapped
230 *
231 * @exception SQLException if a database access error occurs
232 * @see #setTypeMap
233 */
234 java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
235
236 /**
237 * Installs the given <code>java.util.Map</code> object as the default
238 * type map for this <code>RowSet</code> object. This type map will be
239 * used unless another type map is supplied as a method parameter.
240 *
241 * @param map a <code>java.util.Map</code> object containing the names of
242 * SQL user-defined types and the Java classes to which they are
243 * to be mapped
244 * @exception SQLException if a database access error occurs
245 * @see #getTypeMap
246 */
247 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
248
249 //-----------------------------------------------------------------------
250 // The following properties may be used to create a Statement.
251 //-----------------------------------------------------------------------
252
253 /**
254 * Retrieves this <code>RowSet</code> object's command property.
255 *
256 * The command property contains a command string, which must be an SQL
257 * query, that can be executed to fill the rowset with data.
258 * The default value is <code>null</code>.
259 *
260 * @return the command string; may be <code>null</code>
261 * @see #setCommand
262 */
263 String getCommand();
264
265 /**
266 * Sets this <code>RowSet</code> object's command property to the given
267 * SQL query.
268 *
269 * This property is optional
270 * when a rowset gets its data from a data source that does not support
271 * commands, such as a spreadsheet.
272 *
273 * @param cmd the SQL query that will be used to get the data for this
274 * <code>RowSet</code> object; may be <code>null</code>
275 * @exception SQLException if a database access error occurs
276 * @see #getCommand
277 */
278 void setCommand(String cmd) throws SQLException;
279
280 /**
281 * Retrieves whether this <code>RowSet</code> object is read-only.
282 * If updates are possible, the default is for a rowset to be
283 * updatable.
284 * <P>
285 * Attempts to update a read-only rowset will result in an
286 * <code>SQLException</code> being thrown.
287 *
288 * @return <code>true</code> if this <code>RowSet</code> object is
289 * read-only; <code>false</code> if it is updatable
290 * @see #setReadOnly
291 */
292 boolean isReadOnly();
293
294 /**
295 * Sets whether this <code>RowSet</code> object is read-only to the
296 * given <code>boolean</code>.
297 *
298 * @param value <code>true</code> if read-only; <code>false</code> if
299 * updatable
300 * @exception SQLException if a database access error occurs
301 * @see #isReadOnly
302 */
303 void setReadOnly(boolean value) throws SQLException;
304
305 /**
306 * Retrieves the maximum number of bytes that may be returned
307 * for certain column values.
308 * This limit applies only to <code>BINARY</code>,
309 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
310 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
311 * and <code>NVARCHAR</code> columns.
312 * If the limit is exceeded, the excess data is silently discarded.
313 *
314 * @return the current maximum column size limit; zero means that there
315 * is no limit
316 * @exception SQLException if a database access error occurs
317 * @see #setMaxFieldSize
318 */
319 int getMaxFieldSize() throws SQLException;
320
321 /**
322 * Sets the maximum number of bytes that can be returned for a column
323 * value to the given number of bytes.
324 * This limit applies only to <code>BINARY</code>,
325 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
326 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
327 * and <code>NVARCHAR</code> columns.
328 * If the limit is exceeded, the excess data is silently discarded.
329 * For maximum portability, use values greater than 256.
330 *
331 * @param max the new max column size limit in bytes; zero means unlimited
332 * @exception SQLException if a database access error occurs
333 * @see #getMaxFieldSize
334 */
335 void setMaxFieldSize(int max) throws SQLException;
336
337 /**
338 * Retrieves the maximum number of rows that this <code>RowSet</code>
339 * object can contain.
340 * If the limit is exceeded, the excess rows are silently dropped.
341 *
342 * @return the current maximum number of rows that this <code>RowSet</code>
343 * object can contain; zero means unlimited
344 * @exception SQLException if a database access error occurs
345 * @see #setMaxRows
346 */
347 int getMaxRows() throws SQLException;
348
349 /**
350 * Sets the maximum number of rows that this <code>RowSet</code>
351 * object can contain to the specified number.
352 * If the limit is exceeded, the excess rows are silently dropped.
353 *
354 * @param max the new maximum number of rows; zero means unlimited
355 * @exception SQLException if a database access error occurs
356 * @see #getMaxRows
357 */
358 void setMaxRows(int max) throws SQLException;
359
360 /**
361 * Retrieves whether escape processing is enabled for this
362 * <code>RowSet</code> object.
363 * If escape scanning is enabled, which is the default, the driver will do
364 * escape substitution before sending an SQL statement to the database.
365 *
366 * @return <code>true</code> if escape processing is enabled;
367 * <code>false</code> if it is disabled
368 * @exception SQLException if a database access error occurs
369 * @see #setEscapeProcessing
370 */
371 boolean getEscapeProcessing() throws SQLException;
372
373 /**
374 * Sets escape processing for this <code>RowSet</code> object on or
375 * off. If escape scanning is on (the default), the driver will do
376 * escape substitution before sending an SQL statement to the database.
377 *
378 * @param enable <code>true</code> to enable escape processing;
379 * <code>false</code> to disable it
380 * @exception SQLException if a database access error occurs
381 * @see #getEscapeProcessing
382 */
383 void setEscapeProcessing(boolean enable) throws SQLException;
384
385 /**
386 * Retrieves the maximum number of seconds the driver will wait for
387 * a statement to execute.
388 * If this limit is exceeded, an <code>SQLException</code> is thrown.
389 *
390 * @return the current query timeout limit in seconds; zero means
391 * unlimited
392 * @exception SQLException if a database access error occurs
393 * @see #setQueryTimeout
394 */
395 int getQueryTimeout() throws SQLException;
396
397 /**
398 * Sets the maximum time the driver will wait for
399 * a statement to execute to the given number of seconds.
400 * If this limit is exceeded, an <code>SQLException</code> is thrown.
401 *
402 * @param seconds the new query timeout limit in seconds; zero means
403 * that there is no limit
404 * @exception SQLException if a database access error occurs
405 * @see #getQueryTimeout
406 */
407 void setQueryTimeout(int seconds) throws SQLException;
408
409 /**
410 * Sets the type of this <code>RowSet</code> object to the given type.
411 * This method is used to change the type of a rowset, which is by
412 * default read-only and non-scrollable.
413 *
414 * @param type one of the <code>ResultSet</code> constants specifying a type:
415 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
416 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
417 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
418 * @exception SQLException if a database access error occurs
419 * @see java.sql.ResultSet#getType
420 */
421 void setType(int type) throws SQLException;
422
423 /**
424 * Sets the concurrency of this <code>RowSet</code> object to the given
425 * concurrency level. This method is used to change the concurrency level
426 * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code>
427 *
428 * @param concurrency one of the <code>ResultSet</code> constants specifying a
429 * concurrency level: <code>ResultSet.CONCUR_READ_ONLY</code> or
430 * <code>ResultSet.CONCUR_UPDATABLE</code>
431 * @exception SQLException if a database access error occurs
432 * @see ResultSet#getConcurrency
433 */
434 void setConcurrency(int concurrency) throws SQLException;
435
436 //-----------------------------------------------------------------------
437 // Parameters
438 //-----------------------------------------------------------------------
439
440 /**
441 * The <code>RowSet</code> setter methods are used to set any input parameters
442 * needed by the <code>RowSet</code> object's command.
443 * Parameters are set at run time, as opposed to design time.
444 */
445
446 /**
447 * Sets the designated parameter in this <code>RowSet</code> object's SQL
448 * command to SQL <code>NULL</code>.
449 *
450 * <P><B>Note:</B> You must specify the parameter's SQL type.
451 *
452 * @param parameterIndex the first parameter is 1, the second is 2, ...
453 * @param sqlType a SQL type code defined by <code>java.sql.Types</code>
454 * @exception SQLException if a database access error occurs
455 */
456 void setNull(int parameterIndex, int sqlType) throws SQLException;
457
458 /**
459 * Sets the designated parameter to SQL <code>NULL</code>.
460 *
461 * <P><B>Note:</B> You must specify the parameter's SQL type.
462 *
463 * @param parameterName the name of the parameter
464 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
465 * @exception SQLException if a database access error occurs or
466 * this method is called on a closed <code>CallableStatement</code>
467 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
468 * this method
469 * @since 1.4
470 */
471 void setNull(String parameterName, int sqlType) throws SQLException;
472
473 /**
474 * Sets the designated parameter in this <code>RowSet</code> object's SQL
475 * command to SQL <code>NULL</code>. This version of the method <code>setNull</code>
476 * should be used for SQL user-defined types (UDTs) and <code>REF</code> type
477 * parameters. Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>,
478 * <code>JAVA_OBJECT</code>, and named array types.
479 *
480 * <P><B>Note:</B> To be portable, applications must give the
481 * SQL type code and the fully qualified SQL type name when specifying
482 * a NULL UDT or <code>REF</code> parameter. In the case of a UDT,
483 * the name is the type name of the parameter itself. For a <code>REF</code>
484 * parameter, the name is the type name of the referenced type. If
485 * a JDBC driver does not need the type code or type name information,
486 * it may ignore it.
487 *
488 * Although it is intended for UDT and <code>REF</code> parameters,
489 * this method may be used to set a null parameter of any JDBC type.
490 * If the parameter does not have a user-defined or <code>REF</code> type,
491 * the typeName parameter is ignored.
492 *
493 *
494 * @param paramIndex the first parameter is 1, the second is 2, ...
495 * @param sqlType a value from <code>java.sql.Types</code>
496 * @param typeName the fully qualified name of an SQL UDT or the type
497 * name of the SQL structured type being referenced by a <code>REF</code>
498 * type; ignored if the parameter is not a UDT or <code>REF</code> type
499 * @exception SQLException if a database access error occurs
500 */
501 void setNull (int paramIndex, int sqlType, String typeName)
502 throws SQLException;
503
504 /**
505 * Sets the designated parameter to SQL <code>NULL</code>.
506 * This version of the method <code>setNull</code> should
507 * be used for user-defined types and REF type parameters. Examples
508 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
509 * named array types.
510 *
511 * <P><B>Note:</B> To be portable, applications must give the
512 * SQL type code and the fully-qualified SQL type name when specifying
513 * a NULL user-defined or REF parameter. In the case of a user-defined type
514 * the name is the type name of the parameter itself. For a REF
515 * parameter, the name is the type name of the referenced type. If
516 * a JDBC driver does not need the type code or type name information,
517 * it may ignore it.
518 *
519 * Although it is intended for user-defined and Ref parameters,
520 * this method may be used to set a null parameter of any JDBC type.
521 * If the parameter does not have a user-defined or REF type, the given
522 * typeName is ignored.
523 *
524 *
525 * @param parameterName the name of the parameter
526 * @param sqlType a value from <code>java.sql.Types</code>
527 * @param typeName the fully-qualified name of an SQL user-defined type;
528 * ignored if the parameter is not a user-defined type or
529 * SQL <code>REF</code> value
530 * @exception SQLException if a database access error occurs or
531 * this method is called on a closed <code>CallableStatement</code>
532 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
533 * this method
534 * @since 1.4
535 */
536 void setNull (String parameterName, int sqlType, String typeName)
537 throws SQLException;
538
539 /**
540 * Sets the designated parameter in this <code>RowSet</code> object's command
541 * to the given Java <code>boolean</code> value. The driver converts this to
542 * an SQL <code>BIT</code> value before sending it to the database.
543 *
544 * @param parameterIndex the first parameter is 1, the second is 2, ...
545 * @param x the parameter value
546 * @exception SQLException if a database access error occurs
547 */
548 void setBoolean(int parameterIndex, boolean x) throws SQLException;
549
550 /**
551 * Sets the designated parameter to the given Java <code>boolean</code> value.
552 * The driver converts this
553 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
554 *
555 * @param parameterName the name of the parameter
556 * @param x the parameter value
557 * @exception SQLException if a database access error occurs or
558 * this method is called on a closed <code>CallableStatement</code>
559 * @see #getBoolean
560 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
561 * this method
562 * @since 1.4
563 */
564 void setBoolean(String parameterName, boolean x) throws SQLException;
565
566 /**
567 * Sets the designated parameter in this <code>RowSet</code> object's command
568 * to the given Java <code>byte</code> value. The driver converts this to
569 * an SQL <code>TINYINT</code> value before sending it to the database.
570 *
571 * @param parameterIndex the first parameter is 1, the second is 2, ...
572 * @param x the parameter value
573 * @exception SQLException if a database access error occurs
574 */
575 void setByte(int parameterIndex, byte x) throws SQLException;
576
577 /**
578 * Sets the designated parameter to the given Java <code>byte</code> value.
579 * The driver converts this
580 * to an SQL <code>TINYINT</code> value when it sends it to the database.
581 *
582 * @param parameterName the name of the parameter
583 * @param x the parameter value
584 * @exception SQLException if a database access error occurs or
585 * this method is called on a closed <code>CallableStatement</code>
586 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
587 * this method
588 * @see #getByte
589 * @since 1.4
590 */
591 void setByte(String parameterName, byte x) throws SQLException;
592
593 /**
594 * Sets the designated parameter in this <code>RowSet</code> object's command
595 * to the given Java <code>short</code> value. The driver converts this to
596 * an SQL <code>SMALLINT</code> value before sending it to the database.
597 *
598 * @param parameterIndex the first parameter is 1, the second is 2, ...
599 * @param x the parameter value
600 * @exception SQLException if a database access error occurs
601 */
602 void setShort(int parameterIndex, short x) throws SQLException;
603
604 /**
605 * Sets the designated parameter to the given Java <code>short</code> value.
606 * The driver converts this
607 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
608 *
609 * @param parameterName the name of the parameter
610 * @param x the parameter value
611 * @exception SQLException if a database access error occurs or
612 * this method is called on a closed <code>CallableStatement</code>
613 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
614 * this method
615 * @see #getShort
616 * @since 1.4
617 */
618 void setShort(String parameterName, short x) throws SQLException;
619
620 /**
621 * Sets the designated parameter in this <code>RowSet</code> object's command
622 * to the given Java <code>int</code> value. The driver converts this to
623 * an SQL <code>INTEGER</code> value before sending it to the database.
624 *
625 * @param parameterIndex the first parameter is 1, the second is 2, ...
626 * @param x the parameter value
627 * @exception SQLException if a database access error occurs
628 */
629 void setInt(int parameterIndex, int x) throws SQLException;
630
631 /**
632 * Sets the designated parameter to the given Java <code>int</code> value.
633 * The driver converts this
634 * to an SQL <code>INTEGER</code> value when it sends it to the database.
635 *
636 * @param parameterName the name of the parameter
637 * @param x the parameter value
638 * @exception SQLException if a database access error occurs or
639 * this method is called on a closed <code>CallableStatement</code>
640 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
641 * this method
642 * @see #getInt
643 * @since 1.4
644 */
645 void setInt(String parameterName, int x) throws SQLException;
646
647 /**
648 * Sets the designated parameter in this <code>RowSet</code> object's command
649 * to the given Java <code>long</code> value. The driver converts this to
650 * an SQL <code>BIGINT</code> value before sending it to the database.
651 *
652 * @param parameterIndex the first parameter is 1, the second is 2, ...
653 * @param x the parameter value
654 * @exception SQLException if a database access error occurs
655 */
656 void setLong(int parameterIndex, long x) throws SQLException;
657
658 /**
659 * Sets the designated parameter to the given Java <code>long</code> value.
660 * The driver converts this
661 * to an SQL <code>BIGINT</code> value when it sends it to the database.
662 *
663 * @param parameterName the name of the parameter
664 * @param x the parameter value
665 * @exception SQLException if a database access error occurs or
666 * this method is called on a closed <code>CallableStatement</code>
667 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
668 * this method
669 * @see #getLong
670 * @since 1.4
671 */
672 void setLong(String parameterName, long x) throws SQLException;
673
674 /**
675 * Sets the designated parameter in this <code>RowSet</code> object's command
676 * to the given Java <code>float</code> value. The driver converts this to
677 * an SQL <code>REAL</code> value before sending it to the database.
678 *
679 * @param parameterIndex the first parameter is 1, the second is 2, ...
680 * @param x the parameter value
681 * @exception SQLException if a database access error occurs
682 */
683 void setFloat(int parameterIndex, float x) throws SQLException;
684
685 /**
686 * Sets the designated parameter to the given Java <code>float</code> value.
687 * The driver converts this
688 * to an SQL <code>FLOAT</code> value when it sends it to the database.
689 *
690 * @param parameterName the name of the parameter
691 * @param x the parameter value
692 * @exception SQLException if a database access error occurs or
693 * this method is called on a closed <code>CallableStatement</code>
694 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
695 * this method
696 * @see #getFloat
697 * @since 1.4
698 */
699 void setFloat(String parameterName, float x) throws SQLException;
700
701 /**
702 * Sets the designated parameter in this <code>RowSet</code> object's command
703 * to the given Java <code>double</code> value. The driver converts this to
704 * an SQL <code>DOUBLE</code> value before sending it to the database.
705 *
706 * @param parameterIndex the first parameter is 1, the second is 2, ...
707 * @param x the parameter value
708 * @exception SQLException if a database access error occurs
709 */
710 void setDouble(int parameterIndex, double x) throws SQLException;
711
712 /**
713 * Sets the designated parameter to the given Java <code>double</code> value.
714 * The driver converts this
715 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
716 *
717 * @param parameterName the name of the parameter
718 * @param x the parameter value
719 * @exception SQLException if a database access error occurs or
720 * this method is called on a closed <code>CallableStatement</code>
721 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
722 * this method
723 * @see #getDouble
724 * @since 1.4
725 */
726 void setDouble(String parameterName, double x) throws SQLException;
727
728 /**
729 * Sets the designated parameter in this <code>RowSet</code> object's command
730 * to the given <code>java.math.BigDeciaml</code> value.
731 * The driver converts this to
732 * an SQL <code>NUMERIC</code> value before sending it to the database.
733 *
734 * @param parameterIndex the first parameter is 1, the second is 2, ...
735 * @param x the parameter value
736 * @exception SQLException if a database access error occurs
737 */
738 void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;
739
740 /**
741 * Sets the designated parameter to the given
742 * <code>java.math.BigDecimal</code> value.
743 * The driver converts this to an SQL <code>NUMERIC</code> value when
744 * it sends it to the database.
745 *
746 * @param parameterName the name of the parameter
747 * @param x the parameter value
748 * @exception SQLException if a database access error occurs or
749 * this method is called on a closed <code>CallableStatement</code>
750 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
751 * this method
752 * @see #getBigDecimal
753 * @since 1.4
754 */
755 void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
756
757 /**
758 * Sets the designated parameter in this <code>RowSet</code> object's command
759 * to the given Java <code>String</code> value. Before sending it to the
760 * database, the driver converts this to an SQL <code>VARCHAR</code> or
761 * <code>LONGVARCHAR</code> value, depending on the argument's size relative
762 * to the driver's limits on <code>VARCHAR</code> values.
763 *
764 * @param parameterIndex the first parameter is 1, the second is 2, ...
765 * @param x the parameter value
766 * @exception SQLException if a database access error occurs
767 */
768 void setString(int parameterIndex, String x) throws SQLException;
769
770 /**
771 * Sets the designated parameter to the given Java <code>String</code> value.
772 * The driver converts this
773 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
774 * (depending on the argument's
775 * size relative to the driver's limits on <code>VARCHAR</code> values)
776 * when it sends it to the database.
777 *
778 * @param parameterName the name of the parameter
779 * @param x the parameter value
780 * @exception SQLException if a database access error occurs or
781 * this method is called on a closed <code>CallableStatement</code>
782 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
783 * this method
784 * @see #getString
785 * @since 1.4
786 */
787 void setString(String parameterName, String x) throws SQLException;
788
789 /**
790 * Sets the designated parameter in this <code>RowSet</code> object's command
791 * to the given Java array of <code>byte</code> values. Before sending it to the
792 * database, the driver converts this to an SQL <code>VARBINARY</code> or
793 * <code>LONGVARBINARY</code> value, depending on the argument's size relative
794 * to the driver's limits on <code>VARBINARY</code> values.
795 *
796 * @param parameterIndex the first parameter is 1, the second is 2, ...
797 * @param x the parameter value
798 * @exception SQLException if a database access error occurs
799 */
800 void setBytes(int parameterIndex, byte x[]) throws SQLException;
801
802 /**
803 * Sets the designated parameter to the given Java array of bytes.
804 * The driver converts this to an SQL <code>VARBINARY</code> or
805 * <code>LONGVARBINARY</code> (depending on the argument's size relative
806 * to the driver's limits on <code>VARBINARY</code> values) when it sends
807 * it to the database.
808 *
809 * @param parameterName the name of the parameter
810 * @param x the parameter value
811 * @exception SQLException if a database access error occurs or
812 * this method is called on a closed <code>CallableStatement</code>
813 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
814 * this method
815 * @see #getBytes
816 * @since 1.4
817 */
818 void setBytes(String parameterName, byte x[]) throws SQLException;
819
820 /**
821 * Sets the designated parameter in this <code>RowSet</code> object's command
822 * to the given <code>java.sql.Date</code> value. The driver converts this to
823 * an SQL <code>DATE</code> value before sending it to the database, using the
824 * default <code>java.util.Calendar</code> to calculate the date.
825 *
826 * @param parameterIndex the first parameter is 1, the second is 2, ...
827 * @param x the parameter value
828 * @exception SQLException if a database access error occurs
829 */
830 void setDate(int parameterIndex, java.sql.Date x) throws SQLException;
831
832 /**
833 * Sets the designated parameter in this <code>RowSet</code> object's command
834 * to the given <code>java.sql.Time</code> value. The driver converts this to
835 * an SQL <code>TIME</code> value before sending it to the database, using the
836 * default <code>java.util.Calendar</code> to calculate it.
837 *
838 * @param parameterIndex the first parameter is 1, the second is 2, ...
839 * @param x the parameter value
840 * @exception SQLException if a database access error occurs
841 */
842 void setTime(int parameterIndex, java.sql.Time x) throws SQLException;
843
844 /**
845 * Sets the designated parameter in this <code>RowSet</code> object's command
846 * to the given <code>java.sql.Timestamp</code> value. The driver converts this to
847 * an SQL <code>TIMESTAMP</code> value before sending it to the database, using the
848 * default <code>java.util.Calendar</code> to calculate it.
849 *
850 * @param parameterIndex the first parameter is 1, the second is 2, ...
851 * @param x the parameter value
852 * @exception SQLException if a database access error occurs
853 */
854 void setTimestamp(int parameterIndex, java.sql.Timestamp x)
855 throws SQLException;
856
857 /**
858 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
859 * The driver
860 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
861 * database.
862 *
863 * @param parameterName the name of the parameter
864 * @param x the parameter value
865 * @exception SQLException if a database access error occurs or
866 * this method is called on a closed <code>CallableStatement</code>
867 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
868 * this method
869 * @see #getTimestamp
870 * @since 1.4
871 */
872 void setTimestamp(String parameterName, java.sql.Timestamp x)
873 throws SQLException;
874
875 /**
876 * Sets the designated parameter in this <code>RowSet</code> object's command
877 * to the given <code>java.io.InputStream</code> value.
878 * It may be more practical to send a very large ASCII value via a
879 * <code>java.io.InputStream</code> rather than as a <code>LONGVARCHAR</code>
880 * parameter. The driver will read the data from the stream
881 * as needed until it reaches end-of-file.
882 *
883 * <P><B>Note:</B> This stream object can either be a standard
884 * Java stream object or your own subclass that implements the
885 * standard interface.
886 *
887 * @param parameterIndex the first parameter is 1, the second is 2, ...
888 * @param x the Java input stream that contains the ASCII parameter value
889 * @param length the number of bytes in the stream
890 * @exception SQLException if a database access error occurs
891 */
892 void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)
893 throws SQLException;
894
895 /**
896 * Sets the designated parameter to the given input stream, which will have
897 * the specified number of bytes.
898 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
899 * parameter, it may be more practical to send it via a
900 * <code>java.io.InputStream</code>. Data will be read from the stream
901 * as needed until end-of-file is reached. The JDBC driver will
902 * do any necessary conversion from ASCII to the database char format.
903 *
904 * <P><B>Note:</B> This stream object can either be a standard
905 * Java stream object or your own subclass that implements the
906 * standard interface.
907 *
908 * @param parameterName the name of the parameter
909 * @param x the Java input stream that contains the ASCII parameter value
910 * @param length the number of bytes in the stream
911 * @exception SQLException if a database access error occurs or
912 * this method is called on a closed <code>CallableStatement</code>
913 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
914 * this method
915 * @since 1.4
916 */
917 void setAsciiStream(String parameterName, java.io.InputStream x, int length)
918 throws SQLException;
919
920 /**
921 * Sets the designated parameter in this <code>RowSet</code> object's command
922 * to the given <code>java.io.InputStream</code> value.
923 * It may be more practical to send a very large binary value via a
924 * <code>java.io.InputStream</code> rather than as a <code>LONGVARBINARY</code>
925 * parameter. The driver will read the data from the stream
926 * as needed until it reaches end-of-file.
927 *
928 * <P><B>Note:</B> This stream object can either be a standard
929 * Java stream object or your own subclass that implements the
930 * standard interface.
931 *
932 * @param parameterIndex the first parameter is 1, the second is 2, ...
933 * @param x the java input stream which contains the binary parameter value
934 * @param length the number of bytes in the stream
935 * @exception SQLException if a database access error occurs
936 */
937 void setBinaryStream(int parameterIndex, java.io.InputStream x,
938 int length) throws SQLException;
939
940 /**
941 * Sets the designated parameter to the given input stream, which will have
942 * the specified number of bytes.
943 * When a very large binary value is input to a <code>LONGVARBINARY</code>
944 * parameter, it may be more practical to send it via a
945 * <code>java.io.InputStream</code> object. The data will be read from the stream
946 * as needed until end-of-file is reached.
947 *
948 * <P><B>Note:</B> This stream object can either be a standard
949 * Java stream object or your own subclass that implements the
950 * standard interface.
951 *
952 * @param parameterName the name of the parameter
953 * @param x the java input stream which contains the binary parameter value
954 * @param length the number of bytes in the stream
955 * @exception SQLException if a database access error occurs or
956 * this method is called on a closed <code>CallableStatement</code>
957 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
958 * this method
959 * @since 1.4
960 */
961 void setBinaryStream(String parameterName, java.io.InputStream x,
962 int length) throws SQLException;
963
964 /**
965 * Sets the designated parameter in this <code>RowSet</code> object's command
966 * to the given <code>java.io.Reader</code> value.
967 * It may be more practical to send a very large UNICODE value via a
968 * <code>java.io.Reader</code> rather than as a <code>LONGVARCHAR</code>
969 * parameter. The driver will read the data from the stream
970 * as needed until it reaches end-of-file.
971 *
972 * <P><B>Note:</B> This stream object can either be a standard
973 * Java stream object or your own subclass that implements the
974 * standard interface.
975 *
976 * @param parameterIndex the first parameter is 1, the second is 2, ...
977 * @param reader the <code>Reader</code> object that contains the UNICODE data
978 * to be set
979 * @param length the number of characters in the stream
980 * @exception SQLException if a database access error occurs
981 */
982 void setCharacterStream(int parameterIndex,
983 Reader reader,
984 int length) throws SQLException;
985
986 /**
987 * Sets the designated parameter to the given <code>Reader</code>
988 * object, which is the given number of characters long.
989 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
990 * parameter, it may be more practical to send it via a
991 * <code>java.io.Reader</code> object. The data will be read from the stream
992 * as needed until end-of-file is reached. The JDBC driver will
993 * do any necessary conversion from UNICODE to the database char format.
994 *
995 * <P><B>Note:</B> This stream object can either be a standard
996 * Java stream object or your own subclass that implements the
997 * standard interface.
998 *
999 * @param parameterName the name of the parameter
1000 * @param reader the <code>java.io.Reader</code> object that
1001 * contains the UNICODE data used as the designated parameter
1002 * @param length the number of characters in the stream
1003 * @exception SQLException if a database access error occurs or
1004 * this method is called on a closed <code>CallableStatement</code>
1005 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1006 * this method
1007 * @since 1.4
1008 */
1009 void setCharacterStream(String parameterName,
1010 java.io.Reader reader,
1011 int length) throws SQLException;
1012
1013 /**
1014 * Sets the designated parameter in this <code>RowSet</code> object's command
1015 * to the given input stream.
1016 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1017 * parameter, it may be more practical to send it via a
1018 * <code>java.io.InputStream</code>. Data will be read from the stream
1019 * as needed until end-of-file is reached. The JDBC driver will
1020 * do any necessary conversion from ASCII to the database char format.
1021 *
1022 * <P><B>Note:</B> This stream object can either be a standard
1023 * Java stream object or your own subclass that implements the
1024 * standard interface.
1025 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1026 * it might be more efficient to use a version of
1027 * <code>setAsciiStream</code> which takes a length parameter.
1028 *
1029 * @param parameterIndex the first parameter is 1, the second is 2, ...
1030 * @param x the Java input stream that contains the ASCII parameter value
1031 * @exception SQLException if a database access error occurs or
1032 * this method is called on a closed <code>PreparedStatement</code>
1033 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1034 * @since 1.6
1035 */
1036 void setAsciiStream(int parameterIndex, java.io.InputStream x)
1037 throws SQLException;
1038
1039 /**
1040 * Sets the designated parameter to the given input stream.
1041 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1042 * parameter, it may be more practical to send it via a
1043 * <code>java.io.InputStream</code>. Data will be read from the stream
1044 * as needed until end-of-file is reached. The JDBC driver will
1045 * do any necessary conversion from ASCII to the database char format.
1046 *
1047 * <P><B>Note:</B> This stream object can either be a standard
1048 * Java stream object or your own subclass that implements the
1049 * standard interface.
1050 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1051 * it might be more efficient to use a version of
1052 * <code>setAsciiStream</code> which takes a length parameter.
1053 *
1054 * @param parameterName the name of the parameter
1055 * @param x the Java input stream that contains the ASCII parameter value
1056 * @exception SQLException if a database access error occurs or
1057 * this method is called on a closed <code>CallableStatement</code>
1058 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1059 * @since 1.6
1060 */
1061 void setAsciiStream(String parameterName, java.io.InputStream x)
1062 throws SQLException;
1063
1064 /**
1065 * Sets the designated parameter in this <code>RowSet</code> object's command
1066 * to the given input stream.
1067 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1068 * parameter, it may be more practical to send it via a
1069 * <code>java.io.InputStream</code> object. The data will be read from the
1070 * stream as needed until end-of-file is reached.
1071 *
1072 * <P><B>Note:</B> This stream object can either be a standard
1073 * Java stream object or your own subclass that implements the
1074 * standard interface.
1075 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1076 * it might be more efficient to use a version of
1077 * <code>setBinaryStream</code> which takes a length parameter.
1078 *
1079 * @param parameterIndex the first parameter is 1, the second is 2, ...
1080 * @param x the java input stream which contains the binary parameter value
1081 * @exception SQLException 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 input stream.
1091 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1092 * parameter, it may be more practical to send it via a
1093 * <code>java.io.InputStream</code> object. The data will be read from the
1094 * stream as needed until end-of-file is reached.
1095 *
1096 * <P><B>Note:</B> This stream object can either be a standard
1097 * Java stream object or your own subclass that implements the
1098 * standard interface.
1099 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1100 * it might be more efficient to use a version of
1101 * <code>setBinaryStream</code> which takes a length parameter.
1102 *
1103 * @param parameterName the name of the parameter
1104 * @param x the java input stream which contains the binary parameter value
1105 * @exception SQLException if a database access error occurs or
1106 * this method is called on a closed <code>CallableStatement</code>
1107 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1108 * @since 1.6
1109 */
1110 void setBinaryStream(String parameterName, java.io.InputStream x)
1111 throws SQLException;
1112
1113 /**
1114 * Sets the designated parameter in this <code>RowSet</code> object's command
1115 * to the given <code>Reader</code>
1116 * object.
1117 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1118 * parameter, it may be more practical to send it via a
1119 * <code>java.io.Reader</code> object. The data will be read from the stream
1120 * as needed until end-of-file is reached. The JDBC driver will
1121 * do any necessary conversion from UNICODE to the database char format.
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>setCharacterStream</code> which takes a length parameter.
1129 *
1130 * @param parameterIndex the first parameter is 1, the second is 2, ...
1131 * @param reader the <code>java.io.Reader</code> object that contains the
1132 * Unicode data
1133 * @exception SQLException if a database access error occurs or
1134 * this method is called on a closed <code>PreparedStatement</code>
1135 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1136 * @since 1.6
1137 */
1138 void setCharacterStream(int parameterIndex,
1139 java.io.Reader reader) throws SQLException;
1140
1141 /**
1142 * Sets the designated parameter to the given <code>Reader</code>
1143 * object.
1144 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1145 * parameter, it may be more practical to send it via a
1146 * <code>java.io.Reader</code> object. The data will be read from the stream
1147 * as needed until end-of-file is reached. The JDBC driver will
1148 * do any necessary conversion from UNICODE to the database char format.
1149 *
1150 * <P><B>Note:</B> This stream object can either be a standard
1151 * Java stream object or your own subclass that implements the
1152 * standard interface.
1153 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1154 * it might be more efficient to use a version of
1155 * <code>setCharacterStream</code> which takes a length parameter.
1156 *
1157 * @param parameterName the name of the parameter
1158 * @param reader the <code>java.io.Reader</code> object that contains the
1159 * Unicode data
1160 * @exception SQLException if a database access error occurs or
1161 * this method is called on a closed <code>CallableStatement</code>
1162 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1163 * @since 1.6
1164 */
1165 void setCharacterStream(String parameterName,
1166 java.io.Reader reader) throws SQLException;
1167
1168 /**
1169 * Sets the designated parameter in this <code>RowSet</code> object's command
1170 * to a <code>Reader</code> object. The
1171 * <code>Reader</code> reads the data till end-of-file is reached. The
1172 * driver does the necessary conversion from Java character format to
1173 * the national character set in the database.
1174
1175 * <P><B>Note:</B> This stream object can either be a standard
1176 * Java stream object or your own subclass that implements the
1177 * standard interface.
1178 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1179 * it might be more efficient to use a version of
1180 * <code>setNCharacterStream</code> which takes a length parameter.
1181 *
1182 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1183 * @param value the parameter value
1184 * @throws SQLException if the driver does not support national
1185 * character sets; if the driver can detect that a data conversion
1186 * error could occur ; if a database access error occurs; or
1187 * this method is called on a closed <code>PreparedStatement</code>
1188 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1189 * @since 1.6
1190 */
1191 void setNCharacterStream(int parameterIndex, Reader value) throws SQLException;
1192
1193
1194
1195 /**
1196 * Sets the designated parameter in this <code>RowSet</code> object's command
1197 * with the given Java <code>Object</code>. For integral values, the
1198 * <code>java.lang</code> equivalent objects should be used (for example,
1199 * an instance of the class <code>Integer</code> for an <code>int</code>).
1200 *
1201 * If the second argument is an <code>InputStream</code> then the stream must contain
1202 * the number of bytes specified by scaleOrLength. If the second argument is a
1203 * <code>Reader</code> then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a
1204 * <code>SQLException</code> when the prepared statement is executed.
1205 *
1206 * <p>The given Java object will be converted to the targetSqlType
1207 * before being sent to the database.
1208 * <P>
1209 * If the object is of a class implementing <code>SQLData</code>,
1210 * the rowset should call the method <code>SQLData.writeSQL</code>
1211 * to write the object to an <code>SQLOutput</code> data stream.
1212 * If, on the other hand, the object is of a class implementing
1213 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1214 * <code>Struct</code>, <code>java.net.URL</code>,
1215 * or <code>Array</code>, the driver should pass it to the database as a
1216 * value of the corresponding SQL type.
1217 *
1218 *
1219 * <p>Note that this method may be used to pass datatabase-specific
1220 * abstract data types.
1221 *
1222 * @param parameterIndex the first parameter is 1, the second is 2, ...
1223 * @param x the object containing the input parameter value
1224 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1225 * to be sent to the database. The scale argument may further qualify this
1226 * type.
1227 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
1228 * or <code>java.sql.Types.NUMERIC types</code>,
1229 * this is the number of digits after the decimal point. For
1230 * Java Object types <code>InputStream</code> and <code>Reader</code>,
1231 * this is the length
1232 * of the data in the stream or reader. For all other types,
1233 * this value will be ignored.
1234 * @exception SQLException if a database access error occurs
1235 * @see java.sql.Types
1236 */
1237 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength)
1238 throws SQLException;
1239
1240 /**
1241 * Sets the value of the designated parameter with the given object. The second
1242 * argument must be an object type; for integral values, the
1243 * <code>java.lang</code> equivalent objects should be used.
1244 *
1245 * <p>The given Java object will be converted to the given targetSqlType
1246 * before being sent to the database.
1247 *
1248 * If the object has a custom mapping (is of a class implementing the
1249 * interface <code>SQLData</code>),
1250 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1251 * to the SQL data stream.
1252 * If, on the other hand, the object is of a class implementing
1253 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1254 * <code>Struct</code>, <code>java.net.URL</code>,
1255 * or <code>Array</code>, the driver should pass it to the database as a
1256 * value of the corresponding SQL type.
1257 * <P>
1258 * Note that this method may be used to pass datatabase-
1259 * specific abstract data types.
1260 *
1261 * @param parameterName the name of the parameter
1262 * @param x the object containing the input parameter value
1263 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1264 * sent to the database. The scale argument may further qualify this type.
1265 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1266 * this is the number of digits after the decimal point. For all other
1267 * types, this value will be ignored.
1268 * @exception SQLException if a database access error occurs or
1269 * this method is called on a closed <code>CallableStatement</code>
1270 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1271 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1272 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1273 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1274 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1275 * or <code>STRUCT</code> data type and the JDBC driver does not support
1276 * this data type
1277 * @see Types
1278 * @see #getObject
1279 * @since 1.4
1280 */
1281 void setObject(String parameterName, Object x, int targetSqlType, int scale)
1282 throws SQLException;
1283
1284 /**
1285 * Sets the designated parameter in this <code>RowSet</code> object's command
1286 * with a Java <code>Object</code>. For integral values, the
1287 * <code>java.lang</code> equivalent objects should be used.
1288 * This method is like <code>setObject</code> above, but the scale used is the scale
1289 * of the second parameter. Scalar values have a scale of zero. Literal
1290 * values have the scale present in the literal.
1291 * <P>
1292 * Even though it is supported, it is not recommended that this method
1293 * be called with floating point input values.
1294 *
1295 * @param parameterIndex the first parameter is 1, the second is 2, ...
1296 * @param x the object containing the input parameter value
1297 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1298 * to be sent to the database
1299 * @exception SQLException if a database access error occurs
1300 */
1301 void setObject(int parameterIndex, Object x,
1302 int targetSqlType) throws SQLException;
1303
1304 /**
1305 * Sets the value of the designated parameter with the given object.
1306 * This method is like the method <code>setObject</code>
1307 * above, except that it assumes a scale of zero.
1308 *
1309 * @param parameterName the name of the parameter
1310 * @param x the object containing the input parameter value
1311 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1312 * sent to the database
1313 * @exception SQLException if a database access error occurs or
1314 * this method is called on a closed <code>CallableStatement</code>
1315 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1316 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1317 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1318 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1319 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1320 * or <code>STRUCT</code> data type and the JDBC driver does not support
1321 * this data type
1322 * @see #getObject
1323 * @since 1.4
1324 */
1325 void setObject(String parameterName, Object x, int targetSqlType)
1326 throws SQLException;
1327
1328 /**
1329 * Sets the value of the designated parameter with the given object.
1330 * The second parameter must be of type <code>Object</code>; therefore, the
1331 * <code>java.lang</code> equivalent objects should be used for built-in types.
1332 *
1333 * <p>The JDBC specification specifies a standard mapping from
1334 * Java <code>Object</code> types to SQL types. The given argument
1335 * will be converted to the corresponding SQL type before being
1336 * sent to the database.
1337 *
1338 * <p>Note that this method may be used to pass datatabase-
1339 * specific abstract data types, by using a driver-specific Java
1340 * type.
1341 *
1342 * If the object is of a class implementing the interface <code>SQLData</code>,
1343 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1344 * to write it to the SQL data stream.
1345 * If, on the other hand, the object is of a class implementing
1346 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1347 * <code>Struct</code>, <code>java.net.URL</code>,
1348 * or <code>Array</code>, the driver should pass it to the database as a
1349 * value of the corresponding SQL type.
1350 * <P>
1351 * This method throws an exception if there is an ambiguity, for example, if the
1352 * object is of a class implementing more than one of the interfaces named above.
1353 *
1354 * @param parameterName the name of the parameter
1355 * @param x the object containing the input parameter value
1356 * @exception SQLException if a database access error occurs,
1357 * this method is called on a closed <code>CallableStatement</code> or if the given
1358 * <code>Object</code> parameter is ambiguous
1359 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1360 * this method
1361 * @see #getObject
1362 * @since 1.4
1363 */
1364 void setObject(String parameterName, Object x) throws SQLException;
1365
1366 /**
1367 * Sets the designated parameter in this <code>RowSet</code> object's command
1368 * with a Java <code>Object</code>. For integral values, the
1369 * <code>java.lang</code> equivalent objects should be used.
1370 *
1371 * <p>The JDBC specification provides a standard mapping from
1372 * Java Object types to SQL types. The driver will convert the
1373 * given Java object to its standard SQL mapping before sending it
1374 * to the database.
1375 *
1376 * <p>Note that this method may be used to pass datatabase-specific
1377 * abstract data types by using a driver-specific Java type.
1378 *
1379 * If the object is of a class implementing <code>SQLData</code>,
1380 * the rowset should call the method <code>SQLData.writeSQL</code>
1381 * to write the object to an <code>SQLOutput</code> data stream.
1382 * If, on the other hand, the object is of a class implementing
1383 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1384 * <code>Struct</code>, <code>java.net.URL</code>,
1385 * or <code>Array</code>, the driver should pass it to the database as a
1386 * value of the corresponding SQL type.
1387 *
1388 * <P>
1389 * An exception is thrown if there is an ambiguity, for example, if the
1390 * object is of a class implementing more than one of these interfaces.
1391 *
1392 * @param parameterIndex The first parameter is 1, the second is 2, ...
1393 * @param x The object containing the input parameter value
1394 * @exception SQLException if a database access error occurs
1395 */
1396 void setObject(int parameterIndex, Object x) throws SQLException;
1397
1398
1399 /**
1400 * Sets the designated parameter in this <code>RowSet</code> object's command
1401 * with the given <code>Ref</code> value. The driver will convert this
1402 * to the appropriate <code>REF(<structured-type>)</code> value.
1403 *
1404 * @param i the first parameter is 1, the second is 2, ...
1405 * @param x an object representing data of an SQL <code>REF</code> type
1406 * @exception SQLException if a database access error occurs
1407 */
1408 void setRef (int i, Ref x) throws SQLException;
1409
1410 /**
1411 * Sets the designated parameter in this <code>RowSet</code> object's command
1412 * with the given <code>Blob</code> value. The driver will convert this
1413 * to the <code>BLOB</code> value that the <code>Blob</code> object
1414 * represents before sending it to the database.
1415 *
1416 * @param i the first parameter is 1, the second is 2, ...
1417 * @param x an object representing a BLOB
1418 * @exception SQLException if a database access error occurs
1419 */
1420 void setBlob (int i, Blob x) throws SQLException;
1421
1422 /**
1423 * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
1424 * of characters specified by length otherwise a <code>SQLException</code> will be
1425 * generated when the <code>PreparedStatement</code> is executed.
1426 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1427 * method because it informs the driver that the parameter value should be
1428 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1429 * the driver may have to do extra work to determine whether the parameter
1430 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1431 * @param parameterIndex index of the first parameter is 1,
1432 * the second is 2, ...
1433 * @param inputStream An object that contains the data to set the parameter
1434 * value to.
1435 * @param length the number of bytes in the parameter data.
1436 * @throws SQLException if a database access error occurs,
1437 * this method is called on a closed <code>PreparedStatement</code>,
1438 * if parameterIndex does not correspond
1439 * to a parameter marker in the SQL statement, if the length specified
1440 * is less than zero or if the number of bytes in the inputstream does not match
1441 * the specified length.
1442 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1443 *
1444 * @since 1.6
1445 */
1446 void setBlob(int parameterIndex, InputStream inputStream, long length)
1447 throws SQLException;
1448
1449 /**
1450 * Sets the designated parameter to a <code>InputStream</code> object.
1451 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1452 * method because it informs the driver that the parameter value should be
1453 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1454 * the driver may have to do extra work to determine whether the parameter
1455 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1456 *
1457 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1458 * it might be more efficient to use a version of
1459 * <code>setBlob</code> which takes a length parameter.
1460 *
1461 * @param parameterIndex index of the first parameter is 1,
1462 * the second is 2, ...
1463 * @param inputStream An object that contains the data to set the parameter
1464 * value to.
1465 * @throws SQLException if a database access error occurs,
1466 * this method is called on a closed <code>PreparedStatement</code> or
1467 * if parameterIndex does not correspond
1468 * to a parameter marker in the SQL statement,
1469 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1470 *
1471 * @since 1.6
1472 */
1473 void setBlob(int parameterIndex, InputStream inputStream)
1474 throws SQLException;
1475
1476 /**
1477 * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1478 * of characters specified by length, otherwise a <code>SQLException</code> will be
1479 * generated when the <code>CallableStatement</code> is executed.
1480 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1481 * method because it informs the driver that the parameter value should be
1482 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1483 * the driver may have to do extra work to determine whether the parameter
1484 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1485 *
1486 * @param parameterName the name of the parameter to be set
1487 * the second is 2, ...
1488 *
1489 * @param inputStream An object that contains the data to set the parameter
1490 * value to.
1491 * @param length the number of bytes in the parameter data.
1492 * @throws SQLException if parameterIndex does not correspond
1493 * to a parameter marker in the SQL statement, or if the length specified
1494 * is less than zero; if the number of bytes in the inputstream does not match
1495 * the specified length; if a database access error occurs or
1496 * this method is called on a closed <code>CallableStatement</code>
1497 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1498 * this method
1499 *
1500 * @since 1.6
1501 */
1502 void setBlob(String parameterName, InputStream inputStream, long length)
1503 throws SQLException;
1504
1505 /**
1506 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
1507 * The driver converts this to an SQL <code>BLOB</code> value when it
1508 * sends it to the database.
1509 *
1510 * @param parameterName the name of the parameter
1511 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
1512 * @exception SQLException if a database access error occurs or
1513 * this method is called on a closed <code>CallableStatement</code>
1514 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1515 * this method
1516 * @since 1.6
1517 */
1518 void setBlob (String parameterName, Blob x) throws SQLException;
1519
1520 /**
1521 * Sets the designated parameter to a <code>InputStream</code> object.
1522 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1523 * method because it informs the driver that the parameter value should be
1524 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1525 * the driver may have to do extra work to determine whether the parameter
1526 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1527 *
1528 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1529 * it might be more efficient to use a version of
1530 * <code>setBlob</code> which takes a length parameter.
1531 *
1532 * @param parameterName the name of the parameter
1533 * @param inputStream An object that contains the data to set the parameter
1534 * value to.
1535 * @throws SQLException if a database access error occurs or
1536 * this method is called on a closed <code>CallableStatement</code>
1537 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1538 *
1539 * @since 1.6
1540 */
1541 void setBlob(String parameterName, InputStream inputStream)
1542 throws SQLException;
1543
1544 /**
1545 * Sets the designated parameter in this <code>RowSet</code> object's command
1546 * with the given <code>Clob</code> value. The driver will convert this
1547 * to the <code>CLOB</code> value that the <code>Clob</code> object
1548 * represents before sending it to the database.
1549 *
1550 * @param i the first parameter is 1, the second is 2, ...
1551 * @param x an object representing a CLOB
1552 * @exception SQLException if a database access error occurs
1553 */
1554 void setClob (int i, Clob x) throws SQLException;
1555
1556 /**
1557 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
1558 * of characters specified by length otherwise a <code>SQLException</code> will be
1559 * generated when the <code>PreparedStatement</code> is executed.
1560 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1561 * because it informs the driver that the parameter value should be sent to
1562 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1563 * driver may have to do extra work to determine whether the parameter
1564 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1565 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1566 * @param reader An object that contains the data to set the parameter value to.
1567 * @param length the number of characters in the parameter data.
1568 * @throws SQLException if a database access error occurs, this method is called on
1569 * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter
1570 * marker in the SQL statement, or if the length specified is less than zero.
1571 *
1572 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1573 * @since 1.6
1574 */
1575 void setClob(int parameterIndex, Reader reader, long length)
1576 throws SQLException;
1577
1578 /**
1579 * Sets the designated parameter to a <code>Reader</code> object.
1580 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1581 * because it informs the driver that the parameter value should be sent to
1582 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1583 * driver may have to do extra work to determine whether the parameter
1584 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1585 *
1586 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1587 * it might be more efficient to use a version of
1588 * <code>setClob</code> which takes a length parameter.
1589 *
1590 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1591 * @param reader An object that contains the data to set the parameter value to.
1592 * @throws SQLException if a database access error occurs, this method is called on
1593 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1594 * marker in the SQL statement
1595 *
1596 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1597 * @since 1.6
1598 */
1599 void setClob(int parameterIndex, Reader reader)
1600 throws SQLException;
1601
1602 /**
1603 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1604 * of characters specified by length otherwise a <code>SQLException</code> will be
1605 * generated when the <code>CallableStatement</code> is executed.
1606 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1607 * because it informs the driver that the parameter value should be sent to
1608 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1609 * driver may have to do extra work to determine whether the parameter
1610 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1611 * @param parameterName the name of the parameter to be set
1612 * @param reader An object that contains the data to set the parameter value to.
1613 * @param length the number of characters in the parameter data.
1614 * @throws SQLException if parameterIndex does not correspond to a parameter
1615 * marker in the SQL statement; if the length specified is less than zero;
1616 * a database access error occurs or
1617 * this method is called on a closed <code>CallableStatement</code>
1618 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1619 * this method
1620 *
1621 * @since 1.6
1622 */
1623 void setClob(String parameterName, Reader reader, long length)
1624 throws SQLException;
1625
1626 /**
1627 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
1628 * The driver converts this to an SQL <code>CLOB</code> value when it
1629 * sends it to the database.
1630 *
1631 * @param parameterName the name of the parameter
1632 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
1633 * @exception SQLException if a database access error occurs or
1634 * this method is called on a closed <code>CallableStatement</code>
1635 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1636 * this method
1637 * @since 1.6
1638 */
1639 void setClob (String parameterName, Clob x) throws SQLException;
1640
1641 /**
1642 * Sets the designated parameter to a <code>Reader</code> object.
1643 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1644 * because it informs the driver that the parameter value should be sent to
1645 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1646 * driver may have to do extra work to determine whether the parameter
1647 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1648 *
1649 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1650 * it might be more efficient to use a version of
1651 * <code>setClob</code> which takes a length parameter.
1652 *
1653 * @param parameterName the name of the parameter
1654 * @param reader An object that contains the data to set the parameter value to.
1655 * @throws SQLException if a database access error occurs or this method is called on
1656 * a closed <code>CallableStatement</code>
1657 *
1658 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1659 * @since 1.6
1660 */
1661 void setClob(String parameterName, Reader reader)
1662 throws SQLException;
1663
1664 /**
1665 * Sets the designated parameter in this <code>RowSet</code> object's command
1666 * with the given <code>Array</code> value. The driver will convert this
1667 * to the <code>ARRAY</code> value that the <code>Array</code> object
1668 * represents before sending it to the database.
1669 *
1670 * @param i the first parameter is 1, the second is 2, ...
1671 * @param x an object representing an SQL array
1672 * @exception SQLException if a database access error occurs
1673 */
1674 void setArray (int i, Array x) throws SQLException;
1675
1676 /**
1677 * Sets the designated parameter in this <code>RowSet</code> object's command
1678 * with the given <code>java.sql.Date</code> value. The driver will convert this
1679 * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code>
1680 * object to calculate the date.
1681 *
1682 * @param parameterIndex the first parameter is 1, the second is 2, ...
1683 * @param x the parameter value
1684 * @param cal the <code>java.util.Calendar</code> object to use for calculating the date
1685 * @exception SQLException if a database access error occurs
1686 */
1687 void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
1688 throws SQLException;
1689
1690 /**
1691 * Sets the designated parameter to the given <code>java.sql.Date</code> value
1692 * using the default time zone of the virtual machine that is running
1693 * the application.
1694 * The driver converts this
1695 * to an SQL <code>DATE</code> value when it sends it to the database.
1696 *
1697 * @param parameterName the name of the parameter
1698 * @param x the parameter value
1699 * @exception SQLException if a database access error occurs or
1700 * this method is called on a closed <code>CallableStatement</code>
1701 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1702 * this method
1703 * @see #getDate
1704 * @since 1.4
1705 */
1706 void setDate(String parameterName, java.sql.Date x)
1707 throws SQLException;
1708
1709 /**
1710 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1711 * using the given <code>Calendar</code> object. The driver uses
1712 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1713 * which the driver then sends to the database. With a
1714 * a <code>Calendar</code> object, the driver can calculate the date
1715 * taking into account a custom timezone. If no
1716 * <code>Calendar</code> object is specified, the driver uses the default
1717 * timezone, which is that of the virtual machine running the application.
1718 *
1719 * @param parameterName the name of the parameter
1720 * @param x the parameter value
1721 * @param cal the <code>Calendar</code> object the driver will use
1722 * to construct the date
1723 * @exception SQLException if a database access error occurs or
1724 * this method is called on a closed <code>CallableStatement</code>
1725 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1726 * this method
1727 * @see #getDate
1728 * @since 1.4
1729 */
1730 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1731 throws SQLException;
1732
1733 /**
1734 * Sets the designated parameter in this <code>RowSet</code> object's command
1735 * with the given <code>java.sql.Time</code> value. The driver will convert this
1736 * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code>
1737 * object to calculate it, before sending it to the database.
1738 *
1739 * @param parameterIndex the first parameter is 1, the second is 2, ...
1740 * @param x the parameter value
1741 * @param cal the <code>java.util.Calendar</code> object to use for calculating the time
1742 * @exception SQLException if a database access error occurs
1743 */
1744 void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
1745 throws SQLException;
1746
1747 /**
1748 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
1749 * The driver converts this
1750 * to an SQL <code>TIME</code> value when it sends it to the database.
1751 *
1752 * @param parameterName the name of the parameter
1753 * @param x the parameter value
1754 * @exception SQLException if a database access error occurs or
1755 * this method is called on a closed <code>CallableStatement</code>
1756 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1757 * this method
1758 * @see #getTime
1759 * @since 1.4
1760 */
1761 void setTime(String parameterName, java.sql.Time x)
1762 throws SQLException;
1763
1764 /**
1765 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1766 * using the given <code>Calendar</code> object. The driver uses
1767 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1768 * which the driver then sends to the database. With a
1769 * a <code>Calendar</code> object, the driver can calculate the time
1770 * taking into account a custom timezone. If no
1771 * <code>Calendar</code> object is specified, the driver uses the default
1772 * timezone, which is that of the virtual machine running the application.
1773 *
1774 * @param parameterName the name of the parameter
1775 * @param x the parameter value
1776 * @param cal the <code>Calendar</code> object the driver will use
1777 * to construct the time
1778 * @exception SQLException if a database access error occurs or
1779 * this method is called on a closed <code>CallableStatement</code>
1780 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1781 * this method
1782 * @see #getTime
1783 * @since 1.4
1784 */
1785 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1786 throws SQLException;
1787
1788 /**
1789 * Sets the designated parameter in this <code>RowSet</code> object's command
1790 * with the given <code>java.sql.Timestamp</code> value. The driver will
1791 * convert this to an SQL <code>TIMESTAMP</code> value, using the given
1792 * <code>java.util.Calendar</code> object to calculate it, before sending it to the
1793 * database.
1794 *
1795 * @param parameterIndex the first parameter is 1, the second is 2, ...
1796 * @param x the parameter value
1797 * @param cal the <code>java.util.Calendar</code> object to use for calculating the
1798 * timestamp
1799 * @exception SQLException if a database access error occurs
1800 */
1801 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)
1802 throws SQLException;
1803
1804 /**
1805 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1806 * using the given <code>Calendar</code> object. The driver uses
1807 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1808 * which the driver then sends to the database. With a
1809 * a <code>Calendar</code> object, the driver can calculate the timestamp
1810 * taking into account a custom timezone. If no
1811 * <code>Calendar</code> object is specified, the driver uses the default
1812 * timezone, which is that of the virtual machine running the application.
1813 *
1814 * @param parameterName the name of the parameter
1815 * @param x the parameter value
1816 * @param cal the <code>Calendar</code> object the driver will use
1817 * to construct the timestamp
1818 * @exception SQLException if a database access error occurs or
1819 * this method is called on a closed <code>CallableStatement</code>
1820 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1821 * this method
1822 * @see #getTimestamp
1823 * @since 1.4
1824 */
1825 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1826 throws SQLException;
1827
1828 /**
1829 * Clears the parameters set for this <code>RowSet</code> object's command.
1830 * <P>In general, parameter values remain in force for repeated use of a
1831 * <code>RowSet</code> object. Setting a parameter value automatically clears its
1832 * previous value. However, in some cases it is useful to immediately
1833 * release the resources used by the current parameter values, which can
1834 * be done by calling the method <code>clearParameters</code>.
1835 *
1836 * @exception SQLException if a database access error occurs
1837 */
1838 void clearParameters() throws SQLException;
1839
1840 //---------------------------------------------------------------------
1841 // Reading and writing data
1842 //---------------------------------------------------------------------
1843
1844 /**
1845 * Fills this <code>RowSet</code> object with data.
1846 * <P>
1847 * The <code>execute</code> method may use the following properties
1848 * to create a connection for reading data: url, data source name,
1849 * user name, password, transaction isolation, and type map.
1850 *
1851 * The <code>execute</code> method may use the following properties
1852 * to create a statement to execute a command:
1853 * command, read only, maximum field size,
1854 * maximum rows, escape processing, and query timeout.
1855 * <P>
1856 * If the required properties have not been set, an exception is
1857 * thrown. If this method is successful, the current contents of the rowset are
1858 * discarded and the rowset's metadata is also (re)set. If there are
1859 * outstanding updates, they are ignored.
1860 * <P>
1861 * If this <code>RowSet</code> object does not maintain a continuous connection
1862 * with its source of data, it may use a reader (a <code>RowSetReader</code>
1863 * object) to fill itself with data. In this case, a reader will have been
1864 * registered with this <code>RowSet</code> object, and the method
1865 * <code>execute</code> will call on the reader's <code>readData</code>
1866 * method as part of its implementation.
1867 *
1868 * @exception SQLException if a database access error occurs or any of the
1869 * properties necessary for making a connection and creating
1870 * a statement have not been set
1871 */
1872 void execute() throws SQLException;
1873
1874 //--------------------------------------------------------------------
1875 // Events
1876 //--------------------------------------------------------------------
1877
1878 /**
1879 * Registers the given listener so that it will be notified of events
1880 * that occur on this <code>RowSet</code> object.
1881 *
1882 * @param listener a component that has implemented the <code>RowSetListener</code>
1883 * interface and wants to be notified when events occur on this
1884 * <code>RowSet</code> object
1885 * @see #removeRowSetListener
1886 */
1887 void addRowSetListener(RowSetListener listener);
1888
1889 /**
1890 * Removes the specified listener from the list of components that will be
1891 * notified when an event occurs on this <code>RowSet</code> object.
1892 *
1893 * @param listener a component that has been registered as a listener for this
1894 * <code>RowSet</code> object
1895 * @see #addRowSetListener
1896 */
1897 void removeRowSetListener(RowSetListener listener);
1898
1899 /**
1900 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1901 * SQL <code>XML</code> value when it sends it to the database.
1902 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1903 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
1904 * @throws SQLException if a database access error occurs, this method
1905 * is called on a closed result set,
1906 * the <code>java.xml.transform.Result</code>,
1907 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1908 * for the <code>SQLXML</code> object or
1909 * if there is an error processing the XML value. The <code>getCause</code> method
1910 * of the exception may provide a more detailed exception, for example, if the
1911 * stream does not contain valid XML.
1912 * @since 1.6
1913 */
1914 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException;
1915
1916 /**
1917 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1918 * <code>SQL XML</code> value when it sends it to the database.
1919 * @param parameterName the name of the parameter
1920 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1921 * @throws SQLException if a database access error occurs, this method
1922 * is called on a closed result set,
1923 * the <code>java.xml.transform.Result</code>,
1924 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1925 * for the <code>SQLXML</code> object or
1926 * if there is an error processing the XML value. The <code>getCause</code> method
1927 * of the exception may provide a more detailed exception, for example, if the
1928 * stream does not contain valid XML.
1929 * @since 1.6
1930 */
1931 void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException;
1932
1933 /**
1934 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1935 * driver converts this to a SQL <code>ROWID</code> value when it sends it
1936 * to the database
1937 *
1938 * @param parameterIndex the first parameter is 1, the second is 2, ...
1939 * @param x the parameter value
1940 * @throws SQLException if a database access error occurs
1941 *
1942 * @since 1.6
1943 */
1944 void setRowId(int parameterIndex, RowId x) throws SQLException;
1945
1946 /**
1947 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1948 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1949 * database.
1950 *
1951 * @param parameterName the name of the parameter
1952 * @param x the parameter value
1953 * @throws SQLException if a database access error occurs
1954 * @since 1.6
1955 */
1956 void setRowId(String parameterName, RowId x) throws SQLException;
1957
1958 /**
1959 * Sets the designated parameter to the given <code>String</code> object.
1960 * The driver converts this to a SQL <code>NCHAR</code> or
1961 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
1962 * (depending on the argument's
1963 * size relative to the driver's limits on <code>NVARCHAR</code> values)
1964 * when it sends it to the database.
1965 *
1966 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1967 * @param value the parameter value
1968 * @throws SQLException if the driver does not support national
1969 * character sets; if the driver can detect that a data conversion
1970 * error could occur ; or if a database access error occurs
1971 * @since 1.6
1972 */
1973 void setNString(int parameterIndex, String value) throws SQLException;
1974
1975 /**
1976 * Sets the designated parameter to the given <code>String</code> object.
1977 * The driver converts this to a SQL <code>NCHAR</code> or
1978 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1979 * @param parameterName the name of the column to be set
1980 * @param value the parameter value
1981 * @throws SQLException if the driver does not support national
1982 * character sets; if the driver can detect that a data conversion
1983 * error could occur; or if a database access error occurs
1984 * @since 1.6
1985 */
1986 public void setNString(String parameterName, String value)
1987 throws SQLException;
1988
1989 /**
1990 * Sets the designated parameter to a <code>Reader</code> object. The
1991 * <code>Reader</code> reads the data till end-of-file is reached. The
1992 * driver does the necessary conversion from Java character format to
1993 * the national character set in the database.
1994 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1995 * @param value the parameter value
1996 * @param length the number of characters in the parameter data.
1997 * @throws SQLException if the driver does not support national
1998 * character sets; if the driver can detect that a data conversion
1999 * error could occur ; or if a database access error occurs
2000 * @since 1.6
2001 */
2002 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException;
2003
2004 /**
2005 * Sets the designated parameter to a <code>Reader</code> object. The
2006 * <code>Reader</code> reads the data till end-of-file is reached. The
2007 * driver does the necessary conversion from Java character format to
2008 * the national character set in the database.
2009 * @param parameterName the name of the column to be set
2010 * @param value the parameter value
2011 * @param length the number of characters in the parameter data.
2012 * @throws SQLException if the driver does not support national
2013 * character sets; if the driver can detect that a data conversion
2014 * error could occur; or if a database access error occurs
2015 * @since 1.6
2016 */
2017 public void setNCharacterStream(String parameterName, Reader value, long length)
2018 throws SQLException;
2019
2020 /**
2021 * Sets the designated parameter to a <code>Reader</code> object. The
2022 * <code>Reader</code> reads the data till end-of-file is reached. The
2023 * driver does the necessary conversion from Java character format to
2024 * the national character set in the database.
2025
2026 * <P><B>Note:</B> This stream object can either be a standard
2027 * Java stream object or your own subclass that implements the
2028 * standard interface.
2029 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2030 * it might be more efficient to use a version of
2031 * <code>setNCharacterStream</code> which takes a length parameter.
2032 *
2033 * @param parameterName the name of the parameter
2034 * @param value the parameter value
2035 * @throws SQLException if the driver does not support national
2036 * character sets; if the driver can detect that a data conversion
2037 * error could occur ; if a database access error occurs; or
2038 * this method is called on a closed <code>CallableStatement</code>
2039 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2040 * @since 1.6
2041 */
2042 void setNCharacterStream(String parameterName, Reader value) throws SQLException;
2043
2044 /**
2045 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
2046 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
2047 * object maps to a SQL <code>NCLOB</code>.
2048 * @param parameterName the name of the column to be set
2049 * @param value the parameter value
2050 * @throws SQLException if the driver does not support national
2051 * character sets; if the driver can detect that a data conversion
2052 * error could occur; or if a database access error occurs
2053 * @since 1.6
2054 */
2055 void setNClob(String parameterName, NClob value) throws SQLException;
2056
2057 /**
2058 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
2059 * of characters specified by length otherwise a <code>SQLException</code> will be
2060 * generated when the <code>CallableStatement</code> is executed.
2061 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2062 * because it informs the driver that the parameter value should be sent to
2063 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2064 * driver may have to do extra work to determine whether the parameter
2065 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2066 *
2067 * @param parameterName the name of the parameter to be set
2068 * @param reader An object that contains the data to set the parameter value to.
2069 * @param length the number of characters in the parameter data.
2070 * @throws SQLException if parameterIndex does not correspond to a parameter
2071 * marker in the SQL statement; if the length specified is less than zero;
2072 * if the driver does not support national
2073 * character sets; if the driver can detect that a data conversion
2074 * error could occur; if a database access error occurs or
2075 * this method is called on a closed <code>CallableStatement</code>
2076 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2077 * this method
2078 * @since 1.6
2079 */
2080 void setNClob(String parameterName, Reader reader, long length)
2081 throws SQLException;
2082
2083 /**
2084 * Sets the designated parameter to a <code>Reader</code> object.
2085 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2086 * because it informs the driver that the parameter value should be sent to
2087 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2088 * driver may have to do extra work to determine whether the parameter
2089 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2090 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2091 * it might be more efficient to use a version of
2092 * <code>setNClob</code> which takes a length parameter.
2093 *
2094 * @param parameterName the name of the parameter
2095 * @param reader An object that contains the data to set the parameter value to.
2096 * @throws SQLException if the driver does not support national character sets;
2097 * if the driver can detect that a data conversion
2098 * error could occur; if a database access error occurs or
2099 * this method is called on a closed <code>CallableStatement</code>
2100 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2101 *
2102 * @since 1.6
2103 */
2104 void setNClob(String parameterName, Reader reader)
2105 throws SQLException;
2106
2107 /**
2108 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
2109 * of characters specified by length otherwise a <code>SQLException</code> will be
2110 * generated when the <code>PreparedStatement</code> is executed.
2111 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2112 * because it informs the driver that the parameter value should be sent to
2113 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2114 * driver may have to do extra work to determine whether the parameter
2115 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2116 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2117 * @param reader An object that contains the data to set the parameter value to.
2118 * @param length the number of characters in the parameter data.
2119 * @throws SQLException if parameterIndex does not correspond to a parameter
2120 * marker in the SQL statement; if the length specified is less than zero;
2121 * if the driver does not support national character sets;
2122 * if the driver can detect that a data conversion
2123 * error could occur; if a database access error occurs or
2124 * this method is called on a closed <code>PreparedStatement</code>
2125 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2126 *
2127 * @since 1.6
2128 */
2129 void setNClob(int parameterIndex, Reader reader, long length)
2130 throws SQLException;
2131
2132 /**
2133 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
2134 * SQL <code>NCLOB</code> value when it sends it to the database.
2135 * @param parameterIndex of the first parameter is 1, the second is 2, ...
2136 * @param value the parameter value
2137 * @throws SQLException if the driver does not support national
2138 * character sets; if the driver can detect that a data conversion
2139 * error could occur ; or if a database access error occurs
2140 * @since 1.6
2141 */
2142 void setNClob(int parameterIndex, NClob value) throws SQLException;
2143
2144 /**
2145 * Sets the designated parameter to a <code>Reader</code> object.
2146 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2147 * because it informs the driver that the parameter value should be sent to
2148 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2149 * driver may have to do extra work to determine whether the parameter
2150 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2151 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2152 * it might be more efficient to use a version of
2153 * <code>setNClob</code> which takes a length parameter.
2154 *
2155 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2156 * @param reader An object that contains the data to set the parameter value to.
2157 * @throws SQLException if parameterIndex does not correspond to a parameter
2158 * marker in the SQL statement;
2159 * if the driver does not support national character sets;
2160 * if the driver can detect that a data conversion
2161 * error could occur; if a database access error occurs or
2162 * this method is called on a closed <code>PreparedStatement</code>
2163 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2164 *
2165 * @since 1.6
2166 */
2167 void setNClob(int parameterIndex, Reader reader)
2168 throws SQLException;
2169
2170 /**
2171 * Sets the designated parameter to the given <code>java.net.URL</code> value.
2172 * The driver converts this to an SQL <code>DATALINK</code> value
2173 * when it sends it to the database.
2174 *
2175 * @param parameterIndex the first parameter is 1, the second is 2, ...
2176 * @param x the <code>java.net.URL</code> object to be set
2177 * @exception SQLException if a database access error occurs or
2178 * this method is called on a closed <code>PreparedStatement</code>
2179 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2180 * @since 1.4
2181 */
2182 void setURL(int parameterIndex, java.net.URL x) throws SQLException;
2183
2184
2185
2186 }