Java > Open Source Codes > javax > sql > RowSet


1 /*
2  * @(#)RowSet.java 1.15 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sql;
9
10 import java.sql.*;
11 import java.io.*;
12 import java.math.*;
13 import java.util.*;
14
15 /**
16  * The interface that adds support to the JDBC API for the
17  * JavaBeans<sup><font size=-2>TM</font></sup> component model.
18  * A rowset, which can be used as a JavaBeans component in
19  * a visual Bean development environment, can be created and
20  * configured at design time and executed at run time.
21  * <P>
22  * The <code>RowSet</code>
23  * interface provides a set of JavaBeans properties that allow a <code>RowSet</code>
24  * instance to be configured to connect to a JDBC data source and read
25  * some data from the data source. A group of setter methods (<code>setInt</code>,
26  * <code>setBytes</code>, <code>setString</code>, and so on)
27  * provide a way to pass input parameters to a rowset's command property.
28  * This command is the SQL query the rowset uses when it gets its data from
29  * a relational database, which is generally the case.
30  * <P>
31  * The <code>RowSet</code>
32  * interface supports JavaBeans events, allowing other components in an
33  * application to be notified when an event occurs on a rowset,
34  * such as a change in its value.
35  *
36  * <P>The <code>RowSet</code> interface is unique in that it is intended to be
37  * implemented using the rest of the JDBC API. In other words, a
38  * <code>RowSet</code> implementation is a layer of software that executes "on top"
39  * of a JDBC driver. Implementations of the <code>RowSet</code> interface can
40  * be provided by anyone, including JDBC driver vendors who want to
41  * provide a <code>RowSet</code> implementation as part of their JDBC products.
42  * <P>
43  * A <code>RowSet</code> object may make a connection with a data source and
44  * maintain that connection throughout its life cycle, in which case it is
45  * called a <i>connected</i> rowset. A rowset may also make a connection with
46  * a data source, get data from it, and then close the connection. Such a rowset
47  * is called a <i>disconnected</i> rowset. A disconnected rowset may make
48  * changes to its data while it is disconnected and then send the changes back
49  * to the original source of the data, but it must reestablish a connection to do so.
50  * <P>
51  * A disconnected rowset may have a reader (a <code>RowSetReader</code> object)
52  * and a writer (a <code>RowSetWriter</code> object) associated with it.
53  * The reader may be implemented in many different ways to populate a rowset
54  * with data, including getting data from a non-relational data source. The
55  * writer can also be implemented in many different ways to propagate changes
56  * made to the rowset's data back to the underlying data source.
57  * <P>
58  * Rowsets are easy to use. The <code>RowSet</code> interface extends the standard
59  * <code>java.sql.ResultSet</code> interface. The <code>RowSetMetaData</code>
60  * interface extends the <code>java.sql.ResultSetMetaData</code> interface.
61  * Thus, developers familiar
62  * with the JDBC API will have to learn a minimal number of new APIs to
63  * use rowsets. In addition, third-party software tools that work with
64  * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets.
65  *
66  * @since 1.4
67  */
68
69 public interface RowSet extends ResultSet {
70   
71   //-----------------------------------------------------------------------
72 // Properties
73 //-----------------------------------------------------------------------
74
75   //-----------------------------------------------------------------------
76 // The following properties may be used to create a Connection.
77 //-----------------------------------------------------------------------
78
79   /**
80    * Retrieves the url property this <code>RowSet</code> object will use to
81    * create a connection if it uses the <code>DriverManager</code>
82    * instead of a <code>DataSource</code> object to establish the connection.
83    * The default value is <code>null</code>.
84    *
85    * @return a string url
86    * @exception SQLException if a database access error occurs
87    * @see #setUrl
88    */
89   String getUrl() throws SQLException;
90
91   /**
92    * Sets the URL this <code>RowSet</code> object will use when it uses the
93    * <code>DriverManager</code> to create a connection.
94    *
95    * Setting this property is optional. If a URL is used, a JDBC driver
96    * that accepts the URL must be loaded by the application before the
97    * rowset is used to connect to a database. The rowset will use the URL
98    * internally to create a database connection when reading or writing
99    * data. Either a URL or a data source name is used to create a
100    * connection, whichever was specified most recently.
101    *
102    * @param url a string value; may be <code>null</code>
103    * @exception SQLException if a database access error occurs
104    * @see #getUrl
105    */
106   void setUrl(String url) throws SQLException;
107
108   /**
109    * Retrieves the logical name that identifies the data source for this
110    * <code>RowSet</code> object. Users should set
111    * either the url property or the data source name property. The rowset will use
112    * the property that was set more recently to get a connection.
113    *
114    * @return a data source name
115    * @see #setDataSourceName
116    * @see #setUrl
117    */
118   String getDataSourceName();
119
120   /**
121    * Sets the data source name property for this <code>RowSet</code> object to the
122    * given <code>String</code>.
123    * <P>
124    * The value of the data source name property can be used to do a lookup of
125    * a <code>DataSource</code> object that has been registered with a naming
126    * service. After being retrieved, the <code>DataSource</code> object can be
127    * used to create a connection to the data source that it represents.
128    *
129    * @param name the logical name of the data source for this <code>RowSet</code>
130    * object
131    * @exception SQLException if a database access error occurs
132    * @see #getDataSourceName
133    */
134   void setDataSourceName(String name) throws SQLException;
135
136   /**
137    * Retrieves the username used to create a database connection for this
138    * <code>RowSet</code> object.
139    * The username property is set at run time before calling the method
140    * <code>execute</code>. It is
141    * not usually part of the serialized state of a <code>RowSet</code> object.
142    *
143    * @return the username property
144    * @see #setUsername
145    */
146   String getUsername();
147
148   /**
149    * Sets the username property for this <code>RowSet</code> object to the
150    * given <code>String</code>.
151    *
152    * @param name a user name
153    * @exception SQLException if a database access error occurs
154    * @see #getUsername
155    */
156   void setUsername(String name) throws SQLException;
157
158   /**
159    * Retrieves the password used to create a database connection.
160    * The password property is set at run time before calling the method
161    * <code>execute</code>. It is not usually part of the serialized state
162    * of a <code>RowSet</code> object.
163    *
164    * @return the password for making a database connection
165    * @see #setPassword
166    */
167   String getPassword();
168
169   /**
170    * Sets the database password for this <code>RowSet</code> object to
171    * the given <code>String</code>.
172    *
173    * @param password the password string
174    * @exception SQLException if a database access error occurs
175    * @see #getPassword
176    */
177   void setPassword(String password) throws SQLException;
178
179   /**
180    * Retrieves the transaction isolation level set for this
181    * <code>RowSet</code> object.
182    *
183    * @return the transaction isolation level; one of
184    * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
185    * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
186    * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
187    * <code>Connection.TRANSACTION_SERIALIZABLE</code>
188    * @see #setTransactionIsolation
189    */
190   int getTransactionIsolation();
191
192   /**
193    * Sets the transaction isolation level for this <code>RowSet</code> obejct.
194    *
195    * @param level the transaction isolation level; one of
196    * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
197    * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
198    * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
199    * <code>Connection.TRANSACTION_SERIALIZABLE</code>
200    * @exception SQLException if a database access error occurs
201    * @see #getTransactionIsolation
202    */
203   void setTransactionIsolation(int level) throws SQLException;
204
205   /**
206    * Retrieves the <code>Map</code> object associated with this
207    * <code>RowSet</code> object, which specifies the custom mapping
208    * of SQL user-defined types, if any. The default is for the
209    * type map to be empty.
210    *
211    * @return a <code>java.util.Map</code> object containing the names of
212    * SQL user-defined types and the Java classes to which they are
213    * to be mapped
214    *
215    * @exception SQLException if a database access error occurs
216    * @see #setTypeMap
217    */
218   java.util.Map <String ,Class <?>> getTypeMap() throws SQLException;
219
220   /**
221    * Installs the given <code>java.util.Map</code> object as the default
222    * type map for this <code>RowSet</code> object. This type map will be
223    * used unless another type map is supplied as a method parameter.
224    *
225    * @param map a <code>java.util.Map</code> object containing the names of
226    * SQL user-defined types and the Java classes to which they are
227    * to be mapped
228    * @exception SQLException if a database access error occurs
229    * @see #getTypeMap
230    */
231   void setTypeMap(java.util.Map <String ,Class <?>> map) throws SQLException;
232
233   //-----------------------------------------------------------------------
234 // The following properties may be used to create a Statement.
235 //-----------------------------------------------------------------------
236
237   /**
238    * Retrieves this <code>RowSet</code> object's command property.
239    *
240    * The command property contains a command string, which must be an SQL
241    * query, that can be executed to fill the rowset with data.
242    * The default value is <code>null</code>.
243    *
244    * @return the command string; may be <code>null</code>
245    * @see #setCommand
246    */
247   String getCommand();
248
249   /**
250    * Sets this <code>RowSet</code> object's command property to the given
251    * SQL query.
252    *
253    * This property is optional
254    * when a rowset gets its data from a data source that does not support
255    * commands, such as a spreadsheet.
256    *
257    * @param cmd the SQL query that will be used to get the data for this
258    * <code>RowSet</code> object; may be <code>null</code>
259    * @exception SQLException if a database access error occurs
260    * @see #getCommand
261    */
262   void setCommand(String cmd) throws SQLException;
263
264   /**
265    * Retrieves whether this <code>RowSet</code> object is read-only.
266    * If updates are possible, the default is for a rowset to be
267    * updatable.
268    * <P>
269    * Attempts to update a read-only rowset will result in an
270    * <code>SQLException</code> being thrown.
271    *
272    * @return <code>true</code> if this <code>RowSet</code> object is
273    * read-only; <code>false</code> if it is updatable
274    * @see #setReadOnly
275    */
276   boolean isReadOnly();
277
278   /**
279    * Sets whether this <code>RowSet</code> object is read-only to the
280    * given <code>boolean</code>.
281    *
282    * @param value <code>true</code> if read-only; <code>false</code> if
283    * updatable
284    * @exception SQLException if a database access error occurs
285    * @see #isReadOnly
286    */
287   void setReadOnly(boolean value) throws SQLException;
288
289   /**
290    * Retrieves the maximum number of bytes that may be returned
291    * for certain column values.
292    * This limit applies only to <code>BINARY</code>,
293    * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
294    * <code>VARCHAR</code>, and <code>LONGVARCHAR</code> columns.
295    * If the limit is exceeded, the excess data is silently discarded.
296    *
297    * @return the current maximum column size limit; zero means that there
298    * is no limit
299    * @exception SQLException if a database access error occurs
300    * @see #setMaxFieldSize
301    */
302   int getMaxFieldSize() throws SQLException;
303     
304   /**
305    * Sets the maximum number of bytes that can be returned for a column
306    * value to the given number of bytes.
307    * This limit applies only to <code>BINARY</code>,
308    * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
309    * <code>VARCHAR</code>, and <code>LONGVARCHAR</code> columns.
310    * If the limit is exceeded, the excess data is silently discarded.
311    * For maximum portability, use values greater than 256.
312    *
313    * @param max the new max column size limit in bytes; zero means unlimited
314    * @exception SQLException if a database access error occurs
315    * @see #getMaxFieldSize
316    */
317   void setMaxFieldSize(int max) throws SQLException;
318
319   /**
320    * Retrieves the maximum number of rows that this <code>RowSet</code>
321    * object can contain.
322    * If the limit is exceeded, the excess rows are silently dropped.
323    *
324    * @return the current maximum number of rows that this <code>RowSet</code>
325    * object can contain; zero means unlimited
326    * @exception SQLException if a database access error occurs
327    * @see #setMaxRows
328    */
329   int getMaxRows() throws SQLException;
330
331   /**
332    * Sets the maximum number of rows that this <code>RowSet</code>
333    * object can contain to the specified number.
334    * If the limit is exceeded, the excess rows are silently dropped.
335    *
336    * @param max the new maximum number of rows; zero means unlimited
337    * @exception SQLException if a database access error occurs
338    * @see #getMaxRows
339    */
340   void setMaxRows(int max) throws SQLException;
341
342   /**
343    * Retrieves whether escape processing is enabled for this
344    * <code>RowSet</code> object.
345    * If escape scanning is enabled, which is the default, the driver will do
346    * escape substitution before sending an SQL statement to the database.
347    *
348    * @return <code>true</code> if escape processing is enabled;
349    * <code>false</code> if it is disabled
350    * @exception SQLException if a database access error occurs
351    * @see #setEscapeProcessing
352    */
353   boolean getEscapeProcessing() throws SQLException;
354
355   /**
356    * Sets escape processing for this <code>RowSet</code> object on or
357    * off. If escape scanning is on (the default), the driver will do
358    * escape substitution before sending an SQL statement to the database.
359    *
360    * @param enable <code>true</code> to enable escape processing;
361    * <code>false</code> to disable it
362    * @exception SQLException if a database access error occurs
363    * @see #getEscapeProcessing
364    */
365   void setEscapeProcessing(boolean enable) throws SQLException;
366
367   /**
368    * Retrieves the maximum number of seconds the driver will wait for
369    * a statement to execute.
370    * If this limit is exceeded, an <code>SQLException</code> is thrown.
371    *
372    * @return the current query timeout limit in seconds; zero means
373    * unlimited
374    * @exception SQLException if a database access error occurs
375    * @see #setQueryTimeout
376    */
377   int getQueryTimeout() throws SQLException;
378
379   /**
380    * Sets the maximum time the driver will wait for
381    * a statement to execute to the given number of seconds.
382    * If this limit is exceeded, an <code>SQLException</code> is thrown.
383    *
384    * @param seconds the new query timeout limit in seconds; zero means
385    * that there is no limit
386    * @exception SQLException if a database access error occurs
387    * @see #getQueryTimeout
388    */
389   void setQueryTimeout(int seconds) throws SQLException;
390
391   /**
392    * Sets the type of this <code>RowSet</code> object to the given type.
393    * This method is used to change the type of a rowset, which is by
394    * default read-only and non-scrollable.
395    *
396    * @param type one of the <code>ResultSet</code> constants specifying a type:
397    * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
398    * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
399    * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
400    * @exception SQLException if a database access error occurs
401    * @see java.sql.ResultSet#getType
402    */
403   void setType(int type) throws SQLException;
404
405   /**
406    * Sets the concurrency of this <code>RowSet</code> object to the given
407    * concurrency level. This method is used to change the concurrency level
408    * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code>
409    *
410    * @param concurrency one of the <code>ResultSet</code> constants specifying a
411    * concurrency level: <code>ResultSet.CONCUR_READ_ONLY</code> or
412    * <code>ResultSet.CONCUR_UPDATABLE</code>
413    * @exception SQLException if a database access error occurs
414    * @see ResultSet#getConcurrency
415    */
416   void setConcurrency(int concurrency) throws SQLException;
417   
418   //-----------------------------------------------------------------------
419 // Parameters
420 //-----------------------------------------------------------------------
421
422   /**
423    * The <code>RowSet</code> setter methods are used to set any input parameters
424    * needed by the <code>RowSet</code> object's command.
425    * Parameters are set at run time, as opposed to design time.
426    */
427
428   /**
429    * Sets the designated parameter in this <code>RowSet</code> object's SQL
430    * command to SQL <code>NULL</code>.
431    *
432    * <P><B>Note:</B> You must specify the parameter's SQL type.
433    *
434    * @param parameterIndex the first parameter is 1, the second is 2, ...
435    * @param sqlType a SQL type code defined by <code>java.sql.Types</code>
436    * @exception SQLException if a database access error occurs
437    */
438   void setNull(int parameterIndex, int sqlType) throws SQLException;
439
440   /**
441    * Sets the designated parameter in this <code>RowSet</code> object's SQL
442    * command to SQL <code>NULL</code>. This version of the method <code>setNull</code>
443    * should be used for SQL user-defined types (UDTs) and <code>REF</code> type
444    * parameters. Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>,
445    * <code>JAVA_OBJECT</code>, and named array types.
446    *
447    * <P><B>Note:</B> To be portable, applications must give the
448    * SQL type code and the fully qualified SQL type name when specifying
449    * a NULL UDT or <code>REF</code> parameter. In the case of a UDT,
450    * the name is the type name of the parameter itself. For a <code>REF</code>
451    * parameter, the name is the type name of the referenced type. If
452    * a JDBC driver does not need the type code or type name information,
453    * it may ignore it.
454    *
455    * Although it is intended for UDT and <code>REF</code> parameters,
456    * this method may be used to set a null parameter of any JDBC type.
457    * If the parameter does not have a user-defined or <code>REF</code> type,
458    * the typeName parameter is ignored.
459    *
460    *
461    * @param paramIndex the first parameter is 1, the second is 2, ...
462    * @param sqlType a value from <code>java.sql.Types</code>
463    * @param typeName the fully qualified name of an SQL UDT or the type
464    * name of the SQL structured type being referenced by a <code>REF</code>
465    * type; ignored if the parameter is not a UDT or <code>REF</code> type
466    * @exception SQLException if a database access error occurs
467    */
468   void setNull (int paramIndex, int sqlType, String typeName)
469     throws SQLException;
470
471   /**
472    * Sets the designated parameter in this <code>RowSet</code> object's command
473    * to the given Java <code>boolean</code> value. The driver converts this to
474    * an SQL <code>BIT</code> value before sending it to the database.
475    *
476    * @param parameterIndex the first parameter is 1, the second is 2, ...
477    * @param x the parameter value
478    * @exception SQLException if a database access error occurs
479    */
480   void setBoolean(int parameterIndex, boolean x) throws SQLException;
481
482   /**
483    * Sets the designated parameter in this <code>RowSet</code> object's command
484    * to the given Java <code>byte</code> value. The driver converts this to
485    * an SQL <code>TINYINT</code> value before sending it to the database.
486    *
487    * @param parameterIndex the first parameter is 1, the second is 2, ...
488    * @param x the parameter value
489    * @exception SQLException if a database access error occurs
490    */
491   void setByte(int parameterIndex, byte x) throws SQLException;
492   
493   /**
494    * Sets the designated parameter in this <code>RowSet</code> object's command
495    * to the given Java <code>short</code> value. The driver converts this to
496    * an SQL <code>SMALLINT</code> value before sending it to the database.
497    *
498    * @param parameterIndex the first parameter is 1, the second is 2, ...
499    * @param x the parameter value
500    * @exception SQLException if a database access error occurs
501    */
502   void setShort(int parameterIndex, short x) throws SQLException;
503
504   /**
505    * Sets the designated parameter in this <code>RowSet</code> object's command
506    * to the given Java <code>int</code> value. The driver converts this to
507    * an SQL <code>INTEGER</code> value before sending it to the database.
508    *
509    * @param parameterIndex the first parameter is 1, the second is 2, ...
510    * @param x the parameter value
511    * @exception SQLException if a database access error occurs
512    */
513   void setInt(int parameterIndex, int x) throws SQLException;
514
515   /**
516    * Sets the designated parameter in this <code>RowSet</code> object's command
517    * to the given Java <code>long</code> value. The driver converts this to
518    * an SQL <code>BIGINT</code> value before sending it to the database.
519    *
520    * @param parameterIndex the first parameter is 1, the second is 2, ...
521    * @param x the parameter value
522    * @exception SQLException if a database access error occurs
523    */
524   void setLong(int parameterIndex, long x) throws SQLException;
525
526   /**
527    * Sets the designated parameter in this <code>RowSet</code> object's command
528    * to the given Java <code>float</code> value. The driver converts this to
529    * an SQL <code>REAL</code> value before sending it to the database.
530    *
531    * @param parameterIndex the first parameter is 1, the second is 2, ...
532    * @param x the parameter value
533    * @exception SQLException if a database access error occurs
534    */
535   void setFloat(int parameterIndex, float x) throws SQLException;
536
537   /**
538    * Sets the designated parameter in this <code>RowSet</code> object's command
539    * to the given Java <code>double</code> value. The driver converts this to
540    * an SQL <code>DOUBLE</code> value before sending it to the database.
541    *
542    * @param parameterIndex the first parameter is 1, the second is 2, ...
543    * @param x the parameter value
544    * @exception SQLException if a database access error occurs
545    */
546   void setDouble(int parameterIndex, double x) throws SQLException;
547   
548   /**
549    * Sets the designated parameter in this <code>RowSet</code> object's command
550    * to the given <code>java.math.BigDeciaml</code> value.
551    * The driver converts this to
552    * an SQL <code>NUMERIC</code> value before sending it to the database.
553    *
554    * @param parameterIndex the first parameter is 1, the second is 2, ...
555    * @param x the parameter value
556    * @exception SQLException if a database access error occurs
557    */
558   void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;
559
560   /**
561    * Sets the designated parameter in this <code>RowSet</code> object's command
562    * to the given Java <code>String</code> value. Before sending it to the
563    * database, the driver converts this to an SQL <code>VARCHAR</code> or
564    * <code>LONGVARCHAR</code> value, depending on the argument's size relative
565    * to the driver's limits on <code>VARCHAR</code> values.
566    *
567    * @param parameterIndex the first parameter is 1, the second is 2, ...
568    * @param x the parameter value
569    * @exception SQLException if a database access error occurs
570    */
571   void setString(int parameterIndex, String x) throws SQLException;
572
573   /**
574    * Sets the designated parameter in this <code>RowSet</code> object's command
575    * to the given Java array of <code>byte</code> values. Before sending it to the
576    * database, the driver converts this to an SQL <code>VARBINARY</code> or
577    * <code>LONGVARBINARY</code> value, depending on the argument's size relative
578    * to the driver's limits on <code>VARBINARY</code> values.
579    *
580    * @param parameterIndex the first parameter is 1, the second is 2, ...
581    * @param x the parameter value
582    * @exception SQLException if a database access error occurs
583    */
584   void setBytes(int parameterIndex, byte x[]) throws SQLException;
585
586   /**
587    * Sets the designated parameter in this <code>RowSet</code> object's command
588    * to the given <code>java.sql.Date</code> value. The driver converts this to
589    * an SQL <code>DATE</code> value before sending it to the database, using the
590    * default <code>java.util.Calendar</code> to calculate the date.
591    *
592    * @param parameterIndex the first parameter is 1, the second is 2, ...
593    * @param x the parameter value
594    * @exception SQLException if a database access error occurs
595    */
596   void setDate(int parameterIndex, java.sql.Date x) throws SQLException;
597
598   /**
599    * Sets the designated parameter in this <code>RowSet</code> object's command
600    * to the given <code>java.sql.Time</code> value. The driver converts this to
601    * an SQL <code>TIME</code> value before sending it to the database, using the
602    * default <code>java.util.Calendar</code> to calculate it.
603    *
604    * @param parameterIndex the first parameter is 1, the second is 2, ...
605    * @param x the parameter value
606    * @exception SQLException if a database access error occurs
607    */
608   void setTime(int parameterIndex, java.sql.Time x) throws SQLException;
609
610   /**
611    * Sets the designated parameter in this <code>RowSet</code> object's command
612    * to the given <code>java.sql.Timestamp</code> value. The driver converts this to
613    * an SQL <code>TIMESTAMP</code> value before sending it to the database, using the
614    * default <code>java.util.Calendar</code> to calculate it.
615    *
616    * @param parameterIndex the first parameter is 1, the second is 2, ...
617    * @param x the parameter value
618    * @exception SQLException if a database access error occurs
619    */
620   void setTimestamp(int parameterIndex, java.sql.Timestamp x)
621     throws SQLException;
622
623   /**
624    * Sets the designated parameter in this <code>RowSet</code> object's command
625    * to the given <code>java.io.InputStream</code> value.
626    * It may be more practical to send a very large ASCII value via a
627    * <code>java.io.InputStream</code> rather than as a <code>LONGVARCHAR</code>
628    * parameter. The driver will read the data from the stream
629    * as needed until it reaches end-of-file.
630    *
631    * <P><B>Note:</B> This stream object can either be a standard
632    * Java stream object or your own subclass that implements the
633    * standard interface.
634    *
635    * @param parameterIndex the first parameter is 1, the second is 2, ...
636    * @param x the Java input stream that contains the ASCII parameter value
637    * @param length the number of bytes in the stream
638    * @exception SQLException if a database access error occurs
639    */
640   void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)
641     throws SQLException;
642   
643   /**
644    * Sets the designated parameter in this <code>RowSet</code> object's command
645    * to the given <code>java.io.InputStream</code> value.
646    * It may be more practical to send a very large binary value via a
647    * <code>java.io.InputStream</code> rather than as a <code>LONGVARBINARY</code>
648    * parameter. The driver will read the data from the stream
649    * as needed until it reaches end-of-file.
650    *
651    * <P><B>Note:</B> This stream object can either be a standard
652    * Java stream object or your own subclass that implements the
653    * standard interface.
654    *
655    * @param parameterIndex the first parameter is 1, the second is 2, ...
656    * @param x the java input stream which contains the binary parameter value
657    * @param length the number of bytes in the stream
658    * @exception SQLException if a database access error occurs
659    */
660   void setBinaryStream(int parameterIndex, java.io.InputStream x,
661                int length) throws SQLException;
662
663   /**
664    * Sets the designated parameter in this <code>RowSet</code> object's command
665    * to the given <code>java.io.Reader</code> value.
666    * It may be more practical to send a very large UNICODE value via a
667    * <code>java.io.Reader</code> rather than as a <code>LONGVARCHAR</code>
668    * parameter. The driver will read the data from the stream
669    * as needed until it reaches end-of-file.
670    *
671    * <P><B>Note:</B> This stream object can either be a standard
672    * Java stream object or your own subclass that implements the
673    * standard interface.
674    *
675    * @param parameterIndex the first parameter is 1, the second is 2, ...
676    * @param reader the <code>Reader</code> object that contains the UNICODE data
677    * to be set
678    * @param length the number of characters in the stream
679    * @exception SQLException if a database access error occurs
680    */
681   void setCharacterStream(int parameterIndex,
682                   Reader reader,
683               int length) throws SQLException;
684   
685   /**
686    * Sets the designated parameter in this <code>RowSet</code> object's command
687    * with the given Java <code>Object</code>. For integral values, the
688    * <code>java.lang</code> equivalent objects should be used (for example,
689    * an instance of the class <code>Integer</code> for an <code>int</code>).
690    *
691    * <p>The given Java object will be converted to the targetSqlType
692    * before being sent to the database.
693    * <P>
694    * If the object is of a class implementing <code>SQLData</code>,
695    * the rowset should call the method <code>SQLData.writeSQL</code>
696    * to write the object to an <code>SQLOutput</code> data stream.
697    * If the object is an instance of a class implementing the <code>Ref</code>,
698    * <code>Struct</code>, <code>Array</code>, <code>Blob</code>,
699    * or <code>Clob</code> interfaces,
700    * the driver uses the default mapping to the corresponding SQL type.
701    *
702    * <p>Note that this method may be used to pass datatabase-specific
703    * abstract data types.
704    *
705    * @param parameterIndex the first parameter is 1, the second is 2, ...
706    * @param x the object containing the input parameter value
707    * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
708    * to be sent to the database. The scale argument may further qualify this
709    * type.
710    * @param scale for <code>java.sql.Types.DECIMAL</code> or
711    * <code>java.sql.Types.NUMERIC</code> types, this is the number of
712    * digits after the decimal point. For all other types, this value
713    * will be ignored.
714    * @exception SQLException if a database access error occurs
715    * @see java.sql.Types
716    */
717   void setObject(int parameterIndex, Object x, int targetSqlType, int scale)
718             throws SQLException;
719
720   /**
721    * Sets the designated parameter in this <code>RowSet</code> object's command
722    * with a Java <code>Object</code>. For integral values, the
723    * <code>java.lang</code> equivalent objects should be used.
724    * This method is like <code>setObject</code> above, but the scale used is the scale
725    * of the second parameter. Scalar values have a scale of zero. Literal
726    * values have the scale present in the literal.
727    * <P>
728    * Even though it is supported, it is not recommended that this method
729    * be called with floating point input values.
730    *
731    * @param parameterIndex the first parameter is 1, the second is 2, ...
732    * @param x the object containing the input parameter value
733    * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
734    * to be sent to the database
735    * @exception SQLException if a database access error occurs
736    */
737   void setObject(int parameterIndex, Object x,
738          int targetSqlType) throws SQLException;
739   
740   /**
741    * Sets the designated parameter in this <code>RowSet</code> object's command
742    * with a Java <code>Object</code>. For integral values, the
743    * <code>java.lang</code> equivalent objects should be used.
744    *
745    * <p>The JDBC specification provides a standard mapping from
746    * Java Object types to SQL types. The driver will convert the
747    * given Java object to its standard SQL mapping before sending it
748    * to the database.
749    *
750    * <p>Note that this method may be used to pass datatabase-specific
751    * abstract data types by using a driver-specific Java type.
752    *
753    * If the object is of a class implementing <code>SQLData</code>,
754    * the rowset should call the method <code>SQLData.writeSQL</code>
755    * to write the object to an <code>SQLOutput</code> data stream.
756    * If the object is an instance of a class implementing the <code>Ref</code>,
757    * <code>Struct</code>, <code>Array</code>, <code>Blob</code>,
758    * or <code>Clob</code> interfaces,
759    * the driver uses the default mapping to the corresponding SQL type.
760    * <P>
761    * An exception is thrown if there is an ambiguity, for example, if the
762    * object is of a class implementing more than one of these interfaces.
763    *
764    * @param parameterIndex The first parameter is 1, the second is 2, ...
765    * @param x The object containing the input parameter value
766    * @exception SQLException if a database access error occurs
767    */
768   void setObject(int parameterIndex, Object x) throws SQLException;
769
770   /**
771    * Sets the designated parameter in this <code>RowSet</code> object's command
772    * with the given <code>Ref</code> value. The driver will convert this
773    * to the appropriate <code>REF(&lt;structured-type&gt;)</code> value.
774    *
775    * @param i the first parameter is 1, the second is 2, ...
776    * @param x an object representing data of an SQL <code>REF</code> type
777    * @exception SQLException if a database access error occurs
778    */
779   void setRef (int i, Ref x) throws SQLException;
780
781   /**
782    * Sets the designated parameter in this <code>RowSet</code> object's command
783    * with the given <code>Blob</code> value. The driver will convert this
784    * to the <code>BLOB</code> value that the <code>Blob</code> object
785    * represents before sending it to the database.
786    *
787    * @param i the first parameter is 1, the second is 2, ...
788    * @param x an object representing a BLOB
789    * @exception SQLException if a database access error occurs
790    */
791   void setBlob (int i, Blob x) throws SQLException;
792
793   /**
794    * Sets the designated parameter in this <code>RowSet</code> object's command
795    * with the given <code>Clob</code> value. The driver will convert this
796    * to the <code>CLOB</code> value that the <code>Clob</code> object
797    * represents before sending it to the database.
798    *
799    * @param i the first parameter is 1, the second is 2, ...
800    * @param x an object representing a CLOB
801    * @exception SQLException if a database access error occurs
802    */
803   void setClob (int i, Clob x) throws SQLException;
804   
805   /**
806    * Sets the designated parameter in this <code>RowSet</code> object's command
807    * with the given <code>Array</code> value. The driver will convert this
808    * to the <code>ARRAY</code> value that the <code>Array</code> object
809    * represents before sending it to the database.
810    *
811    * @param i the first parameter is 1, the second is 2, ...
812    * @param x an object representing an SQL array
813    * @exception SQLException if a database access error occurs
814    */
815   void setArray (int i, Array x) throws SQLException;
816
817   /**
818    * Sets the designated parameter in this <code>RowSet</code> object's command
819    * with the given <code>java.sql.Date</code> value. The driver will convert this
820    * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code>
821    * object to calculate the date.
822    *
823    * @param parameterIndex the first parameter is 1, the second is 2, ...
824    * @param x the parameter value
825    * @param cal the <code>java.util.Calendar</code> object to use for calculating the date
826    * @exception SQLException if a database access error occurs
827    */
828   void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
829     throws SQLException;
830
831   /**
832    * Sets the designated parameter in this <code>RowSet</code> object's command
833    * with the given <code>java.sql.Time</code> value. The driver will convert this
834    * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code>
835    * object to calculate it, before sending it to the database.
836    *
837    * @param parameterIndex the first parameter is 1, the second is 2, ...
838    * @param x the parameter value
839    * @param cal the <code>java.util.Calendar</code> object to use for calculating the time
840    * @exception SQLException if a database access error occurs
841    */
842   void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
843     throws SQLException;
844
845   /**
846    * Sets the designated parameter in this <code>RowSet</code> object's command
847    * with the given <code>java.sql.Timestamp</code> value. The driver will
848    * convert this to an SQL <code>TIMESTAMP</code> value, using the given
849    * <code>java.util.Calendar</code> object to calculate it, before sending it to the
850    * database.
851    *
852    * @param parameterIndex the first parameter is 1, the second is 2, ...
853    * @param x the parameter value
854    * @param cal the <code>java.util.Calendar</code> object to use for calculating the
855    * timestamp
856    * @exception SQLException if a database access error occurs
857    */
858   void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)
859     throws SQLException;
860
861   /**
862    * Clears the parameters set for this <code>RowSet</code> object's command.
863    * <P>In general, parameter values remain in force for repeated use of a
864    * <code>RowSet</code> object. Setting a parameter value automatically clears its
865    * previous value. However, in some cases it is useful to immediately
866    * release the resources used by the current parameter values, which can
867    * be done by calling the method <code>clearParameters</code>.
868    *
869    * @exception SQLException if a database access error occurs
870    */
871   void clearParameters() throws SQLException;
872
873   //---------------------------------------------------------------------
874 // Reading and writing data
875 //---------------------------------------------------------------------
876
877   /**
878    * Fills this <code>RowSet</code> object with data.
879    * <P>
880    * The <code>execute</code> method may use the following properties
881    * to create a connection for reading data: url, data source name,
882    * user name, password, transaction isolation, and type map.
883    *
884    * The <code>execute</code> method may use the following properties
885    * to create a statement to execute a command:
886    * command, read only, maximum field size,
887    * maximum rows, escape processing, and query timeout.
888    * <P>
889    * If the required properties have not been set, an exception is
890    * thrown. If this method is successful, the current contents of the rowset are
891    * discarded and the rowset's metadata is also (re)set. If there are
892    * outstanding updates, they are ignored.
893    * <P>
894    * If this <code>RowSet</code> object does not maintain a continuous connection
895    * with its source of data, it may use a reader (a <code>RowSetReader</code>
896    * object) to fill itself with data. In this case, a reader will have been
897    * registered with this <code>RowSet</code> object, and the method
898    * <code>execute</code> will call on the reader's <code>readData</code>
899    * method as part of its implementation.
900    *
901    * @exception SQLException if a database access error occurs or any of the
902    * properties necessary for making a connection and creating
903    * a statement have not been set
904    */
905   void execute() throws SQLException;
906
907   //--------------------------------------------------------------------
908 // Events
909 //--------------------------------------------------------------------
910
911   /**
912    * Registers the given listener so that it will be notified of events
913    * that occur on this <code>RowSet</code> object.
914    *
915    * @param listener a component that has implemented the <code>RowSetListener</code>
916    * interface and wants to be notified when events occur on this
917    * <code>RowSet</code> object
918    * @see #removeRowSetListener
919    */
920   void addRowSetListener(RowSetListener listener);
921
922   /**
923    * Removes the specified listener from the list of components that will be
924    * notified when an event occurs on this <code>RowSet</code> object.
925    *
926    * @param listener a component that has been registered as a listener for this
927    * <code>RowSet</code> object
928    * @see #addRowSetListener
929    */
930   void removeRowSetListener(RowSetListener listener);
931  
932 }
933
934
935
936
937
938
939
940
941
942

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags