1 /*
2 * Copyright (c) 2000, 2014, 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 {@code Reader} (a <code>RowSetReader</code> object)
70 * and a writer (a <code>RowSetWriter</code> object) associated with it.
71 * The {@code 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.BigDecimal} 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} 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}
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}
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}
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} object. The
1171 * {@code Reader} 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} then the {@code Reader} must contain the number of characters specified
1204 * by scaleOrLength. If these conditions are not true the driver will generate a
1205 * <code>SQLException</code> when the prepared statement is executed.
1206 *
1207 * <p>The given Java object will be converted to the targetSqlType
1208 * before being sent to the database.
1209 * <P>
1210 * If the object is of a class implementing <code>SQLData</code>,
1211 * the rowset should call the method <code>SQLData.writeSQL</code>
1212 * to write the object to an <code>SQLOutput</code> data stream.
1213 * If, on the other hand, the object is of a class implementing
1214 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1215 * <code>Struct</code>, <code>java.net.URL</code>,
1216 * or <code>Array</code>, the driver should pass it to the database as a
1217 * value of the corresponding SQL type.
1218 *
1219 *
1220 * <p>Note that this method may be used to pass database-specific
1221 * abstract data types.
1222 *
1223 * @param parameterIndex the first parameter is 1, the second is 2, ...
1224 * @param x the object containing the input parameter value
1225 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1226 * to be sent to the database. The scale argument may further qualify this
1227 * type.
1228 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
1229 * or <code>java.sql.Types.NUMERIC types</code>,
1230 * this is the number of digits after the decimal point. For
1231 * Java Object types <code>InputStream</code> and {@code Reader},
1232 * this is the length
1233 * of the data in the stream or {@code Reader}. For all other types,
1234 * this value will be ignored.
1235 * @exception SQLException if a database access error occurs
1236 * @see java.sql.Types
1237 */
1238 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength)
1239 throws SQLException;
1240
1241 /**
1242 * Sets the value of the designated parameter with the given object. The second
1243 * argument must be an object type; for integral values, the
1244 * <code>java.lang</code> equivalent objects should be used.
1245 *
1246 * <p>The given Java object will be converted to the given targetSqlType
1247 * before being sent to the database.
1248 *
1249 * If the object has a custom mapping (is of a class implementing the
1250 * interface <code>SQLData</code>),
1251 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1252 * to the SQL data stream.
1253 * If, on the other hand, the object is of a class implementing
1254 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1255 * <code>Struct</code>, <code>java.net.URL</code>,
1256 * or <code>Array</code>, the driver should pass it to the database as a
1257 * value of the corresponding SQL type.
1258 * <P>
1259 * Note that this method may be used to pass database-
1260 * specific abstract data types.
1261 *
1262 * @param parameterName the name of the parameter
1263 * @param x the object containing the input parameter value
1264 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1265 * sent to the database. The scale argument may further qualify this type.
1266 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1267 * this is the number of digits after the decimal point. For all other
1268 * types, this value will be ignored.
1269 * @exception SQLException if a database access error occurs or
1270 * this method is called on a closed <code>CallableStatement</code>
1271 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1272 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1273 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1274 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1275 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1276 * or <code>STRUCT</code> data type and the JDBC driver does not support
1277 * this data type
1278 * @see Types
1279 * @see #getObject
1280 * @since 1.4
1281 */
1282 void setObject(String parameterName, Object x, int targetSqlType, int scale)
1283 throws SQLException;
1284
1285 /**
1286 * Sets the designated parameter in this <code>RowSet</code> object's command
1287 * with a Java <code>Object</code>. For integral values, the
1288 * <code>java.lang</code> equivalent objects should be used.
1289 * This method is like <code>setObject</code> above, but the scale used is the scale
1290 * of the second parameter. Scalar values have a scale of zero. Literal
1291 * values have the scale present in the literal.
1292 * <P>
1293 * Even though it is supported, it is not recommended that this method
1294 * be called with floating point input values.
1295 *
1296 * @param parameterIndex the first parameter is 1, the second is 2, ...
1297 * @param x the object containing the input parameter value
1298 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1299 * to be sent to the database
1300 * @exception SQLException if a database access error occurs
1301 */
1302 void setObject(int parameterIndex, Object x,
1303 int targetSqlType) throws SQLException;
1304
1305 /**
1306 * Sets the value of the designated parameter with the given object.
1307 * This method is like the method <code>setObject</code>
1308 * above, except that it assumes a scale of zero.
1309 *
1310 * @param parameterName the name of the parameter
1311 * @param x the object containing the input parameter value
1312 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1313 * sent to the database
1314 * @exception SQLException if a database access error occurs or
1315 * this method is called on a closed <code>CallableStatement</code>
1316 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1317 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1318 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1319 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1320 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1321 * or <code>STRUCT</code> data type and the JDBC driver does not support
1322 * this data type
1323 * @see #getObject
1324 * @since 1.4
1325 */
1326 void setObject(String parameterName, Object x, int targetSqlType)
1327 throws SQLException;
1328
1329 /**
1330 * Sets the value of the designated parameter with the given object.
1331 * The second parameter must be of type <code>Object</code>; therefore, the
1332 * <code>java.lang</code> equivalent objects should be used for built-in types.
1333 *
1334 * <p>The JDBC specification specifies a standard mapping from
1335 * Java <code>Object</code> types to SQL types. The given argument
1336 * will be converted to the corresponding SQL type before being
1337 * sent to the database.
1338 *
1339 * <p>Note that this method may be used to pass database-
1340 * specific abstract data types, by using a driver-specific Java
1341 * type.
1342 *
1343 * If the object is of a class implementing the interface <code>SQLData</code>,
1344 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1345 * to write it to the SQL data stream.
1346 * If, on the other hand, the object is of a class implementing
1347 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1348 * <code>Struct</code>, <code>java.net.URL</code>,
1349 * or <code>Array</code>, the driver should pass it to the database as a
1350 * value of the corresponding SQL type.
1351 * <P>
1352 * This method throws an exception if there is an ambiguity, for example, if the
1353 * object is of a class implementing more than one of the interfaces named above.
1354 *
1355 * @param parameterName the name of the parameter
1356 * @param x the object containing the input parameter value
1357 * @exception SQLException if a database access error occurs,
1358 * this method is called on a closed <code>CallableStatement</code> or if the given
1359 * <code>Object</code> parameter is ambiguous
1360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1361 * this method
1362 * @see #getObject
1363 * @since 1.4
1364 */
1365 void setObject(String parameterName, Object x) throws SQLException;
1366
1367 /**
1368 * Sets the designated parameter in this <code>RowSet</code> object's command
1369 * with a Java <code>Object</code>. For integral values, the
1370 * <code>java.lang</code> equivalent objects should be used.
1371 *
1372 * <p>The JDBC specification provides a standard mapping from
1373 * Java Object types to SQL types. The driver will convert the
1374 * given Java object to its standard SQL mapping before sending it
1375 * to the database.
1376 *
1377 * <p>Note that this method may be used to pass database-specific
1378 * abstract data types by using a driver-specific Java type.
1379 *
1380 * If the object is of a class implementing <code>SQLData</code>,
1381 * the rowset should call the method <code>SQLData.writeSQL</code>
1382 * to write the object to an <code>SQLOutput</code> data stream.
1383 * If, on the other hand, the object is of a class implementing
1384 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1385 * <code>Struct</code>, <code>java.net.URL</code>,
1386 * or <code>Array</code>, the driver should pass it to the database as a
1387 * value of the corresponding SQL type.
1388 *
1389 * <P>
1390 * An exception is thrown if there is an ambiguity, for example, if the
1391 * object is of a class implementing more than one of these interfaces.
1392 *
1393 * @param parameterIndex The first parameter is 1, the second is 2, ...
1394 * @param x The object containing the input parameter value
1395 * @exception SQLException if a database access error occurs
1396 */
1397 void setObject(int parameterIndex, Object x) throws SQLException;
1398
1399
1400 /**
1401 * Sets the designated parameter in this <code>RowSet</code> object's command
1402 * with the given <code>Ref</code> value. The driver will convert this
1403 * to the appropriate <code>REF(<structured-type>)</code> value.
1404 *
1405 * @param i the first parameter is 1, the second is 2, ...
1406 * @param x an object representing data of an SQL <code>REF</code> type
1407 * @exception SQLException if a database access error occurs
1408 */
1409 void setRef (int i, Ref x) throws SQLException;
1410
1411 /**
1412 * Sets the designated parameter in this <code>RowSet</code> object's command
1413 * with the given <code>Blob</code> value. The driver will convert this
1414 * to the <code>BLOB</code> value that the <code>Blob</code> object
1415 * represents before sending it to the database.
1416 *
1417 * @param i the first parameter is 1, the second is 2, ...
1418 * @param x an object representing a BLOB
1419 * @exception SQLException if a database access error occurs
1420 */
1421 void setBlob (int i, Blob x) throws SQLException;
1422
1423 /**
1424 * Sets the designated parameter to a <code>InputStream</code> object.
1425 * The <code>InputStream</code> must contain the number
1426 * of characters specified by length otherwise a <code>SQLException</code> will be
1427 * generated when the <code>PreparedStatement</code> is executed.
1428 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1429 * method because it informs the driver that the parameter value should be
1430 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1431 * the driver may have to do extra work to determine whether the parameter
1432 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1433 * @param parameterIndex index of the first parameter is 1,
1434 * the second is 2, ...
1435 * @param inputStream An object that contains the data to set the parameter
1436 * value to.
1437 * @param length the number of bytes in the parameter data.
1438 * @throws SQLException if a database access error occurs,
1439 * this method is called on a closed <code>PreparedStatement</code>,
1440 * if parameterIndex does not correspond
1441 * to a parameter marker in the SQL statement, if the length specified
1442 * is less than zero or if the number of bytes in the <code>InputStream</code> does not match
1443 * the specified length.
1444 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1445 *
1446 * @since 1.6
1447 */
1448 void setBlob(int parameterIndex, InputStream inputStream, long length)
1449 throws SQLException;
1450
1451 /**
1452 * Sets the designated parameter to a <code>InputStream</code> object.
1453 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1454 * method because it informs the driver that the parameter value should be
1455 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1456 * the driver may have to do extra work to determine whether the parameter
1457 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1458 *
1459 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1460 * it might be more efficient to use a version of
1461 * <code>setBlob</code> which takes a length parameter.
1462 *
1463 * @param parameterIndex index of the first parameter is 1,
1464 * the second is 2, ...
1465 * @param inputStream An object that contains the data to set the parameter
1466 * value to.
1467 * @throws SQLException if a database access error occurs,
1468 * this method is called on a closed <code>PreparedStatement</code> or
1469 * if parameterIndex does not correspond
1470 * to a parameter marker in the SQL statement,
1471 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1472 *
1473 * @since 1.6
1474 */
1475 void setBlob(int parameterIndex, InputStream inputStream)
1476 throws SQLException;
1477
1478 /**
1479 * Sets the designated parameter to a <code>InputStream</code> object.
1480 * The {@code InputStream} must contain the number
1481 * of characters specified by length, otherwise a <code>SQLException</code> will be
1482 * generated when the <code>CallableStatement</code> is executed.
1483 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1484 * method because it informs the driver that the parameter value should be
1485 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1486 * the driver may have to do extra work to determine whether the parameter
1487 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1488 *
1489 * @param parameterName the name of the parameter to be set
1490 * the second is 2, ...
1491 *
1492 * @param inputStream An object that contains the data to set the parameter
1493 * value to.
1494 * @param length the number of bytes in the parameter data.
1495 * @throws SQLException if parameterIndex does not correspond
1496 * to a parameter marker in the SQL statement, or if the length specified
1497 * is less than zero; if the number of bytes in the <code>InputStream</code> does not match
1498 * the specified length; if a database access error occurs or
1499 * this method is called on a closed <code>CallableStatement</code>
1500 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1501 * this method
1502 *
1503 * @since 1.6
1504 */
1505 void setBlob(String parameterName, InputStream inputStream, long length)
1506 throws SQLException;
1507
1508 /**
1509 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
1510 * The driver converts this to an SQL <code>BLOB</code> value when it
1511 * sends it to the database.
1512 *
1513 * @param parameterName the name of the parameter
1514 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
1515 * @exception SQLException if a database access error occurs or
1516 * this method is called on a closed <code>CallableStatement</code>
1517 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1518 * this method
1519 * @since 1.6
1520 */
1521 void setBlob (String parameterName, Blob x) throws SQLException;
1522
1523 /**
1524 * Sets the designated parameter to a <code>InputStream</code> object.
1525 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1526 * method because it informs the driver that the parameter value should be
1527 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1528 * the driver may have to do extra work to determine whether the parameter
1529 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1530 *
1531 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1532 * it might be more efficient to use a version of
1533 * <code>setBlob</code> which takes a length parameter.
1534 *
1535 * @param parameterName the name of the parameter
1536 * @param inputStream An object that contains the data to set the parameter
1537 * value to.
1538 * @throws SQLException if a database access error occurs or
1539 * this method is called on a closed <code>CallableStatement</code>
1540 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1541 *
1542 * @since 1.6
1543 */
1544 void setBlob(String parameterName, InputStream inputStream)
1545 throws SQLException;
1546
1547 /**
1548 * Sets the designated parameter in this <code>RowSet</code> object's command
1549 * with the given <code>Clob</code> value. The driver will convert this
1550 * to the <code>CLOB</code> value that the <code>Clob</code> object
1551 * represents before sending it to the database.
1552 *
1553 * @param i the first parameter is 1, the second is 2, ...
1554 * @param x an object representing a CLOB
1555 * @exception SQLException if a database access error occurs
1556 */
1557 void setClob (int i, Clob x) throws SQLException;
1558
1559 /**
1560 * Sets the designated parameter to a {@code Reader} object.
1561 * The {@code Reader} must contain the number
1562 * of characters specified by length otherwise a <code>SQLException</code> will be
1563 * generated when the <code>PreparedStatement</code> is executed.
1564 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1565 * because it informs the driver that the parameter value should be sent to
1566 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1567 * driver may have to do extra work to determine whether the parameter
1568 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1569 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1570 * @param reader An object that contains the data to set the parameter value to.
1571 * @param length the number of characters in the parameter data.
1572 * @throws SQLException if a database access error occurs, this method is called on
1573 * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter
1574 * marker in the SQL statement, or if the length specified is less than zero.
1575 *
1576 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1577 * @since 1.6
1578 */
1579 void setClob(int parameterIndex, Reader reader, long length)
1580 throws SQLException;
1581
1582 /**
1583 * Sets the designated parameter to a {@code Reader} object.
1584 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1585 * because it informs the driver that the parameter value should be sent to
1586 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1587 * driver may have to do extra work to determine whether the parameter
1588 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1589 *
1590 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1591 * it might be more efficient to use a version of
1592 * <code>setClob</code> which takes a length parameter.
1593 *
1594 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1595 * @param reader An object that contains the data to set the parameter value to.
1596 * @throws SQLException if a database access error occurs, this method is called on
1597 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1598 * marker in the SQL statement
1599 *
1600 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1601 * @since 1.6
1602 */
1603 void setClob(int parameterIndex, Reader reader)
1604 throws SQLException;
1605
1606 /**
1607 * Sets the designated parameter to a {@code Reader} object. The
1608 * {@code Reader} must contain the number
1609 * of characters specified by length otherwise a <code>SQLException</code> will be
1610 * generated when the <code>CallableStatement</code> is executed.
1611 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1612 * because it informs the driver that the parameter value should be sent to
1613 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1614 * driver may have to do extra work to determine whether the parameter
1615 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1616 * @param parameterName the name of the parameter to be set
1617 * @param reader An object that contains the data to set the parameter value to.
1618 * @param length the number of characters in the parameter data.
1619 * @throws SQLException if parameterIndex does not correspond to a parameter
1620 * marker in the SQL statement; if the length specified is less than zero;
1621 * a database access error occurs or
1622 * this method is called on a closed <code>CallableStatement</code>
1623 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1624 * this method
1625 *
1626 * @since 1.6
1627 */
1628 void setClob(String parameterName, Reader reader, long length)
1629 throws SQLException;
1630
1631 /**
1632 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
1633 * The driver converts this to an SQL <code>CLOB</code> value when it
1634 * sends it to the database.
1635 *
1636 * @param parameterName the name of the parameter
1637 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
1638 * @exception SQLException if a database access error occurs or
1639 * this method is called on a closed <code>CallableStatement</code>
1640 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1641 * this method
1642 * @since 1.6
1643 */
1644 void setClob (String parameterName, Clob x) throws SQLException;
1645
1646 /**
1647 * Sets the designated parameter to a {@code Reader} object.
1648 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1649 * because it informs the driver that the parameter value should be sent to
1650 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1651 * driver may have to do extra work to determine whether the parameter
1652 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1653 *
1654 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1655 * it might be more efficient to use a version of
1656 * <code>setClob</code> which takes a length parameter.
1657 *
1658 * @param parameterName the name of the parameter
1659 * @param reader An object that contains the data to set the parameter value to.
1660 * @throws SQLException if a database access error occurs or this method is called on
1661 * a closed <code>CallableStatement</code>
1662 *
1663 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1664 * @since 1.6
1665 */
1666 void setClob(String parameterName, Reader reader)
1667 throws SQLException;
1668
1669 /**
1670 * Sets the designated parameter in this <code>RowSet</code> object's command
1671 * with the given <code>Array</code> value. The driver will convert this
1672 * to the <code>ARRAY</code> value that the <code>Array</code> object
1673 * represents before sending it to the database.
1674 *
1675 * @param i the first parameter is 1, the second is 2, ...
1676 * @param x an object representing an SQL array
1677 * @exception SQLException if a database access error occurs
1678 */
1679 void setArray (int i, Array x) throws SQLException;
1680
1681 /**
1682 * Sets the designated parameter in this <code>RowSet</code> object's command
1683 * with the given <code>java.sql.Date</code> value. The driver will convert this
1684 * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code>
1685 * object to calculate the date.
1686 *
1687 * @param parameterIndex the first parameter is 1, the second is 2, ...
1688 * @param x the parameter value
1689 * @param cal the <code>java.util.Calendar</code> object to use for calculating the date
1690 * @exception SQLException if a database access error occurs
1691 */
1692 void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
1693 throws SQLException;
1694
1695 /**
1696 * Sets the designated parameter to the given <code>java.sql.Date</code> value
1697 * using the default time zone of the virtual machine that is running
1698 * the application.
1699 * The driver converts this
1700 * to an SQL <code>DATE</code> value when it sends it to the database.
1701 *
1702 * @param parameterName the name of the parameter
1703 * @param x the parameter value
1704 * @exception SQLException if a database access error occurs or
1705 * this method is called on a closed <code>CallableStatement</code>
1706 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1707 * this method
1708 * @see #getDate
1709 * @since 1.4
1710 */
1711 void setDate(String parameterName, java.sql.Date x)
1712 throws SQLException;
1713
1714 /**
1715 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1716 * using the given <code>Calendar</code> object. The driver uses
1717 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1718 * which the driver then sends to the database. With a
1719 * a <code>Calendar</code> object, the driver can calculate the date
1720 * taking into account a custom timezone. If no
1721 * <code>Calendar</code> object is specified, the driver uses the default
1722 * timezone, which is that of the virtual machine running the application.
1723 *
1724 * @param parameterName the name of the parameter
1725 * @param x the parameter value
1726 * @param cal the <code>Calendar</code> object the driver will use
1727 * to construct the date
1728 * @exception SQLException if a database access error occurs or
1729 * this method is called on a closed <code>CallableStatement</code>
1730 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1731 * this method
1732 * @see #getDate
1733 * @since 1.4
1734 */
1735 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1736 throws SQLException;
1737
1738 /**
1739 * Sets the designated parameter in this <code>RowSet</code> object's command
1740 * with the given <code>java.sql.Time</code> value. The driver will convert this
1741 * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code>
1742 * object to calculate it, before sending it to the database.
1743 *
1744 * @param parameterIndex the first parameter is 1, the second is 2, ...
1745 * @param x the parameter value
1746 * @param cal the <code>java.util.Calendar</code> object to use for calculating the time
1747 * @exception SQLException if a database access error occurs
1748 */
1749 void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
1750 throws SQLException;
1751
1752 /**
1753 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
1754 * The driver converts this
1755 * to an SQL <code>TIME</code> value when it sends it to the database.
1756 *
1757 * @param parameterName the name of the parameter
1758 * @param x the parameter value
1759 * @exception SQLException if a database access error occurs or
1760 * this method is called on a closed <code>CallableStatement</code>
1761 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1762 * this method
1763 * @see #getTime
1764 * @since 1.4
1765 */
1766 void setTime(String parameterName, java.sql.Time x)
1767 throws SQLException;
1768
1769 /**
1770 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1771 * using the given <code>Calendar</code> object. The driver uses
1772 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1773 * which the driver then sends to the database. With a
1774 * a <code>Calendar</code> object, the driver can calculate the time
1775 * taking into account a custom timezone. If no
1776 * <code>Calendar</code> object is specified, the driver uses the default
1777 * timezone, which is that of the virtual machine running the application.
1778 *
1779 * @param parameterName the name of the parameter
1780 * @param x the parameter value
1781 * @param cal the <code>Calendar</code> object the driver will use
1782 * to construct the time
1783 * @exception SQLException if a database access error occurs or
1784 * this method is called on a closed <code>CallableStatement</code>
1785 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1786 * this method
1787 * @see #getTime
1788 * @since 1.4
1789 */
1790 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1791 throws SQLException;
1792
1793 /**
1794 * Sets the designated parameter in this <code>RowSet</code> object's command
1795 * with the given <code>java.sql.Timestamp</code> value. The driver will
1796 * convert this to an SQL <code>TIMESTAMP</code> value, using the given
1797 * <code>java.util.Calendar</code> object to calculate it, before sending it to the
1798 * database.
1799 *
1800 * @param parameterIndex the first parameter is 1, the second is 2, ...
1801 * @param x the parameter value
1802 * @param cal the <code>java.util.Calendar</code> object to use for calculating the
1803 * timestamp
1804 * @exception SQLException if a database access error occurs
1805 */
1806 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)
1807 throws SQLException;
1808
1809 /**
1810 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1811 * using the given <code>Calendar</code> object. The driver uses
1812 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1813 * which the driver then sends to the database. With a
1814 * a <code>Calendar</code> object, the driver can calculate the timestamp
1815 * taking into account a custom timezone. If no
1816 * <code>Calendar</code> object is specified, the driver uses the default
1817 * timezone, which is that of the virtual machine running the application.
1818 *
1819 * @param parameterName the name of the parameter
1820 * @param x the parameter value
1821 * @param cal the <code>Calendar</code> object the driver will use
1822 * to construct the timestamp
1823 * @exception SQLException if a database access error occurs or
1824 * this method is called on a closed <code>CallableStatement</code>
1825 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1826 * this method
1827 * @see #getTimestamp
1828 * @since 1.4
1829 */
1830 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1831 throws SQLException;
1832
1833 /**
1834 * Clears the parameters set for this <code>RowSet</code> object's command.
1835 * <P>In general, parameter values remain in force for repeated use of a
1836 * <code>RowSet</code> object. Setting a parameter value automatically clears its
1837 * previous value. However, in some cases it is useful to immediately
1838 * release the resources used by the current parameter values, which can
1839 * be done by calling the method <code>clearParameters</code>.
1840 *
1841 * @exception SQLException if a database access error occurs
1842 */
1843 void clearParameters() throws SQLException;
1844
1845 //---------------------------------------------------------------------
1846 // Reading and writing data
1847 //---------------------------------------------------------------------
1848
1849 /**
1850 * Fills this <code>RowSet</code> object with data.
1851 * <P>
1852 * The <code>execute</code> method may use the following properties
1853 * to create a connection for reading data: url, data source name,
1854 * user name, password, transaction isolation, and type map.
1855 *
1856 * The <code>execute</code> method may use the following properties
1857 * to create a statement to execute a command:
1858 * command, read only, maximum field size,
1859 * maximum rows, escape processing, and query timeout.
1860 * <P>
1861 * If the required properties have not been set, an exception is
1862 * thrown. If this method is successful, the current contents of the rowset are
1863 * discarded and the rowset's metadata is also (re)set. If there are
1864 * outstanding updates, they are ignored.
1865 * <P>
1866 * If this <code>RowSet</code> object does not maintain a continuous connection
1867 * with its source of data, it may use a {@code Reader} (a <code>RowSetReader</code>
1868 * object) to fill itself with data. In this case, a {@code Reader} will have been
1869 * registered with this <code>RowSet</code> object, and the method
1870 * <code>execute</code> will call on the {@code Reader}'s <code>readData</code>
1871 * method as part of its implementation.
1872 *
1873 * @exception SQLException if a database access error occurs or any of the
1874 * properties necessary for making a connection and creating
1875 * a statement have not been set
1876 */
1877 void execute() throws SQLException;
1878
1879 //--------------------------------------------------------------------
1880 // Events
1881 //--------------------------------------------------------------------
1882
1883 /**
1884 * Registers the given listener so that it will be notified of events
1885 * that occur on this <code>RowSet</code> object.
1886 *
1887 * @param listener a component that has implemented the <code>RowSetListener</code>
1888 * interface and wants to be notified when events occur on this
1889 * <code>RowSet</code> object
1890 * @see #removeRowSetListener
1891 */
1892 void addRowSetListener(RowSetListener listener);
1893
1894 /**
1895 * Removes the specified listener from the list of components that will be
1896 * notified when an event occurs on this <code>RowSet</code> object.
1897 *
1898 * @param listener a component that has been registered as a listener for this
1899 * <code>RowSet</code> object
1900 * @see #addRowSetListener
1901 */
1902 void removeRowSetListener(RowSetListener listener);
1903
1904 /**
1905 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1906 * SQL <code>XML</code> value when it sends it to the database.
1907 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1908 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
1909 * @throws SQLException if a database access error occurs, this method
1910 * is called on a closed result set,
1911 * the <code>java.xml.transform.Result</code>,
1912 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1913 * for the <code>SQLXML</code> object or
1914 * if there is an error processing the XML value. The <code>getCause</code> method
1915 * of the exception may provide a more detailed exception, for example, if the
1916 * stream does not contain valid XML.
1917 * @since 1.6
1918 */
1919 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException;
1920
1921 /**
1922 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1923 * <code>SQL XML</code> value when it sends it to the database.
1924 * @param parameterName the name of the parameter
1925 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1926 * @throws SQLException if a database access error occurs, this method
1927 * is called on a closed result set,
1928 * the <code>java.xml.transform.Result</code>,
1929 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1930 * for the <code>SQLXML</code> object or
1931 * if there is an error processing the XML value. The <code>getCause</code> method
1932 * of the exception may provide a more detailed exception, for example, if the
1933 * stream does not contain valid XML.
1934 * @since 1.6
1935 */
1936 void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException;
1937
1938 /**
1939 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1940 * driver converts this to a SQL <code>ROWID</code> value when it sends it
1941 * to the database
1942 *
1943 * @param parameterIndex the first parameter is 1, the second is 2, ...
1944 * @param x the parameter value
1945 * @throws SQLException if a database access error occurs
1946 *
1947 * @since 1.6
1948 */
1949 void setRowId(int parameterIndex, RowId x) throws SQLException;
1950
1951 /**
1952 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1953 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1954 * database.
1955 *
1956 * @param parameterName the name of the parameter
1957 * @param x the parameter value
1958 * @throws SQLException if a database access error occurs
1959 * @since 1.6
1960 */
1961 void setRowId(String parameterName, RowId x) throws SQLException;
1962
1963 /**
1964 * Sets the designated parameter to the given <code>String</code> object.
1965 * The driver converts this to a SQL <code>NCHAR</code> or
1966 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
1967 * (depending on the argument's
1968 * size relative to the driver's limits on <code>NVARCHAR</code> values)
1969 * when it sends it to the database.
1970 *
1971 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1972 * @param value the parameter value
1973 * @throws SQLException if the driver does not support national
1974 * character sets; if the driver can detect that a data conversion
1975 * error could occur ; or if a database access error occurs
1976 * @since 1.6
1977 */
1978 void setNString(int parameterIndex, String value) throws SQLException;
1979
1980 /**
1981 * Sets the designated parameter to the given <code>String</code> object.
1982 * The driver converts this to a SQL <code>NCHAR</code> or
1983 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1984 * @param parameterName the name of the column to be set
1985 * @param value the parameter value
1986 * @throws SQLException if the driver does not support national
1987 * character sets; if the driver can detect that a data conversion
1988 * error could occur; or if a database access error occurs
1989 * @since 1.6
1990 */
1991 public void setNString(String parameterName, String value)
1992 throws SQLException;
1993
1994 /**
1995 * Sets the designated parameter to a {@code Reader} object. The
1996 * {@code Reader} reads the data till end-of-file is reached. The
1997 * driver does the necessary conversion from Java character format to
1998 * the national character set in the database.
1999 * @param parameterIndex of the first parameter is 1, the second is 2, ...
2000 * @param value the parameter value
2001 * @param length the number of characters in the parameter data.
2002 * @throws SQLException if the driver does not support national
2003 * character sets; if the driver can detect that a data conversion
2004 * error could occur ; or if a database access error occurs
2005 * @since 1.6
2006 */
2007 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException;
2008
2009 /**
2010 * Sets the designated parameter to a {@code Reader} object. The
2011 * {@code Reader} reads the data till end-of-file is reached. The
2012 * driver does the necessary conversion from Java character format to
2013 * the national character set in the database.
2014 * @param parameterName the name of the column to be set
2015 * @param value the parameter value
2016 * @param length the number of characters in the parameter data.
2017 * @throws SQLException if the driver does not support national
2018 * character sets; if the driver can detect that a data conversion
2019 * error could occur; or if a database access error occurs
2020 * @since 1.6
2021 */
2022 public void setNCharacterStream(String parameterName, Reader value, long length)
2023 throws SQLException;
2024
2025 /**
2026 * Sets the designated parameter to a {@code Reader} object. The
2027 * {@code Reader} reads the data till end-of-file is reached. The
2028 * driver does the necessary conversion from Java character format to
2029 * the national character set in the database.
2030
2031 * <P><B>Note:</B> This stream object can either be a standard
2032 * Java stream object or your own subclass that implements the
2033 * standard interface.
2034 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2035 * it might be more efficient to use a version of
2036 * <code>setNCharacterStream</code> which takes a length parameter.
2037 *
2038 * @param parameterName the name of the parameter
2039 * @param value the parameter value
2040 * @throws SQLException if the driver does not support national
2041 * character sets; if the driver can detect that a data conversion
2042 * error could occur ; if a database access error occurs; or
2043 * this method is called on a closed <code>CallableStatement</code>
2044 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2045 * @since 1.6
2046 */
2047 void setNCharacterStream(String parameterName, Reader value) throws SQLException;
2048
2049 /**
2050 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
2051 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
2052 * object maps to a SQL <code>NCLOB</code>.
2053 * @param parameterName the name of the column to be set
2054 * @param value the parameter value
2055 * @throws SQLException if the driver does not support national
2056 * character sets; if the driver can detect that a data conversion
2057 * error could occur; or if a database access error occurs
2058 * @since 1.6
2059 */
2060 void setNClob(String parameterName, NClob value) throws SQLException;
2061
2062 /**
2063 * Sets the designated parameter to a {@code Reader} object.
2064 * The {@code Reader} must contain the number
2065 * of characters specified by length otherwise a <code>SQLException</code> will be
2066 * generated when the <code>CallableStatement</code> is executed.
2067 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2068 * because it informs the driver that the parameter value should be sent to
2069 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2070 * driver may have to do extra work to determine whether the parameter
2071 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2072 *
2073 * @param parameterName the name of the parameter to be set
2074 * @param reader An object that contains the data to set the parameter value to.
2075 * @param length the number of characters in the parameter data.
2076 * @throws SQLException if parameterIndex does not correspond to a parameter
2077 * marker in the SQL statement; if the length specified is less than zero;
2078 * if the driver does not support national
2079 * character sets; if the driver can detect that a data conversion
2080 * error could occur; if a database access error occurs or
2081 * this method is called on a closed <code>CallableStatement</code>
2082 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2083 * this method
2084 * @since 1.6
2085 */
2086 void setNClob(String parameterName, Reader reader, long length)
2087 throws SQLException;
2088
2089 /**
2090 * Sets the designated parameter to a {@code Reader} object.
2091 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2092 * because it informs the driver that the parameter value should be sent to
2093 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2094 * driver may have to do extra work to determine whether the parameter
2095 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2096 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2097 * it might be more efficient to use a version of
2098 * <code>setNClob</code> which takes a length parameter.
2099 *
2100 * @param parameterName the name of the parameter
2101 * @param reader An object that contains the data to set the parameter value to.
2102 * @throws SQLException if the driver does not support national character sets;
2103 * if the driver can detect that a data conversion
2104 * error could occur; if a database access error occurs or
2105 * this method is called on a closed <code>CallableStatement</code>
2106 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2107 *
2108 * @since 1.6
2109 */
2110 void setNClob(String parameterName, Reader reader)
2111 throws SQLException;
2112
2113 /**
2114 * Sets the designated parameter to a {@code Reader} object.
2115 * The {@code Reader} must contain the number
2116 * of characters specified by length otherwise a <code>SQLException</code> will be
2117 * generated when the <code>PreparedStatement</code> is executed.
2118 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2119 * because it informs the driver that the parameter value should be sent to
2120 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2121 * driver may have to do extra work to determine whether the parameter
2122 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2123 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2124 * @param reader An object that contains the data to set the parameter value to.
2125 * @param length the number of characters in the parameter data.
2126 * @throws SQLException if parameterIndex does not correspond to a parameter
2127 * marker in the SQL statement; if the length specified is less than zero;
2128 * if the driver does not support national character sets;
2129 * if the driver can detect that a data conversion
2130 * error could occur; if a database access error occurs or
2131 * this method is called on a closed <code>PreparedStatement</code>
2132 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2133 *
2134 * @since 1.6
2135 */
2136 void setNClob(int parameterIndex, Reader reader, long length)
2137 throws SQLException;
2138
2139 /**
2140 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
2141 * SQL <code>NCLOB</code> value when it sends it to the database.
2142 * @param parameterIndex of the first parameter is 1, the second is 2, ...
2143 * @param value the parameter value
2144 * @throws SQLException if the driver does not support national
2145 * character sets; if the driver can detect that a data conversion
2146 * error could occur ; or if a database access error occurs
2147 * @since 1.6
2148 */
2149 void setNClob(int parameterIndex, NClob value) throws SQLException;
2150
2151 /**
2152 * Sets the designated parameter to a {@code Reader} object.
2153 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2154 * because it informs the driver that the parameter value should be sent to
2155 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2156 * driver may have to do extra work to determine whether the parameter
2157 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2158 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2159 * it might be more efficient to use a version of
2160 * <code>setNClob</code> which takes a length parameter.
2161 *
2162 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2163 * @param reader An object that contains the data to set the parameter value to.
2164 * @throws SQLException if parameterIndex does not correspond to a parameter
2165 * marker in the SQL statement;
2166 * if the driver does not support national character sets;
2167 * if the driver can detect that a data conversion
2168 * error could occur; if a database access error occurs or
2169 * this method is called on a closed <code>PreparedStatement</code>
2170 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2171 *
2172 * @since 1.6
2173 */
2174 void setNClob(int parameterIndex, Reader reader)
2175 throws SQLException;
2176
2177 /**
2178 * Sets the designated parameter to the given <code>java.net.URL</code> value.
2179 * The driver converts this to an SQL <code>DATALINK</code> value
2180 * when it sends it to the database.
2181 *
2182 * @param parameterIndex the first parameter is 1, the second is 2, ...
2183 * @param x the <code>java.net.URL</code> object to be set
2184 * @exception SQLException if a database access error occurs or
2185 * this method is called on a closed <code>PreparedStatement</code>
2186 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2187 * @since 1.4
2188 */
2189 void setURL(int parameterIndex, java.net.URL x) throws SQLException;
2190
2191
2192
2193 }