KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sql > rowset > BaseRowSet


1 /*
2  * @(#)BaseRowSet.java 1.11 04/07/20
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.rowset;
9
10 import java.sql.*;
11 import javax.sql.*;
12 import java.util.*;
13 import java.io.*;
14 import java.io.Serializable JavaDoc;
15
16 import javax.sql.rowset.serial.*;
17
18 /**
19  * An abstract class providing a <code>RowSet</code> object with its basic functionality.
20  * The basic functions include having properties and sending event notifications,
21  * which all JavaBeans<sup><font size=-2>TM</font></sup> components must implement.
22  * <P>
23  * <h3>1.0 Overview</h3>
24  * The <code>BaseRowSet</code> class provides the core functionality
25  * for all <code>RowSet</code> implementations,
26  * and all standard implementations <b>may</b> use this class in combination with
27  * one or more <code>RowSet</code> interfaces in order to provide a standard
28  * vendor-specific implementation. To clarify, all implementations must implement
29  * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,
30  * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,
31  * or <code>WebRowSet</code>). This means that any implementation that extends
32  * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>
33  * interfaces.
34  * <p>
35  * The <code>BaseRowSet</code> class provides the following:
36  * <p>
37  * <UL>
38  * <LI><b>Properties</b>
39  * <ul>
40  * <li>Fields for storing current properties
41  * <li>Methods for getting and setting properties
42  * </ul>
43  * <p>
44  * <LI><b>Event notification</b>
45  * <P>
46  * <LI><b>A complete set of setter methods</b> for setting the parameters in a
47  * <code>RowSet</code> object's command
48  * <p>
49  * <LI> <b>Streams</b>
50  * <ul>
51  * <li>Fields for storing stream instances
52  * <li>Constants for indicating the type of a stream
53  * </ul>
54  * <p>
55  * </UL>
56  *
57  * <h3>2.0 Setting Properties</h3>
58  * All rowsets maintain a set of properties, which will usually be set using
59  * a tool. The number and kinds of properties a rowset has will vary,
60  * depending on what the <code>RowSet</code> implementation does and how it gets
61  * its data. For example,
62  * rowsets that get their data from a <code>ResultSet</code> object need to
63  * set the properties that are required for making a database connection.
64  * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a
65  * connection, it needs to set a property for the JDBC URL that identifies the
66  * appropriate driver, and it needs to set the properties that give the
67  * user name and password.
68  * If, on the other hand, the rowset uses a <code>DataSource</code> object
69  * to make the connection, which is the preferred method, it does not need to
70  * set the property for the JDBC URL. Instead, it needs to set the property
71  * for the logical name of the data source along with the properties for
72  * the user name and password.
73  * <P>
74  * NOTE: In order to use a <code>DataSource</code> object for making a
75  * connection, the <code>DataSource</code> object must have been registered
76  * with a naming service that uses the Java Naming and Directory
77  * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
78  * is usually done by a person acting in the capacity of a system administrator.
79  * <P>
80  * <h3>3.0 Setting the Command and Its Parameters</h3>
81  * When a rowset gets its data from a relational database, it executes a command (a query)
82  * that produces a <code>ResultSet</code> object. This query is the command that is set
83  * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
84  * data from the <code>ResultSet</code> object into itself. If the query
85  * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
86  * are used to set these values. All setter methods allow these values to be set
87  * to <code>null</code> if required.
88  * <P>
89  * The following code fragment illustrates how the
90  * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
91  * object <code>crs</code> might have its command property set. Note that if a
92  * tool is used to set properties, this is the code that the tool would use.
93  * <PRE>
94  * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
95  * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
96  * </PRE>
97  * <P>
98  * In this example, the values for <code>CREDIT_LIMIT</code> and
99  * <code>REGION</code> are placeholder parameters, which are indicated with a
100  * question mark (?). The first question mark is placeholder parameter number
101  * <code>1</code>, the second question mark is placeholder parameter number
102  * <code>2</code>, and so on. Any placeholder parameters must be set with
103  * values before the query can be executed. To set these
104  * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
105  * methods, similar to those provided by the <code>PreparedStatement</code>
106  * interface, for setting values of each data type. A <code>RowSet</code> object stores the
107  * parameter values internally, and its <code>execute</code> method uses them internally
108  * to set values for the placeholder parameters
109  * before it sends the command to the DBMS to be executed.
110  * <P>
111  * The following code fragment demonstrates
112  * setting the two parameters in the query from the previous example.
113  * <PRE>
114  * crs.setInt(1, 5000);
115  * crs.setString(2, "West");
116  * </PRE>
117  * If the <code>execute</code> method is called at this point, the query
118  * sent to the DBMS will be:
119  * <PRE>
120  * "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
121  * "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
122  * </PRE>
123  * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and
124  * <code>Ref</code> objects as a command parameter, stores these values as
125  * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>
126  * and <code>SerialRef</code> objects respectively.
127  *
128  * <h3>4.0 Handling of Parameters Behind the Scenes</h3>
129  *
130  * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,
131  * those that set properties and those that set placeholder parameters. The setter
132  * methods discussed in this section are those that set placeholder parameters.
133  * <P>
134  * The placeholder parameters set with the <code>BaseRowSet</code> setter methods
135  * are stored as objects in an internal <code>Hashtable</code> object.
136  * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>
137  * is stored as <code>Byte</code> object, and <code>int</code> is stored as
138  * an <code>Integer</code> object.
139  * When the method <code>execute</code> is called, the values in the
140  * <code>Hashtable</code> object are substituted for the appropriate placeholder
141  * parameters in the command.
142  * <P)>
143  * A call to the method <code>getParams</code> returns the values stored in the
144  * <code>Hashtable</code> object as an array of <code>Object</code> instances.
145  * An element in this array may be a simple <code>Object</code> instance or an
146  * array (which is a type of <code>Object</code>). The particular setter method used
147  * determines whether an element in this array is an <code>Object</code> or an array.
148  * <P>
149  * The majority of methods for setting placeholder parameters take two parameters,
150  * with the first parameter
151  * indicating which placeholder parameter is to be set, and the second parameter
152  * giving the value to be set. Methods such as <code>getInt</code>,
153  * <code>getString</code>, <code>getBoolean</code>, and <code>getLong</code> fall into
154  * this category. After these methods have been called, a call to the method
155  * <code>getParams</code> will return an array with the values that have been set. Each
156  * element in the array is an <code>Object</code> instance representing the
157  * values that have been set. The order of these values in the array is determined by the
158  * <code>int</code> (the first parameter) passed to the setter method. The values in the
159  * array are the values (the second parameter) passed to the setter method.
160  * In other words, the first element in the array is the value
161  * to be set for the first placeholder parameter in the <code>RowSet</code> object's
162  * command. The second element is the value to
163  * be set for the second placeholder parameter, and so on.
164  * <P>
165  * Several setter methods send the driver and DBMS information beyond the value to be set.
166  * When the method <code>getParams</code> is called after one of these setter methods has
167  * been used, the elements in the array will themselves be arrays to accommodate the
168  * additional information. In this category, the method <code>setNull</code> is a special case
169  * because one version takes only
170  * two parameters (<code>setNull(int parameterIndex, int SqlType)</code>). Nevertheless,
171  * it requires
172  * an array to contain the information that will be passed to the driver and DBMS. The first
173  * element in this array is the value to be set, which is <code>null</code>, and the
174  * second element is the <code>int</code> supplied for <i>sqlType</i>, which
175  * indicates the type of SQL value that is being set to <code>null</code>. This information
176  * is needed by some DBMSs and is therefore required in order to ensure that applications
177  * are portable.
178  * The other version is intended to be used when the value to be set to <code>null</code>
179  * is a user-defined type. It takes three parameters
180  * (<code>setNull(int parameterIndex, int sqlType, String typeName)</code>) and also
181  * requires an array to contain the information to be passed to the driver and DBMS.
182  * The first two elements in this array are the same as for the first version of
183  * <code>setNull</code>. The third element, <i>typeName</i>, gives the SQL name of
184  * the user-defined type. As is true with the other setter methods, the number of the
185  * placeholder parameter to be set is indicated by an element's position in the array
186  * returned by <code>getParams</code>. So, for example, if the parameter
187  * supplied to <code>setNull</code> is <code>2</code>, the second element in the array
188  * returned by <code>getParams</code> will be an array of two or three elements.
189  * <P>
190  * Some methods, such as <code>setObject</code> and <code>setDate</code> have versions
191  * that take more than two parameters, with the extra parameters giving information
192  * to the driver or the DBMS. For example, the methods <code>setDate</code>,
193  * <code>setTime</code>, and <code>setTimestamp</code> can take a <code>Calendar</code>
194  * object as their third parameter. If the DBMS does not store time zone information,
195  * the drivern uses the <code>Calendar</code> object to construct the <code>Date</code>,
196  * <code>Time</code>, or <code>Timestamp</code> object being set. As is true with other
197  * methods that provide additional information, the element in the array returned
198  * by <code>getParams</code> is an array instead of a simple <code>Object</code> instance.
199  * <P>
200  * The methods <code>setAsciiStream</code>, <code>setBinaryStream</code>,
201  * <code>setCharacterStream</code>, and <code>setUnicodeStream</code> (which is
202  * deprecated, so applications should use <code>getCharacterStream</code> instead)
203  * take three parameters, so for them, the element in the array returned by
204  * <code>getParams</code> is also an array. What is different about these setter
205  * methods is that in addition to the information provided by parameters, the array contains
206  * one of the <code>BaseRowSet</code> constants indicating the type of stream being set.
207 * <p>
208 * NOTE: The method <code>getParams</code> is called internally by
209 * <code>RowSet</code> implementations extending this class; it is not normally called by an
210 * application programmer directly.
211 *
212 * <h3>5.0 Event Notification</h3>
213 * The <code>BaseRowSet</code> class provides the event notification
214 * mechanism for rowsets. It contains the field
215 * <code>listeners</code>, methods for adding and removing listeners, and
216 * methods for notifying listeners of changes.
217 * <P>
218 * A listener is an object that has implemented the <code>RowSetListener</code> interface.
219 * If it has been added to a <code>RowSet</code> object's list of listeners, it will be notified
220 * when an event occurs on that <code>RowSet</code> object. Each listener's
221 * implementation of the <code>RowSetListener</code> methods defines what that object
222 * will do when it is notified that an event has occurred.
223 * <P>
224 * There are three possible events for a <code>RowSet</code> object:
225 * <OL>
226 * <LI>the cursor moves
227 * <LI>an individual row is changed (updated, deleted, or inserted)
228 * <LI>the contents of the entire <code>RowSet</code> object are changed
229 * </OL>
230 * <P>
231 * The <code>BaseRowSet</code> method used for the notification indicates the
232 * type of event that has occurred. For example, the method
233 * <code>notifyRowChanged</code> indicates that a row has been updated,
234 * deleted, or inserted. Each of the notification methods creates a
235 * <code>RowSetEvent</code> object, which is supplied to the listener in order to
236 * identify the <code>RowSet</code> object on which the event occurred.
237 * What the listener does with this information, which may be nothing, depends on how it was
238 * implemented.
239 * <p>
240 * <h3>6.0 Default Behavior</h3>
241 * A default <code>BaseRowSet</code> object is initialized with many starting values.
242 *
243 * The following is true of a default <code>RowSet</code> instance that extends
244 * the <code>BaseRowSet</code> class:
245 * <UL>
246 * <LI>Has a scrollable cursor and does not show changes
247 * made by others.
248 * <LI>Is updatable.
249 * <LI>Does not show rows that have been deleted.
250 * <LI>Has no time limit for how long a driver may take to
251 * execute the <code>RowSet</code> object's command.
252 * <LI>Has no limit for the number of rows it may contain.
253 * <LI>Has no limit for the number of bytes a column may contain. NOTE: This
254 * limit applies only to columns that hold values of the
255 * following types: <code>BINARY</code>, <code>VARBINARY</code>,
256 * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
257 * and <code>LONGVARCHAR</code>.
258 * <LI>Will not see uncommitted data (make "dirty" reads).
259 * <LI>Has escape processing turned on.
260 * <LI>Has its connection's type map set to <code>null</code>.
261 * <LI>Has an empty <code>Vector</code> object for storing the values set
262 * for the placeholder parameters in the <code>RowSet</code> object's command.
263 * </UL>
264 * <p>
265 * If other values are desired, an application must set the property values
266 * explicitly. For example, the following line of code sets the maximum number
267 * of rows for the <code>CachedRowSet</code> object <i>crs</i> to 500.
268 * <PRE>
269 * crs.setMaxRows(500);
270 * </PRE>
271 * Methods implemented in extensions of this <code>BaseRowSet</code> class <b>must</b> throw an
272 * <code>SQLException</code> object for any violation of the defined assertions. Also, if the
273 * extending class overrides and reimplements any <code>BaseRowSet</code> method and encounters
274 * connectivity or underlying data source issues, that method <b>may</b> in addition throw an
275 * <code>SQLException</code> object for that reason.
276 */

277
278 public abstract class BaseRowSet implements Serializable JavaDoc, Cloneable JavaDoc {
279
280 /**
281  * A constant indicating to a <code>RowSetReaderImpl</code> object
282  * that a given parameter is a Unicode stream. This
283  * <code>RowSetReaderImpl</code> object is provided as an extension of the
284  * <code>SyncProvider</code> abstract class defined in the
285  * <code>SyncFactory</code> static factory SPI mechanism.
286  */

287 public static final int UNICODE_STREAM_PARAM = 0;
288
289 /**
290  * A constant indicating to a <code>RowSetReaderImpl</code> object
291  * that a given parameter is a binary stream. A
292  * <code>RowSetReaderImpl</code> object is provided as an extension of the
293  * <code>SyncProvider</code> abstract class defined in the
294  * <code>SyncFactory</code> static factory SPI mechanism.
295  */

296 public static final int BINARY_STREAM_PARAM = 1;
297
298 /**
299  * A constant indicating to a <code>RowSetReaderImpl</code> object
300  * that a given parameter is an ASCII stream. A
301  * <code>RowSetReaderImpl</code> object is provided as an extension of the
302  * <code>SyncProvider</code> abstract class defined in the
303  * <code>SyncFactory</code> static factory SPI mechanism.
304  */

305 public static final int ASCII_STREAM_PARAM = 2;
306
307     /**
308      * The <code>InputStream</code> object that will be
309      * returned by the method <code>getBinaryStream</code>, which is
310      * specified in the <code>ResultSet</code> interface.
311      * @serial
312      */

313     protected java.io.InputStream JavaDoc binaryStream;
314
315     /**
316      * The <code>InputStream</code> object that will be
317      * returned by the method <code>getUnicodeStream</code>,
318      * which is specified in the <code>ResultSet</code> interface.
319      * @serial
320      */

321     protected java.io.InputStream JavaDoc unicodeStream;
322
323     /**
324      * The <code>InputStream</code> object that will be
325      * returned by the method <code>getAsciiStream</code>,
326      * which is specified in the <code>ResultSet</code> interface.
327      * @serial
328      */

329     protected java.io.InputStream JavaDoc asciiStream;
330
331     /**
332      * The <code>Reader</code> object that will be
333      * returned by the method <code>getCharacterStream</code>,
334      * which is specified in the <code>ResultSet</code> interface.
335      * @serial
336      */

337     protected java.io.Reader JavaDoc charStream;
338     
339     /**
340      * The query that will be sent to the DBMS for execution when the
341      * method <code>execute</code> is called.
342      * @serial
343      */

344     private String JavaDoc command;
345     
346     /**
347      * The JDBC URL the reader, writer, or both supply to the method
348      * <code>DriverManager.getConnection</code> when the
349      * <code>DriverManager</code> is used to get a connection.
350      * <P>
351      * The JDBC URL identifies the driver to be used to make the conndection.
352      * This URL can be found in the documentation supplied by the driver
353      * vendor.
354      * @serial
355      */

356     private String JavaDoc URL;
357
358     /**
359      * The logical name of the data source that the reader/writer should use
360      * in order to retrieve a <code>DataSource</code> object from a Java
361      * Directory and Naming Interface (JNDI) naming service.
362      * @serial
363      */

364     private String JavaDoc dataSource;
365     
366     /**
367      * The user name the reader, writer, or both supply to the method
368      * <code>DriverManager.getConnection</code> when the
369      * <code>DriverManager</code> is used to get a connection.
370      * @serial
371      */

372     private transient String JavaDoc username;
373
374     /**
375      * The password the reader, writer, or both supply to the method
376      * <code>DriverManager.getConnection</code> when the
377      * <code>DriverManager</code> is used to get a connection.
378      * @serial
379      */

380     private transient String JavaDoc password;
381
382     /**
383      * A constant indicating the type of this JDBC <code>RowSet</code>
384      * object. It must be one of the following <code>ResultSet</code>
385      * constants: <code>TYPE_FORWARD_ONLY</code>,
386      * <code>TYPE_SCROLL_INSENSITIVE</code>, or
387      * <code>TYPE_SCROLL_SENSITIVE</code>.
388      * @serial
389      */

390     private int rowSetType = ResultSet.TYPE_SCROLL_INSENSITIVE;
391
392     /**
393      * A <code>boolean</code> indicating whether deleted rows are visible in this
394      * JDBC <code>RowSet</code> object .
395      * @serial
396      */

397     private boolean showDeleted = false; // default is false
398

399     /**
400      * The maximum number of seconds the driver
401      * will wait for a command to execute. This limit applies while
402      * this JDBC <code>RowSet</code> object is connected to its data
403      * source, that is, while it is populating itself with
404      * data and while it is writing data back to the data source.
405      * @serial
406      */

407     private int queryTimeout = 0; // default is no timeout
408

409     /**
410      * The maximum number of rows the reader should read.
411      * @serial
412      */

413     private int maxRows = 0; // default is no limit
414

415     /**
416      * The maximum field size the reader should read.
417      * @serial
418      */

419     private int maxFieldSize = 0; // default is no limit
420

421     /**
422      * A constant indicating the concurrency of this JDBC <code>RowSet</code>
423      * object. It must be one of the following <code>ResultSet</code>
424      * constants: <code>CONCUR_READ_ONLY</code> or
425      * <code>CONCUR_UPDATABLE</code>.
426      * @serial
427      */

428     private int concurrency = ResultSet.CONCUR_UPDATABLE;
429
430     /**
431      * A <code>boolean</code> indicating whether this JDBC <code>RowSet</code>
432      * object is read-only. <code>true</code> indicates that it is read-only;
433      * <code>false</code> that it is writable.
434      * @serial
435      */

436     private boolean readOnly;
437
438     /**
439      * A <code>boolean</code> indicating whether the reader for this
440      * JDBC <code>RowSet</code> object should perform escape processing.
441      * <code>true</code> means that escape processing is turned on;
442      * <code>false</code> that it is not. The default is <code>true</code>.
443      * @serial
444      */

445     private boolean escapeProcessing;
446
447     /**
448      * A constant indicating the isolation level of the connection
449      * for this JDBC <code>RowSet</code> object . It must be one of
450      * the following <code>Connection</code> constants:
451      * <code>TRANSACTION_NONE</code>,
452      * <code>TRANSACTION_READ_UNCOMMITTED</code>,
453      * <code>TRANSACTION_READ_COMMITTED</code>,
454      * <code>TRANSACTION_REPEATABLE_READ</code> or
455      * <code>TRANSACTION_SERIALIZABLE</code>.
456      * @serial
457      */

458     private int isolation;
459
460     /**
461      * A constant used as a hint to the driver that indicates the direction in
462      * which data from this JDBC <code>RowSet</code> object is going
463      * to be fetched. The following <code>ResultSet</code> constants are
464      * possible values:
465      * <code>FETCH_FORWARD</code>,
466      * <code>FETCH_REVERSE</code>,
467      * <code>FETCH_UNKNOWN</code>.
468      * <P>
469      * Unused at this time.
470      * @serial
471      */

472     private int fetchDir = ResultSet.FETCH_FORWARD; // default fetch direction
473

474     /**
475      * A hint to the driver that indicates the expected number of rows
476      * in this JDBC <code>RowSet</code> object .
477      * <P>
478      * Unused at this time.
479      * @serial
480      */

481     private int fetchSize = 0; // default fetchSize
482

483     /**
484      * The <code>java.util.Map</code> object that contains entries mapping
485      * SQL type names to classes in the Java programming language for the
486      * custom mapping of user-defined types.
487      * @serial
488      */

489     private Map map;
490
491     /**
492      * A <code>Vector</code> object that holds the list of listeners
493      * that have registered with this <code>RowSet</code> object.
494      * @serial
495      */

496     private Vector listeners;
497
498     /**
499      * A <code>Vector</code> object that holds the parameters set
500      * for this <code>RowSet</code> object's current command.
501      * @serial
502      */

503     private Hashtable params; // could be transient?
504

505     /**
506      * Constructs a new <code>BaseRowSet</code> object initialized with
507      * a default <code>Vector</code> object for its <code>listeners</code>
508      * field. The other default values with which it is initialized are listed
509      * in Section 6.0 of the class comment for this class.
510      */

511     public BaseRowSet() {
512     // allocate the listeners collection
513
listeners = new Vector();
514     }
515  
516     /**
517      * Performs the necessary internal configurations and initializations
518      * to allow any JDBC <code>RowSet</code> implementation to start using
519      * the standard facilities provided by a <code>BaseRowSet</code>
520      * instance. This method <b>should</b> be called after the <code>RowSet</code> object
521      * has been instantiated to correctly initialize all parameters. This method
522      * <b>should</b> never be called by an application, but is called from with
523      * a <code>RowSet</code> implementation extending this class.
524      */

525     protected void initParams() {
526         params = new Hashtable();
527     }
528
529     //--------------------------------------------------------------------
530
// Events
531
//--------------------------------------------------------------------
532

533     /**
534     * The listener will be notified whenever an event occurs on this <code>RowSet</code>
535     * object.
536     * <P>
537     * A listener might, for example, be a table or graph that needs to
538     * be updated in order to accurately reflect the current state of
539     * the <code>RowSet</code> object.
540     * <p>
541     * <b>Note</b>: if the <code>RowSetListener</code> object is
542     * <code>null</code>, this method silently discards the <code>null</code>
543     * value and does not add a null reference to the set of listeners.
544     * <p>
545     * <b>Note</b>: if the listener is already set, and the new <code>RowSetListerner</code>
546     * instance is added to the set of listeners already registered to receive
547     * event notifications from this <code>RowSet</code>.
548     *
549     * @param listener an object that has implemented the
550     * <code>javax.sql.RowSetListener</code> interface and wants to be notified
551     * of any events that occur on this <code>RowSet</code> object; May be
552     * null.
553     * @see #removeRowSetListener
554     */

555     public void addRowSetListener(RowSetListener listener) {
556     listeners.add(listener);
557     }
558
559     /**
560     * Removes the designated object from this <code>RowSet</code> object's list of listeners.
561     * If the given argument is not a registered listener, this method
562     * does nothing.
563     *
564     * <b>Note</b>: if the <code>RowSetListener</code> object is
565     * <code>null</code>, this method silently discards the <code>null</code>
566     * value.
567     *
568     * @param listener a <code>RowSetListener</code> object that is on the list
569     * of listeners for this <code>RowSet</code> object
570     * @see #addRowSetListener
571     */

572     public void removeRowSetListener(RowSetListener listener) {
573     listeners.remove(listener);
574     }
575     
576     /**
577      * Determine if instance of this class extends the RowSet interface.
578      */

579     private void checkforRowSetInterface() throws SQLException {
580         if ((this instanceof javax.sql.RowSet JavaDoc) == false) {
581             throw new SQLException("The class extending abstract class BaseRowSet " +
582                 "must implement javax.sql.RowSet or one of it's sub-interfaces.");
583         }
584     }
585
586     /**
587     * Notifies all of the listeners registered with this
588     * <code>RowSet</code> object that its cursor has moved.
589     * <P>
590     * When an application calls a method to move the cursor,
591     * that method moves the cursor and then calls this method
592     * internally. An application <b>should</b> never invoke
593     * this method directly.
594     *
595     * @throws SQLException if the class extending the <code>BaseRowSet</code>
596     * abstract class does not implement the <code>RowSet</code> interface or
597     * one of it's sub-interfaces.
598     */

599     protected void notifyCursorMoved() throws SQLException {
600         checkforRowSetInterface();
601     if (listeners.isEmpty() == false) {
602             RowSetEvent event = new RowSetEvent((RowSet)this);
603             for (Iterator i = listeners.iterator(); i.hasNext(); ) {
604                 ((RowSetListener)i.next()).cursorMoved(event);
605             }
606     }
607     }
608
609     /**
610     * Notifies all of the listeners registered with this <code>RowSet</code> object that
611     * one of its rows has changed.
612     * <P>
613     * When an application calls a method that changes a row, such as
614     * the <code>CachedRowSet</code> methods <code>insertRow</code>,
615     * <code>updateRow</code>, or <code>deleteRow</code>,
616     * that method calls <code>notifyRowChanged</code>
617     * internally. An application <b>should</b> never invoke
618     * this method directly.
619     *
620     * @throws SQLException if the class extending the <code>BaseRowSet</code>
621     * abstract class does not implement the <code>RowSet</code> interface or
622     * one of it's sub-interfaces.
623     */

624     protected void notifyRowChanged() throws SQLException {
625         checkforRowSetInterface();
626     if (listeners.isEmpty() == false) {
627         RowSetEvent event = new RowSetEvent((RowSet)this);
628         for (Iterator i = listeners.iterator(); i.hasNext(); ) {
629             ((RowSetListener)i.next()).rowChanged(event);
630         }
631     }
632     }
633
634    /**
635     * Notifies all of the listeners registered with this <code>RowSet</code>
636     * object that its entire contents have changed.
637     * <P>
638     * When an application calls methods that change the entire contents
639     * of the <code>RowSet</code> object, such as the <code>CachedRowSet</code> methods
640     * <code>execute</code>, <code>populate</code>, <code>restoreOriginal</code>,
641     * or <code>release</code>, that method calls <code>notifyRowSetChanged</code>
642     * internally (either directly or indirectly). An application <b>should</b>
643     * never invoke this method directly.
644     *
645     * @throws SQLException if the class extending the <code>BaseRowSet</code>
646     * abstract class does not implement the <code>RowSet</code> interface or
647     * one of it's sub-interfaces.
648     */

649     protected void notifyRowSetChanged() throws SQLException {
650         checkforRowSetInterface();
651     if (listeners.isEmpty() == false) {
652         RowSetEvent event = new RowSetEvent((RowSet)this);
653         for (Iterator i = listeners.iterator(); i.hasNext(); ) {
654             ((RowSetListener)i.next()).rowSetChanged(event);
655         }
656     }
657 }
658
659     /**
660      * Retrieves the SQL query that is the command for this
661      * <code>RowSet</code> object. The command property contains the query that
662      * will be executed to populate this <code>RowSet</code> object.
663      * <P>
664      * The SQL query returned by this method is used by <code>RowSet</code> methods
665      * such as <code>execute</code> and <code>populate</code>, which may be implemented
666      * by any class that extends the <code>BaseRowSet</code> abstract class and
667      * implements one or more of the standard JSR-114 <code>RowSet</code>
668      * interfaces.
669      * <P>
670      * The command is used by the <code>RowSet</code> object's
671      * reader to obtain a <code>ResultSet</code> object. The reader then
672      * reads the data from the <code>ResultSet</code> object and uses it to
673      * to populate this <code>RowSet</code> object.
674      * <P>
675      * The default value for the <code>command</code> property is <code>null</code>.
676      *
677      * @return the <code>String</code> that is the value for this
678      * <code>RowSet</code> object's <code>command</code> property;
679      * may be <code>null</code>
680      * @see #setCommand
681      */

682     public String JavaDoc getCommand() {
683         return command;
684     }
685
686     /**
687      * Sets this <code>RowSet</code> object's <code>command</code> property to
688      * the given <code>String</code> object and clears the parameters, if any,
689      * that were set for the previous command.
690      * <P>
691      * The <code>command</code> property may not be needed if the <code>RowSet</code>
692      * object gets its data from a source that does not support commands,
693      * such as a spreadsheet or other tabular file.
694      * Thus, this property is optional and may be <code>null</code>.
695      *
696      * @param cmd a <code>String</code> object containing an SQL query
697      * that will be set as this <code>RowSet</code> object's command
698      * property; may be <code>null</code> but may not be an empty string
699      * @throws SQLException if an empty string is provided as the command value
700      * @see #getCommand
701      */

702     public void setCommand(String JavaDoc cmd) throws SQLException {
703     // cmd equal to null or
704
// cmd with length 0 (implies url =="")
705
// are not independent events.
706

707     if(cmd == null) {
708        command = null;
709     } else if (cmd.length() == 0) {
710             throw new SQLException("Invalid command string detected. " +
711             "Cannot be of length less than 0");
712         } else {
713             // "unbind" any parameters from any previous command.
714
if(params == null){
715                  throw new SQLException("Set initParams() before setCommand");
716             }
717             params.clear();
718             command = new String JavaDoc(cmd);
719     }
720     
721     }
722
723     /**
724      * Retrieves the JDBC URL that this <code>RowSet</code> object's
725      * <code>javax.sql.Reader</code> object uses to make a connection
726      * with a relational database using a JDBC technology-enabled driver.
727      *<P>
728      * The <code>Url</code> property will be <code>null</code> if the underlying data
729      * source is a non-SQL data source, such as a spreadsheet or an XML
730      * data source.
731      *
732      * @return a <code>String</code> object that contains the JDBC URL
733      * used to establish the connection for this <code>RowSet</code>
734      * object; may be <code>null</code> (default value) if not set
735      * @throws SQLException if an error occurs retrieving the URL value
736      * @see #setUrl
737      */

738     public String JavaDoc getUrl() throws SQLException {
739         return URL;
740     }
741     
742     /**
743      * Sets the Url property for this <code>RowSet</code> object
744      * to the given <code>String</code> object and sets the dataSource name
745      * property to <code>null</code>. The Url property is a
746      * JDBC URL that is used when
747      * the connection is created using a JDBC technology-enabled driver
748      * ("JDBC driver") and the <code>DriverManager</code>.
749      * The correct JDBC URL for the specific driver to be used can be found
750      * in the driver documentation. Although there are guidelines for for how
751      * a JDBC URL is formed,
752      * a driver vendor can specify any <code>String</code> object except
753      * one with a length of <code>0</code> (an empty string).
754      * <P>
755      * Setting the Url property is optional if connections are established using
756      * a <code>DataSource</code> object instead of the <code>DriverManager</code>.
757      * The driver will use either the URL property or the
758      * dataSourceName property to create a connection, whichever was
759      * specified most recently. If an application uses a JDBC URL, it
760      * must load a JDBC driver that accepts the JDBC URL before it uses the
761      * <code>RowSet</code> object to connect to a database. The <code>RowSet</code>
762      * object will use the URL internally to create a database connection in order
763      * to read or write data.
764      *
765      * @param url a <code>String</code> object that contains the JDBC URL
766      * that will be used to establish the connection to a database for this
767      * <code>RowSet</code> object; may be <code>null</code> but must not
768      * be an empty string
769      * @throws SQLException if an error occurs setting the Url property or the
770      * parameter supplied is a string with a length of <code>0</code> (an
771      * empty string)
772      * @see #getUrl
773      */

774     public void setUrl(String JavaDoc url) throws SQLException {
775     if(url == null) {
776        url = null;
777     } else if (url.length() < 1) {
778             throw new SQLException("Invalid url string detected. " +
779             "Cannot be of length less than 1");
780         } else {
781             URL = new String JavaDoc(url);
782     }
783     
784         dataSource = null;
785         
786     }
787
788     /**
789      * Returns the logical name that when supplied to a naming service
790      * that uses the Java Naming and Directory Interface (JNDI) API, will
791      * retrieve a <code>javax.sql.DataSource</code> object. This
792      * <code>DataSource</code> object can be used to establish a connection
793      * to the data source that it represents.
794      * <P>
795      * Users should set either the url or the data source name property.
796      * The driver will use the property set most recently to establish a
797      * connection.
798      *
799      * @return a <code>String</code> object that identifies the
800      * <code>DataSource</code> object to be used for making a
801      * connection; if no logical name has been set, <code>null</code>
802      * is returned.
803      * @see #setDataSourceName
804      */

805     public String JavaDoc getDataSourceName() {
806         return dataSource;
807     }
808
809
810     /**
811      * Sets the <code>DataSource</code> name property for this <code>RowSet</code>
812      * object to the given logical name and sets this <code>RowSet</code> object's
813      * Url property to <code>null</code>. The name must have been bound to a
814      * <code>DataSource</code> object in a JNDI naming service so that an
815      * application can do a lookup using that name to retrieve the
816      * <code>DataSource</code> object bound to it. The <code>DataSource</code>
817      * object can then be used to establish a connection to the data source it
818      * represents.
819      * <P>
820      * Users should set either the Url property or the dataSourceName property.
821      * If both properties are set, the driver will use the property set most recently.
822      *
823      * @param name a <code>String</code> object with the name that can be supplied
824      * to a naming service based on JNDI technology to retrieve the
825      * <code>DataSource</code> object that can be used to get a connection;
826      * may be <code>null</code> but must not be an empty string
827      * @throws SQLException if an empty string is provided as the <code>DataSource</code>
828      * name
829      * @see #getDataSourceName
830      */

831     public void setDataSourceName(String JavaDoc name) throws SQLException {
832         
833         if (name == null) {
834             dataSource = null;
835         } else if (name.equals("")) {
836            throw new SQLException("DataSource name cannot be empty string");
837         } else {
838            dataSource = new String JavaDoc(name);
839         }
840
841         URL = null;
842     }
843
844     /**
845      * Returns the user name used to create a database connection. Because it
846      * is not serialized, the username property is set at runtime before
847      * calling the method <code>execute</code>.
848      *
849      * @return the <code>String</code> object containing the user name that
850      * is supplied to the data source to create a connection; may be
851      * <code>null</code> (default value) if not set
852      * @see #setUsername
853      */

854     public String JavaDoc getUsername() {
855         return username;
856     }
857
858     /**
859      * Sets the username property for this <code>RowSet</code> object
860      * to the given user name. Because it
861      * is not serialized, the username property is set at run time before
862      * calling the method <code>execute</code>.
863      *
864      * @param name the <code>String</code> object containing the user name that
865      * is supplied to the data source to create a connection. It may be null.
866      * @see #getUsername
867      */

868     public void setUsername(String JavaDoc name) {
869         if(name == null)
870         {
871        username = null;
872         } else {
873            username = new String JavaDoc(name);
874     }
875     }
876
877     /**
878      * Returns the password used to create a database connection for this
879      * <code>RowSet</code> object. Because the password property is not
880      * serialized, it is set at run time before calling the method
881      * <code>execute</code>. The default value is <code>null</code>
882      *
883      * @return the <code>String</code> object that represents the password
884      * that must be supplied to the database to create a connection
885      * @see #setPassword
886      */

887     public String JavaDoc getPassword() {
888         return password;
889     }
890
891     /**
892      * Sets the password used to create a database connection for this
893      * <code>RowSet</code> object to the given <code>String</code>
894      * object. Because the password property is not
895      * serialized, it is set at run time before calling the method
896      * <code>execute</code>.
897      *
898      * @param pass the <code>String</code> object that represents the password
899      * that is supplied to the database to create a connection. It may be
900      * null.
901      * @see #getPassword
902      */

903     public void setPassword(String JavaDoc pass) {
904     if(pass == null)
905     {
906        password = null;
907     } else {
908            password = new String JavaDoc(pass);
909     }
910     }
911
912     /**
913      * Sets the type for this <code>RowSet</code> object to the specified type.
914      * The default type is <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>.
915      *
916      * @param type one of the following constants:
917      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
918      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
919      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
920      * @throws SQLException if the parameter supplied is not one of the
921      * following constants:
922      * <code>ResultSet.TYPE_FORWARD_ONLY</code> or
923      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>
924      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
925      * @see #getConcurrency
926      * @see #getType
927      */

928     public void setType(int type) throws SQLException {
929         
930         if ((type != ResultSet.TYPE_FORWARD_ONLY) &&
931            (type != ResultSet.TYPE_SCROLL_INSENSITIVE) &&
932            (type != ResultSet.TYPE_SCROLL_SENSITIVE)) {
933                 throw new SQLException("Invalid type of RowSet set. Must be either " +
934                 "ResultSet.TYPE_FORWARD_ONLY or ResultSet.TYPE_SCROLL_INSENSITIVE " +
935                 "or ResultSet.TYPE_SCROLL_SENSITIVE.");
936         }
937         this.rowSetType = type;
938     }
939
940     /**
941      * Returns the type of this <code>RowSet</code> object. The type is initially
942      * determined by the statement that created the <code>RowSet</code> object.
943      * The <code>RowSet</code> object can call the method
944      * <code>setType</code> at any time to change its
945      * type. The default is <code>TYPE_SCROLL_INSENSITIVE</code>.
946      *
947      * @return the type of this JDBC <code>RowSet</code>
948      * object, which must be one of the following:
949      * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
950      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
951      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
952      * @throws SQLException if an error occurs getting the type of
953      * of this <code>RowSet</code> object
954      * @see #setType
955      */

956     public int getType() throws SQLException {
957         return rowSetType;
958     }
959
960     /**
961      * Sets the concurrency for this <code>RowSet</code> object to
962      * the specified concurrency. The default concurrency for any <code>RowSet</code>
963      * object (connected or disconnected) is <code>ResultSet.CONCUR_UPDATABLE</code>,
964      * but this method may be called at any time to change the concurrency.
965      * <P>
966      * @param concurrency one of the following constants:
967      * <code>ResultSet.CONCUR_READ_ONLY</code> or
968      * <code>ResultSet.CONCUR_UPDATABLE</code>
969      * @throws SQLException if the parameter supplied is not one of the
970      * following constants:
971      * <code>ResultSet.CONCUR_UPDATABLE</code> or
972      * <code>ResultSet.CONCUR_READ_ONLY</code>
973      * @see #getConcurrency
974      * @see #isReadOnly
975      */

976     public void setConcurrency(int concurrency) throws SQLException {
977         
978         if((concurrency != ResultSet.CONCUR_READ_ONLY) &&
979            (concurrency != ResultSet.CONCUR_UPDATABLE)) {
980                 throw new SQLException("Invalid concurrency set. Must be either " +
981                 "ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE.");
982         }
983         this.concurrency = concurrency;
984     }
985
986     /**
987      * Returns a <code>boolean</code> indicating whether this
988      * <code>RowSet</code> object is read-only.
989      * Any attempts to update a read-only <code>RowSet</code> object will result in an
990      * <code>SQLException</code> being thrown. By default,
991      * rowsets are updatable if updates are possible.
992      *
993      * @return <code>true</code> if this <code>RowSet</code> object
994      * cannot be updated; <code>false</code> otherwise
995      * @see #setConcurrency
996      * @see #setReadOnly
997      */

998     public boolean isReadOnly() {
999         return readOnly;
1000    };
1001
1002    /**
1003     * Sets this <code>RowSet</code> object's readOnly property to the given <code>boolean</code>.
1004     *
1005     * @param value <code>true</code> to indicate that this
1006     * <code>RowSet</code> object is read-only;
1007     * <code>false</code> to indicate that it is updatable
1008     */

1009    public void setReadOnly(boolean value) {
1010        readOnly = value;
1011    }
1012
1013    /**
1014     * Returns the transaction isolation property for this
1015     * <code>RowSet</code> object's connection. This property represents
1016     * the transaction isolation level requested for use in transactions.
1017     * <P>
1018     * For <code>RowSet</code> implementations such as
1019     * the <code>CachedRowSet</code> that operate in a disconnected environment,
1020     * the <code>SyncProvider</code> object
1021     * offers complementary locking and data integrity options. The
1022     * options described below are pertinent only to connected <code>RowSet</code>
1023     * objects (<code>JdbcRowSet</code> objects).
1024     *
1025     * @return one of the following constants:
1026     * <code>Connection.TRANSACTION_NONE</code>,
1027     * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
1028     * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1029     * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
1030     * <code>Connection.TRANSACTION_SERIALIZABLE</code>
1031     * @see javax.sql.rowset.spi.SyncFactory
1032     * @see javax.sql.rowset.spi.SyncProvider
1033     * @see #setTransactionIsolation
1034
1035     */

1036    public int getTransactionIsolation() {
1037        return isolation;
1038    };
1039
1040    /**
1041     * Sets the transaction isolation property for this JDBC <code>RowSet</code> object to the given
1042     * constant. The DBMS will use this transaction isolation level for
1043     * transactions if it can.
1044     * <p>
1045     * For <code>RowSet</code> implementations such as
1046     * the <code>CachedRowSet</code> that operate in a disconnected environment,
1047     * the <code>SyncProvider</code> object being used
1048     * offers complementary locking and data integrity options. The
1049     * options described below are pertinent only to connected <code>RowSet</code>
1050     * objects (<code>JdbcRowSet</code> objects).
1051     *
1052     * @param level one of the following constants, listed in ascending order:
1053     * <code>Connection.TRANSACTION_NONE</code>,
1054     * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
1055     * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1056     * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
1057     * <code>Connection.TRANSACTION_SERIALIZABLE</code>
1058     * @throws SQLException if the given parameter is not one of the Connection
1059     * constants
1060     * @see javax.sql.rowset.spi.SyncFactory
1061     * @see javax.sql.rowset.spi.SyncProvider
1062     * @see #getTransactionIsolation
1063     */

1064    public void setTransactionIsolation(int level) throws SQLException {
1065        if ((level != Connection.TRANSACTION_NONE) &&
1066           (level != Connection.TRANSACTION_READ_COMMITTED) &&
1067           (level != Connection.TRANSACTION_READ_UNCOMMITTED) &&
1068           (level != Connection.TRANSACTION_REPEATABLE_READ) &&
1069           (level != Connection.TRANSACTION_SERIALIZABLE))
1070            {
1071                throw new SQLException("Invalid transaction isolation set. Must " +
1072                "be either " +
1073                "Connection.TRANSACTION_NONE or " +
1074                "Connection.TRANSACTION_READ_UNCOMMITTED or " +
1075                "Connection.TRANSACTION_READ_COMMITTED or " +
1076                "Connection.RRANSACTION_REPEATABLE_READ or " +
1077                "Connection.TRANSACTION_SERIALIZABLE");
1078            }
1079        this.isolation = level;
1080    }
1081
1082    /**
1083     * Retrieves the type map associated with the <code>Connection</code>
1084     * object for this <code>RowSet</code> object.
1085     * <P>
1086     * Drivers that support the JDBC 3.0 API will create
1087     * <code>Connection</code> objects with an associated type map.
1088     * This type map, which is initially empty, can contain one or more
1089     * fully-qualified SQL names and <code>Class</code> objects indicating
1090     * the class to which the named SQL value will be mapped. The type mapping
1091     * specified in the connection's type map is used for custom type mapping
1092     * when no other type map supersedes it.
1093     * <p>
1094     * If a type map is explicitly supplied to a method that can perform
1095     * custom mapping, that type map supersedes the connection's type map.
1096     *
1097     * @return the <code>java.util.Map</code> object that is the type map
1098     * for this <code>RowSet</code> object's connection
1099     */

1100    public java.util.Map JavaDoc<String JavaDoc,Class JavaDoc<?>> getTypeMap() {
1101        return map;
1102    }
1103
1104    /**
1105     * Installs the given <code>java.util.Map</code> object as the type map
1106     * associated with the <code>Connection</code> object for this
1107     * <code>RowSet</code> object. The custom mapping indicated in
1108     * this type map will be used unless a different type map is explicitly
1109     * supplied to a method, in which case the type map supplied will be used.
1110     *
1111     * @param map a <code>java.util.Map</code> object that contains the
1112     * mapping from SQL type names for user defined types (UDT) to classes in
1113     * the Java programming language. Each entry in the <code>Map</code>
1114     * object consists of the fully qualified SQL name of a UDT and the
1115     * <code>Class</code> object for the <code>SQLData</code> implementation
1116     * of that UDT. May be <code>null</code>.
1117     */

1118    public void setTypeMap(java.util.Map JavaDoc<String JavaDoc,Class JavaDoc<?>> map) {
1119        this.map = map;
1120    }
1121
1122    /**
1123     * Retrieves the maximum number of bytes that can be used for a column
1124     * value in this <code>RowSet</code> object.
1125     * This limit applies only to columns that hold values of the
1126     * following types: <code>BINARY</code>, <code>VARBINARY</code>,
1127     * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
1128     * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
1129     * data is silently discarded.
1130     *
1131     * @return an <code>int</code> indicating the current maximum column size
1132     * limit; zero means that there is no limit
1133     * @throws SQLException if an error occurs internally determining the
1134     * maximum limit of the column size
1135     */

1136    public int getMaxFieldSize() throws SQLException {
1137        return maxFieldSize;
1138    }
1139    
1140    /**
1141     * Sets the maximum number of bytes that can be used for a column
1142     * value in this <code>RowSet</code> object to the given number.
1143     * This limit applies only to columns that hold values of the
1144     * following types: <code>BINARY</code>, <code>VARBINARY</code>,
1145     * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
1146     * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
1147     * data is silently discarded. For maximum portability, it is advisable to
1148     * use values greater than 256.
1149     *
1150     * @param max an <code>int</code> indicating the new maximum column size
1151     * limit; zero means that there is no limit
1152     * @throws SQLException if (1) an error occurs internally setting the
1153     * maximum limit of the column size or (2) a size of less than 0 is set
1154     */

1155    public void setMaxFieldSize(int max) throws SQLException {
1156        if (max < 0) {
1157            throw new SQLException("Invalid max field size set. Cannot be of " +
1158            "value: " + max);
1159        }
1160        maxFieldSize = max;
1161    }
1162
1163    /**
1164     * Retrieves the maximum number of rows that this <code>RowSet</code> object may contain. If
1165     * this limit is exceeded, the excess rows are silently dropped.
1166     *
1167     * @return an <code>int</code> indicating the current maximum number of
1168     * rows; zero means that there is no limit
1169     * @throws SQLException if an error occurs internally determining the
1170     * maximum limit of rows that a <code>Rowset</code> object can contain
1171     */

1172    public int getMaxRows() throws SQLException {
1173        return maxRows;
1174    }
1175
1176    /**
1177     * Sets the maximum number of rows that this <code>RowSet</code> object may contain to
1178     * the given number. If this limit is exceeded, the excess rows are
1179     * silently dropped.
1180     *
1181     * @param max an <code>int</code> indicating the current maximum number
1182     * of rows; zero means that there is no limit
1183     * @throws SQLException if an error occurs internally setting the
1184     * maximum limit on the number of rows that a JDBC <code>RowSet</code> object
1185     * can contain; or if <i>max</i> is less than <code>0</code>; or
1186     * if <i>max</i> is less than the <code>fetchSize</code> of the
1187     * <code>RowSet</code>
1188     */

1189    public void setMaxRows(int max) throws SQLException {
1190        if (max < 0) {
1191            throw new SQLException("Invalid max row size set. Cannot be of " +
1192                "value: " + max);
1193        } else if (max < this.getFetchSize()) {
1194            throw new SQLException("Invalid max row size set. Cannot be less " +
1195                "than the fetchSize.");
1196        }
1197        this.maxRows = max;
1198    }
1199
1200    /**
1201     * Sets to the given <code>boolean</code> whether or not the driver will
1202     * scan for escape syntax and do escape substitution before sending SQL
1203     * statements to the database. The default is for the driver to do escape
1204     * processing.
1205     * <P>
1206     * Note: Since <code>PreparedStatement</code> objects have usually been
1207     * parsed prior to making this call, disabling escape processing for
1208     * prepared statements will likely have no effect.
1209     *
1210     * @param enable <code>true</code> to enable escape processing;
1211     * <code>false</code> to disable it
1212     * @throws SQLException if an error occurs setting the underlying JDBC
1213     * technology-enabled driver to process the escape syntax
1214     */

1215    public void setEscapeProcessing(boolean enable) throws SQLException {
1216        escapeProcessing = enable;
1217    }
1218
1219    /**
1220     * Retrieves the maximum number of seconds the driver will wait for a
1221     * query to execute. If the limit is exceeded, an <code>SQLException</code>
1222     * is thrown.
1223     *
1224     * @return the current query timeout limit in seconds; zero means that
1225     * there is no limit
1226     * @throws SQLException if an error occurs in determining the query
1227     * time-out value
1228     */

1229    public int getQueryTimeout() throws SQLException {
1230        return queryTimeout;
1231    }
1232
1233    /**
1234     * Sets to the given number the maximum number of seconds the driver will
1235     * wait for a query to execute. If the limit is exceeded, an
1236     * <code>SQLException</code> is thrown.
1237     *
1238     * @param seconds the new query time-out limit in seconds; zero means that
1239     * there is no limit; must not be less than zero
1240     * @throws SQLException if an error occurs setting the query
1241     * time-out or if the query time-out value is less than 0
1242     */

1243    public void setQueryTimeout(int seconds) throws SQLException {
1244        if (seconds < 0) {
1245            throw new SQLException("Invalid query timeout value set. Cannot be " +
1246            "of value: " + seconds);
1247        }
1248        this.queryTimeout = seconds;
1249    }
1250
1251    /**
1252     * Retrieves a <code>boolean</code> indicating whether rows marked
1253     * for deletion appear in the set of current rows.
1254     * The default value is <code>false</code>.
1255     * <P>
1256     * Note: Allowing deleted rows to remain visible complicates the behavior
1257     * of some of the methods. However, most <code>RowSet</code> object users
1258     * can simply ignore this extra detail because only sophisticated
1259     * applications will likely want to take advantage of this feature.
1260     *
1261     * @return <code>true</code> if deleted rows are visible;
1262     * <code>false</code> otherwise
1263     * @throws SQLException if an error occurs determining if deleted rows
1264     * are visible or not
1265     * @see #setShowDeleted
1266     */

1267    public boolean getShowDeleted() throws SQLException {
1268        return showDeleted;
1269    }
1270
1271    /**
1272     * Sets the property <code>showDeleted</code> to the given
1273     * <code>boolean</code> value, which determines whether
1274     * rows marked for deletion appear in the set of current rows.
1275     *
1276     * @param value <code>true</code> if deleted rows should be shown;
1277     * <code>false</code> otherwise
1278     * @throws SQLException if an error occurs setting whether deleted
1279     * rows are visible or not
1280     * @see #getShowDeleted
1281     */

1282    public void setShowDeleted(boolean value) throws SQLException {
1283        showDeleted = value;
1284    }
1285
1286    /**
1287     * Ascertains whether escape processing is enabled for this
1288     * <code>RowSet</code> object.
1289     *
1290     * @return <code>true</code> if escape processing is turned on;
1291     * <code>false</code> otherwise
1292     * @throws SQLException if an error occurs determining if escape
1293     * processing is enabled or not or if the internal escape
1294     * processing trigger has not been enabled
1295     */

1296    public boolean getEscapeProcessing() throws SQLException {
1297        return escapeProcessing;
1298    }
1299
1300    /**
1301     * Gives the driver a performance hint as to the direction in
1302     * which the rows in this <code>RowSet</code> object will be
1303     * processed. The driver may ignore this hint.
1304     * <P>
1305     * A <code>RowSet</code> object inherits the default properties of the
1306     * <code>ResultSet</code> object from which it got its data. That
1307     * <code>ResultSet</code> object's default fetch direction is set by
1308     * the <code>Statement</code> object that created it.
1309     * <P>
1310     * This method applies to a <code>RowSet</code> object only while it is
1311     * connected to a database using a JDBC driver.
1312     * <p>
1313     * A <code>RowSet</code> object may use this method at any time to change
1314     * its setting for the fetch direction.
1315     *
1316     * @param direction one of <code>ResultSet.FETCH_FORWARD</code>,
1317     * <code>ResultSet.FETCH_REVERSE</code>, or
1318     * <code>ResultSet.FETCH_UNKNOWN</code>
1319     * @throws SQLException if (1) the <code>RowSet</code> type is
1320     * <code>TYPE_FORWARD_ONLY</code> and the given fetch direction is not
1321     * <code>FETCH_FORWARD</code> or (2) the given fetch direction is not
1322     * one of the following:
1323     * ResultSet.FETCH_FORWARD,
1324     * ResultSet.FETCH_REVERSE, or
1325     * ResultSet.FETCH_UNKNOWN
1326     * @see #getFetchDirection
1327     */

1328    public void setFetchDirection(int direction) throws SQLException {
1329        // Changed the condition checking to the below as there were two
1330
// conditions that had to be checked
1331
// 1. RowSet is TYPE_FORWARD_ONLY and direction is not FETCH_FORWARD
1332
// 2. Direction is not one of the valid values
1333

1334        if (((getType() == ResultSet.TYPE_FORWARD_ONLY) && (direction != ResultSet.FETCH_FORWARD)) ||
1335            ((direction != ResultSet.FETCH_FORWARD) &&
1336            (direction != ResultSet.FETCH_REVERSE) &&
1337            (direction != ResultSet.FETCH_UNKNOWN))) {
1338            throw new SQLException("Invalid Fetch Direction");
1339        }
1340        fetchDir = direction;
1341    }
1342
1343    /**
1344     * Retrieves this <code>RowSet</code> object's current setting for the
1345     * fetch direction. The default type is <code>ResultSet.FETCH_FORWARD</code>
1346     *
1347     * @return one of <code>ResultSet.FETCH_FORWARD</code>,
1348     * <code>ResultSet.FETCH_REVERSE</code>, or
1349     * <code>ResultSet.FETCH_UNKNOWN</code>
1350     * @throws SQLException if an error occurs in determining the
1351     * current fetch direction for fetching rows
1352     * @see #setFetchDirection
1353     */

1354    public int getFetchDirection() throws SQLException {
1355    
1356        //Added the following code to throw a
1357
//SQL Exception if the fetchDir is not
1358
//set properly.Bug id:4914155
1359

1360        // This checking is not necessary!
1361

1362        /*
1363         if((fetchDir != ResultSet.FETCH_FORWARD) &&
1364           (fetchDir != ResultSet.FETCH_REVERSE) &&
1365           (fetchDir != ResultSet.FETCH_UNKNOWN)) {
1366            throw new SQLException("Fetch Direction Invalid");
1367         }
1368         */

1369        return (fetchDir);
1370    }
1371
1372    /**
1373     * Sets the fetch size for this <code>RowSet</code> object to the given number of
1374     * rows. The fetch size gives a JDBC technology-enabled driver ("JDBC driver")
1375     * a hint as to the
1376     * number of rows that should be fetched from the database when more rows
1377     * are needed for this <code>RowSet</code> object. If the fetch size specified
1378     * is zero, the driver ignores the value and is free to make its own best guess
1379     * as to what the fetch size should be.
1380     * <P>
1381     * A <code>RowSet</code> object inherits the default properties of the
1382     * <code>ResultSet</code> object from which it got its data. That
1383     * <code>ResultSet</code> object's default fetch size is set by
1384     * the <code>Statement</code> object that created it.
1385     * <P>
1386     * This method applies to a <code>RowSet</code> object only while it is
1387     * connected to a database using a JDBC driver.
1388     * For connected <code>RowSet</code> implementations such as
1389     * <code>JdbcRowSet</code>, this method has a direct and immediate effect
1390     * on the underlying JDBC driver.
1391     * <P>
1392     * A <code>RowSet</code> object may use this method at any time to change
1393     * its setting for the fetch size.
1394     * <p>
1395     * For <code>RowSet</code> implementations such as
1396     * <code>CachedRowSet</code>, which operate in a disconnected environment,
1397     * the <code>SyncProvider</code> object being used
1398     * may leverage the fetch size to poll the data source and
1399     * retrieve a number of rows that do not exceed the fetch size and that may
1400     * form a subset of the actual rows returned by the original query. This is
1401     * an implementation variance determined by the specific <code>SyncProvider</code>
1402     * object employed by the disconnected <code>RowSet</code> object.
1403     * <P>
1404     *
1405     * @param rows the number of rows to fetch; <code>0</code> to let the
1406     * driver decide what the best fetch size is; must not be less
1407     * than <code>0</code> or more than the maximum number of rows
1408     * allowed for this <code>RowSet</code> object (the number returned
1409     * by a call to the method {@link #getMaxRows})
1410     * @throws SQLException if the specified fetch size is less than <code>0</code>
1411     * or more than the limit for the maximum number of rows
1412     * @see #getFetchSize
1413     */

1414    public void setFetchSize(int rows) throws SQLException {
1415        //Added this checking as maxRows can be 0 when this function is called
1416
//maxRows = 0 means rowset can hold any number of rows, os this checking
1417
// is needed to take care of this condition.
1418
if (getMaxRows() == 0 && rows >= 0) {
1419            fetchSize = rows;
1420            return;
1421        }
1422        if ((rows < 0) || (rows > getMaxRows())) {
1423            throw new SQLException("Invalid fetch size set. Cannot be of " +
1424            "value: " + rows);
1425        }
1426        fetchSize = rows;
1427    }
1428
1429    /**
1430     * Returns the fetch size for this <code>RowSet</code> object. The default
1431     * value is zero.
1432     *
1433     * @return the number of rows suggested as the fetch size when this <code>RowSet</code> object
1434     * needs more rows from the database
1435     * @throws SQLException if an error occurs determining the number of rows in the
1436     * current fetch size
1437     * @see #setFetchSize
1438     */

1439    public int getFetchSize() throws SQLException {
1440        return fetchSize;
1441    }
1442
1443    /**
1444     * Returns the concurrency for this <code>RowSet</code> object.
1445     * The default is <code>CONCUR_UPDATABLE</code> for both connected and
1446     * disconnected <code>RowSet</code> objects.
1447     * <P>
1448     * An application can call the method <code>setConcurrency</code> at any time
1449     * to change a <code>RowSet</code> object's concurrency.
1450     * <p>
1451     * @return the concurrency type for this <code>RowSet</code>
1452     * object, which must be one of the following:
1453     * <code>ResultSet.CONCUR_READ_ONLY</code> or
1454     * <code>ResultSet.CONCUR_UPDATABLE</code>
1455     * @throws SQLException if an error occurs getting the concurrency
1456     * of this <code>RowSet</code> object
1457     * @see #setConcurrency
1458     * @see #isReadOnly
1459     */

1460    public int getConcurrency() throws SQLException {
1461        return concurrency;
1462    }
1463
1464    //-----------------------------------------------------------------------
1465
// Parameters
1466
//-----------------------------------------------------------------------
1467

1468    /**
1469     * Checks the given index to see whether it is less than <code>1</code> and
1470     * throws an <code>SQLException</code> object if it is.
1471     * <P>
1472     * This method is called by many methods internally; it is never
1473     * called by an application directly.
1474     *
1475     * @param idx an <code>int</code> indicating which parameter is to be
1476     * checked; the first parameter is <code>1</code>
1477     * @throws SQLException if the parameter is less than <code>1</code>
1478     */

1479    private void checkParamIndex(int idx) throws SQLException {
1480        if ((idx < 1)) {
1481            throw new SQLException("Invalid Parameter Index");
1482        }
1483    }
1484    
1485    //---------------------------------------------------------------------
1486
// setter methods for setting the parameters in a <code>RowSet</code> object's command
1487
//---------------------------------------------------------------------
1488

1489    /**
1490     * Sets the designated parameter to SQL <code>NULL</code>.
1491     * Note that the parameter's SQL type must be specified using one of the
1492     * type codes defined in <code>java.sql.Types</code>. This SQL type is
1493     * specified in the second parameter.
1494     * <p>
1495     * Note that the second parameter tells the DBMS the data type of the value being
1496     * set to <code>NULL</code>. Some DBMSs require this information, so it is required
1497     * in order to make code more portable.
1498     * <P>
1499     * The parameter value set by this method is stored internally and
1500     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1501     * object's command when the method <code>execute</code> is called.
1502     * Methods such as <code>execute</code> and <code>populate</code> must be
1503     * provided in any class that extends this class and implements one or
1504     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1505     * <P>
1506     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1507     * as it is undefined in this class.
1508     * <P>
1509     * Calls made to the method <code>getParams</code> after this version of
1510     * <code>setNull</code>
1511     * has been called will return an <code>Object</code> array containing the parameter values that
1512     * have been set. In that array, the element that represents the values
1513     * set with this method will itself be an array. The first element of that array
1514     * is <code>null</code>.
1515     * The second element is the value set for <i>sqlType</i>.
1516     * The parameter number is indicated by an element's position in the array
1517     * returned by the method <code>getParams</code>,
1518     * with the first element being the value for the first placeholder parameter, the
1519     * second element being the value for the second placeholder parameter, and so on.
1520     * In other words, if the second placeholder parameter is being set to
1521     * <code>null</code>, the array containing it will be the second element in
1522     * the array returned by <code>getParams</code>.
1523     * <P>
1524     * Note that because the numbering of elements in an array starts at zero,
1525     * the array element that corresponds to placeholder parameter number
1526     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
1527     *
1528     * @param parameterIndex the ordinal number of the placeholder parameter
1529     * in this <code>RowSet</code> object's command that is to be set.
1530     * The first parameter is 1, the second is 2, and so on; must be
1531     * <code>1</code> or greater
1532     * @param sqlType an <code>int</code> that is one of the SQL type codes
1533     * defined in the class {@link java.sql.Types}. If a non-standard
1534     * <i>sqlType</i> is supplied, this method will not throw a
1535     * <code>SQLException</code>. This allows implicit support for
1536     * non-standard SQL types.
1537     * @throws SQLException if a database access error occurs or the given
1538     * parameter index is out of bounds
1539     * @see #getParams
1540     */

1541    public void setNull(int parameterIndex, int sqlType) throws SQLException {
1542        Object JavaDoc nullVal[];
1543        checkParamIndex(parameterIndex);
1544        
1545        nullVal = new Object JavaDoc[2];
1546        nullVal[0] = null;
1547        nullVal[1] = new Integer JavaDoc(sqlType);
1548
1549       if (params == null){
1550            throw new SQLException("Set initParams() before setNull");
1551       }
1552        
1553        params.put(new Integer JavaDoc(parameterIndex - 1), nullVal);
1554    }
1555
1556    /**
1557     * Sets the designated parameter to SQL <code>NULL</code>.
1558     *
1559     * Although this version of the method <code>setNull</code> is intended
1560     * for user-defined
1561     * and <code>REF</code> parameters, this method may be used to set a null
1562     * parameter for any JDBC type. The following are user-defined types:
1563     * <code>STRUCT</code>, <code>DISTINCT</code>, and <code>JAVA_OBJECT</code>,
1564     * and named array types.
1565     *
1566     * <P><B>Note:</B> To be portable, applications must give the
1567     * SQL type code and the fully qualified SQL type name when specifying
1568     * a <code>NULL</code> user-defined or <code>REF</code> parameter.
1569     * In the case of a user-defined type, the name is the type name of
1570     * the parameter itself. For a <code>REF</code> parameter, the name is
1571     * the type name of the referenced type. If a JDBC technology-enabled
1572     * driver does not need the type code or type name information,
1573     * it may ignore it.
1574     * <P>
1575     * If the parameter does not have a user-defined or <code>REF</code> type,
1576     * the given <code>typeName</code> parameter is ignored.
1577     * <P>
1578     * The parameter value set by this method is stored internally and
1579     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1580     * object's command when the method <code>execute</code> is called.
1581     * Methods such as <code>execute</code> and <code>populate</code> must be
1582     * provided in any class that extends this class and implements one or
1583     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1584     * <P>
1585     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1586     * as it is undefined in this class.
1587     * <P>
1588     * Calls made to the method <code>getParams</code> after this version of
1589     * <code>setNull</code>
1590     * has been called will return an <code>Object</code> array containing the parameter values that
1591     * have been set. In that array, the element that represents the values
1592     * set with this method will itself be an array. The first element of that array
1593     * is <code>null</code>.
1594     * The second element is the value set for <i>sqlType</i>, and the third
1595     * element is the value set for <i>typeName</i>.
1596     * The parameter number is indicated by an element's position in the array
1597     * returned by the method <code>getParams</code>,
1598     * with the first element being the value for the first placeholder parameter, the
1599     * second element being the value for the second placeholder parameter, and so on.
1600     * In other words, if the second placeholder parameter is being set to
1601     * <code>null</code>, the array containing it will be the second element in
1602     * the array returned by <code>getParams</code>.
1603     * <P>
1604     * Note that because the numbering of elements in an array starts at zero,
1605     * the array element that corresponds to placeholder parameter number
1606     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
1607     *
1608     * @param parameterIndex the ordinal number of the placeholder parameter
1609     * in this <code>RowSet</code> object's command that is to be set.
1610     * The first parameter is 1, the second is 2, and so on; must be
1611     * <code>1</code> or greater
1612     * @param sqlType a value from <code>java.sql.Types</code>
1613     * @param typeName the fully qualified name of an SQL user-defined type,
1614     * which is ignored if the parameter is not a user-defined
1615     * type or <code>REF</code> value
1616     * @throws SQLException if an error occurs or the given parameter index
1617     * is out of bounds
1618     * @see #getParams
1619     */

1620    public void setNull(int parameterIndex, int sqlType, String JavaDoc typeName)
1621        throws SQLException {
1622        
1623        Object JavaDoc nullVal[];
1624        checkParamIndex(parameterIndex);
1625        
1626        nullVal = new Object JavaDoc[3];
1627        nullVal[0] = null;
1628        nullVal[1] = new Integer JavaDoc(sqlType);
1629        nullVal[2] = new String JavaDoc(typeName);
1630
1631       if(params == null){
1632            throw new SQLException("Set initParams() before setNull");
1633       }
1634        
1635        params.put(new Integer JavaDoc(parameterIndex - 1), nullVal);
1636    }
1637
1638
1639    /**
1640     * Sets the designated parameter to the given <code>boolean</code> in the
1641     * Java programming language. The driver converts this to an SQL
1642     * <code>BIT</code> value when it sends it to the database.
1643     * <P>
1644     * The parameter value set by this method is stored internally and
1645     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1646     * object's command when the method <code>execute</code> is called.
1647     * Methods such as <code>execute</code>, <code>populate</code> must be
1648     * provided in any class that extends this class and implements one or
1649     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1650     * <p>
1651     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1652     * as it is undefined in this class.
1653     *
1654     * @param parameterIndex the ordinal number of the placeholder parameter
1655     * in this <code>RowSet</code> object's command that is to be set.
1656     * The first parameter is 1, the second is 2, and so on; must be
1657     * <code>1</code> or greater
1658     * @param x the parameter value
1659     * @throws SQLException if an error occurs or the
1660     * parameter index is out of bounds
1661     * @see #getParams
1662     */

1663    public void setBoolean(int parameterIndex, boolean x) throws SQLException {
1664        checkParamIndex(parameterIndex);
1665
1666       if(params == null){
1667            throw new SQLException("Set initParams() before setNull");
1668       }
1669        
1670        params.put(new Integer JavaDoc(parameterIndex - 1), new Boolean JavaDoc(x));
1671    }
1672
1673    /**
1674     * Sets the designated parameter to the given <code>byte</code> in the Java
1675     * programming language. The driver converts this to an SQL
1676     * <code>TINYINT</code> value when it sends it to the database.
1677     * <P>
1678     * The parameter value set by this method is stored internally and
1679     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1680     * object's command when the method <code>execute</code> is called.
1681     * Methods such as <code>execute</code> and <code>populate</code> must be
1682     * provided in any class that extends this class and implements one or
1683     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1684     * <p>
1685     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1686     * as it is undefined in this class.
1687     *
1688     * @param parameterIndex the ordinal number of the placeholder parameter
1689     * in this <code>RowSet</code> object's command that is to be set.
1690     * The first parameter is 1, the second is 2, and so on; must be
1691     * <code>1</code> or greater
1692     * @param x the parameter value
1693     * @throws SQLException if an error occurs or the
1694     * parameter index is out of bounds
1695     * @see #getParams
1696     */

1697    public void setByte(int parameterIndex, byte x) throws SQLException {
1698        checkParamIndex(parameterIndex);
1699
1700       if(params == null){
1701            throw new SQLException("Set initParams() before setByte");
1702       }
1703        
1704        params.put(new Integer JavaDoc(parameterIndex - 1), new Byte JavaDoc(x));
1705    }
1706
1707    /**
1708     * Sets the designated parameter to the given <code>short</code> in the
1709     * Java programming language. The driver converts this to an SQL
1710     * <code>SMALLINT</code> value when it sends it to the database.
1711     * <P>
1712     * The parameter value set by this method is stored internally and
1713     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1714     * object's command when the method <code>execute</code> is called.
1715     * Methods such as <code>execute</code> and <code>populate</code> must be
1716     * provided in any class that extends this class and implements one or
1717     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1718     * <p>
1719     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1720     * as it is undefined in this class.
1721     * <p>
1722     * @param parameterIndex the ordinal number of the placeholder parameter
1723     * in this <code>RowSet</code> object's command that is to be set.
1724     * The first parameter is 1, the second is 2, and so on; must be
1725     * <code>1</code> or greater
1726     * @param x the parameter value
1727     * @throws SQLException if an error occurs or the
1728     * parameter index is out of bounds
1729     * @see #getParams
1730     */

1731    public void setShort(int parameterIndex, short x) throws SQLException {
1732        checkParamIndex(parameterIndex);
1733
1734        if(params == null){
1735             throw new SQLException("Set initParams() before setShort");
1736        }
1737        
1738        params.put(new Integer JavaDoc(parameterIndex - 1), new Short JavaDoc(x));
1739    }
1740
1741    /**
1742     * Sets the designated parameter to an <code>int</code> in the Java
1743     * programming language. The driver converts this to an SQL
1744     * <code>INTEGER</code> value when it sends it to the database.
1745     * <P>
1746     * The parameter value set by this method is stored internally and
1747     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1748     * object's command when the method <code>execute</code> is called.
1749     * Methods such as <code>execute</code> and <code>populate</code> must be
1750     * provided in any class that extends this class and implements one or
1751     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1752     * <P>
1753     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1754     * as it is undefined in this class.
1755     *
1756     * @param parameterIndex the ordinal number of the placeholder parameter
1757     * in this <code>RowSet</code> object's command that is to be set.
1758     * The first parameter is 1, the second is 2, and so on; must be
1759     * <code>1</code> or greater
1760     * @param x the parameter value
1761     * @throws SQLException if an error occurs or the
1762     * parameter index is out of bounds
1763     * @see #getParams
1764     */

1765    public void setInt(int parameterIndex, int x) throws SQLException {
1766        checkParamIndex(parameterIndex);
1767        if(params == null){
1768             throw new SQLException("Set initParams() before setInt");
1769        }
1770        params.put(new Integer JavaDoc(parameterIndex - 1), new Integer JavaDoc(x));
1771    }
1772
1773    /**
1774     * Sets the designated parameter to the given <code>long</code> in the Java
1775     * programming language. The driver converts this to an SQL
1776     * <code>BIGINT</code> value when it sends it to the database.
1777     * <P>
1778     * The parameter value set by this method is stored internally and
1779     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1780     * object's command when the method <code>execute</code> is called.
1781     * Methods such as <code>execute</code> and <code>populate</code> must be
1782     * provided in any class that extends this class and implements one or
1783     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1784     * <P>
1785     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1786     * as it is undefined in this class.
1787     *
1788     * @param parameterIndex the ordinal number of the placeholder parameter
1789     * in this <code>RowSet</code> object's command that is to be set.
1790     * The first parameter is 1, the second is 2, and so on; must be
1791     * <code>1</code> or greater
1792     * @param x the parameter value
1793     * @throws SQLException if an error occurs or the
1794     * parameter index is out of bounds
1795     * @see #getParams
1796     */

1797    public void setLong(int parameterIndex, long x) throws SQLException {
1798        checkParamIndex(parameterIndex);
1799        if(params == null){
1800             throw new SQLException("Set initParams() before setLong");
1801        }
1802        params.put(new Integer JavaDoc(parameterIndex - 1), new Long JavaDoc(x));
1803    }
1804
1805    /**
1806     * Sets the designated parameter to the given <code>float</code> in the
1807     * Java programming language. The driver converts this to an SQL
1808     * <code>FLOAT</code> value when it sends it to the database.
1809     * <P>
1810     * The parameter value set by this method is stored internally and
1811     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1812     * object's command when the method <code>execute</code> is called.
1813     * Methods such as <code>execute</code> and <code>populate</code> must be
1814     * provided in any class that extends this class and implements one or
1815     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1816     * <P>
1817     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1818     * as it is undefined in this class.
1819     *
1820     * @param parameterIndex the ordinal number of the placeholder parameter
1821     * in this <code>RowSet</code> object's command that is to be set.
1822     * The first parameter is 1, the second is 2, and so on; must be
1823     * <code>1</code> or greater
1824     * @param x the parameter value
1825     * @throws SQLException if an error occurs or the
1826     * parameter index is out of bounds
1827     * @see #getParams
1828     */

1829    public void setFloat(int parameterIndex, float x) throws SQLException {
1830        checkParamIndex(parameterIndex);
1831        if(params == null){
1832             throw new SQLException("Set initParams() before setFloat");
1833        }
1834        params.put(new Integer JavaDoc(parameterIndex - 1), new Float JavaDoc(x));
1835    }
1836
1837    /**
1838     * Sets the designated parameter to the given <code>double</code> in the
1839     * Java programming language. The driver converts this to an SQL
1840     * <code>DOUBLE</code> value when it sends it to the database.
1841     * <P>
1842     * The parameter value set by this method is stored internally and
1843     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1844     * object's command when the method <code>execute</code> is called.
1845     * Methods such as <code>execute</code> and <code>populate</code> must be
1846     * provided in any class that extends this class and implements one or
1847     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1848     * <P>
1849     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1850     * as it is undefined in this class.
1851     * S
1852     * @param parameterIndex the ordinal number of the placeholder parameter
1853     * in this <code>RowSet</code> object's command that is to be set.
1854     * The first parameter is 1, the second is 2, and so on; must be
1855     * <code>1</code> or greater
1856     * @param x the parameter value
1857     * @throws SQLException if an error occurs or the
1858     * parameter index is out of bounds
1859     * @see #getParams
1860     */

1861    public void setDouble(int parameterIndex, double x) throws SQLException {
1862        checkParamIndex(parameterIndex);
1863        if(params == null){
1864             throw new SQLException("Set initParams() before setDouble");
1865        }
1866        params.put(new Integer JavaDoc(parameterIndex - 1), new Double JavaDoc(x));
1867    }
1868
1869    /**
1870     * Sets the designated parameter to the given
1871     * <code>java.lang.BigDecimal</code> value. The driver converts this to
1872     * an SQL <code>NUMERIC</code> value when it sends it to the database.
1873     * <P>
1874     * The parameter value set by this method is stored internally and
1875     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1876     * object's command when the method <code>execute</code> is called.
1877     * Methods such as <code>execute</code> and <code>populate</code> must be
1878     * provided in any class that extends this class and implements one or
1879     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1880     * <P>
1881     * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1882     * as it is undefined in this class.
1883     *
1884     * @param parameterIndex the ordinal number of the placeholder parameter
1885     * in this <code>RowSet</code> object's command that is to be set.
1886     * The first parameter is 1, the second is 2, and so on; must be
1887     * <code>1</code> or greater
1888     * @param x the parameter value
1889     * @throws SQLException if an error occurs or the
1890     * parameter index is out of bounds
1891     * @see #getParams
1892     */

1893    public void setBigDecimal(int parameterIndex, java.math.BigDecimal JavaDoc x) throws SQLException {
1894        checkParamIndex(parameterIndex);
1895        if(params == null){
1896             throw new SQLException("Set initParams() before setBigDecimal");
1897        }
1898        params.put(new Integer JavaDoc(parameterIndex - 1), x);
1899    }
1900
1901    /**
1902     * Sets the designated parameter to the given <code>String</code>
1903     * value. The driver converts this to an SQL
1904     * <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
1905     * (depending on the argument's size relative to the driver's limits
1906     * on <code>VARCHAR</code> values) when it sends it to the database.
1907     * <P>
1908     * The parameter value set by this method is stored internally and
1909     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1910     * object's command when the method <code>execute</code> is called.
1911     * Methods such as <code>execute</code> and <code>populate</code> must be
1912     * provided in any class that extends this class and implements one or
1913     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1914     * <p>
1915     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1916     * as it is undefined in this class.
1917     * <p>
1918     * @param parameterIndex the ordinal number of the placeholder parameter
1919     * in this <code>RowSet</code> object's command that is to be set.
1920     * The first parameter is 1, the second is 2, and so on; must be
1921     * <code>1</code> or greater
1922     * @param x the parameter value
1923     * @throws SQLException if an error occurs or the
1924     * parameter index is out of bounds
1925     * @see #getParams
1926     */

1927    public void setString(int parameterIndex, String JavaDoc x) throws SQLException {
1928        checkParamIndex(parameterIndex);
1929        if(params == null){
1930             throw new SQLException("Set initParams() before setString");
1931        }
1932        params.put(new Integer JavaDoc(parameterIndex - 1), x);
1933    }
1934
1935    /**
1936     * Sets the designated parameter to the given array of bytes.
1937     * The driver converts this to an SQL
1938     * <code>VARBINARY</code> or <code>LONGVARBINARY</code> value
1939     * (depending on the argument's size relative to the driver's limits
1940     * on <code>VARBINARY</code> values) when it sends it to the database.
1941     * <P>
1942     * The parameter value set by this method is stored internally and
1943     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1944     * object's command when the method <code>execute</code> is called.
1945     * Methods such as <code>execute</code> and <code>populate</code> must be
1946     * provided in any class that extends this class and implements one or
1947     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1948     * <p>
1949     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1950     * as it is undefined in this class.
1951     *
1952     * @param parameterIndex the ordinal number of the placeholder parameter
1953     * in this <code>RowSet</code> object's command that is to be set.
1954     * The first parameter is 1, the second is 2, and so on; must be
1955     * <code>1</code> or greater
1956     * @param x the parameter value
1957     * @throws SQLException if an error occurs or the
1958     * parameter index is out of bounds
1959     * @see #getParams
1960     */

1961    public void setBytes(int parameterIndex, byte x[]) throws SQLException {
1962        checkParamIndex(parameterIndex);
1963        if(params == null){
1964             throw new SQLException("Set initParams() before setBytes");
1965        }
1966        params.put(new Integer JavaDoc(parameterIndex - 1), x);
1967    }
1968
1969    /**
1970     * Sets the designated parameter to the given <code>java.sql.Date</code>
1971     * value. The driver converts this to an SQL
1972     * <code>DATE</code> value when it sends it to the database.
1973     * <P>
1974     * The parameter value set by this method is stored internally and
1975     * will be supplied as the appropriate parameter in this <code>RowSet</code>
1976     * object's command when the method <code>execute</code> is called.
1977     * Methods such as <code>execute</code> and <code>populate</code> must be
1978     * provided in any class that extends this class and implements one or
1979     * more of the standard JSR-114 <code>RowSet</code> interfaces.
1980     * <P>
1981     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1982     * as it is undefined in this class.
1983     * <P>
1984     * Calls made to the method <code>getParams</code> after this version
1985     * of <code>setDate</code>
1986     * has been called will return an array with the value to be set for
1987     * placeholder parameter number <i>parameterIndex</i> being the <code>Date</code>
1988     * object supplied as the second parameter.
1989     * Note that because the numbering of elements in an array starts at zero,
1990     * the array element that corresponds to placeholder parameter number
1991     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
1992     *
1993     * @param parameterIndex the ordinal number of the placeholder parameter
1994     * in this <code>RowSet</code> object's command that is to be set.
1995     * The first parameter is 1, the second is 2, and so on; must be
1996     * <code>1</code> or greater
1997     * @param x the parameter value
1998     * @throws SQLException if an error occurs or the
1999     * parameter index is out of bounds
2000     * @see #getParams
2001     */

2002    public void setDate(int parameterIndex, java.sql.Date JavaDoc x) throws SQLException {
2003        checkParamIndex(parameterIndex);
2004    
2005        if(params == null){
2006             throw new SQLException("Set initParams() before setDate");
2007        }
2008        params.put(new Integer JavaDoc(parameterIndex - 1), x);
2009    }
2010
2011    /**
2012     * Sets the designated parameter to the given <code>java.sql.Time</code>
2013     * value. The driver converts this to an SQL <code>TIME</code> value
2014     * when it sends it to the database.
2015     * <P>
2016     * The parameter value set by this method is stored internally and
2017     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2018     * object's command when the method <code>execute</code> is called.
2019     * Methods such as <code>execute</code> and <code>populate</code> must be
2020     * provided in any class that extends this class and implements one or
2021     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2022     * <P>
2023     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2024     * as it is undefined in this class.
2025     * <P>
2026     * Calls made to the method <code>getParams</code> after this version
2027     * of the method <code>setTime</code>
2028     * has been called will return an array of the parameters that have been set.
2029     * The parameter to be set for parameter placeholder number <i>parameterIndex</i>
2030     * will be the <code>Time</code> object that was set as the second parameter
2031     * to this method.
2032     * <P>
2033     * Note that because the numbering of elements in an array starts at zero,
2034     * the array element that corresponds to placeholder parameter number
2035     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2036     *
2037     * @param parameterIndex the ordinal number of the placeholder parameter
2038     * in this <code>RowSet</code> object's command that is to be set.
2039     * The first parameter is 1, the second is 2, and so on; must be
2040     * <code>1</code> or greater
2041     * @param x a <code>java.sql.Time</code> object, which is to be set as the value
2042     * for placeholder parameter <i>parameterIndex</i>
2043     * @throws SQLException if an error occurs or the
2044     * parameter index is out of bounds
2045     * @see #getParams
2046     */

2047    public void setTime(int parameterIndex, java.sql.Time JavaDoc x) throws SQLException {
2048        checkParamIndex(parameterIndex);
2049        if(params == null){
2050             throw new SQLException("Set initParams() before setTime");
2051        }
2052        
2053        params.put(new Integer JavaDoc(parameterIndex - 1), x);
2054    }
2055
2056    /**
2057     * Sets the designated parameter to the given
2058     * <code>java.sql.Timestamp</code> value.
2059     * The driver converts this to an SQL <code>TIMESTAMP</code> value when it
2060     * sends it to the database.
2061     * <P>
2062     * The parameter value set by this method is stored internally and
2063     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2064     * object's command when the method <code>execute</code> is called.
2065     * Methods such as <code>execute</code> and <code>populate</code> must be
2066     * provided in any class that extends this class and implements one or
2067     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2068     * <P>
2069     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2070     * as it is undefined in this class.
2071     * <P>
2072     * Calls made to the method <code>getParams</code> after this version of
2073     * <code>setTimestamp</code>
2074     * has been called will return an array with the value for parameter placeholder
2075     * number <i>parameterIndex</i> being the <code>Timestamp</code> object that was
2076     * supplied as the second parameter to this method.
2077     * Note that because the numbering of elements in an array starts at zero,
2078     * the array element that corresponds to placeholder parameter number
2079     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2080     *
2081     * @param parameterIndex the ordinal number of the placeholder parameter
2082     * in this <code>RowSet</code> object's command that is to be set.
2083     * The first parameter is 1, the second is 2, and so on; must be
2084     * <code>1</code> or greater
2085     * @param x a <code>java.sql.Timestamp</code> object
2086     * @throws SQLException if an error occurs or the
2087     * parameter index is out of bounds
2088     * @see #getParams
2089     */

2090    public void setTimestamp(int parameterIndex, java.sql.Timestamp JavaDoc x) throws SQLException {
2091        checkParamIndex(parameterIndex);
2092        if(params == null){
2093             throw new SQLException("Set initParams() before setTimestamp");
2094        }
2095        
2096        params.put(new Integer JavaDoc(parameterIndex - 1), x);
2097    }
2098
2099    /**
2100     * Sets the designated parameter to the given
2101     * <code>java.io.InputStream</code> object,
2102     * which will have the specified number of bytes.
2103     * The contents of the stream will be read and sent to the database.
2104     * This method throws an <code>SQLException</code> object if the number of bytes
2105     * read and sent to the database is not equal to <i>length</i>.
2106     * <P>
2107     * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2108     * parameter, it may be more practical to send it via a
2109     * <code>java.io.InputStream</code> object. A JDBC technology-enabled
2110     * driver will read the data from the stream as needed until it reaches
2111     * end-of-file. The driver will do any necessary conversion from ASCII to
2112     * the database <code>CHAR</code> format.
2113     *
2114     * <P><B>Note:</B> This stream object can be either a standard
2115     * Java stream object or your own subclass that implements the
2116     * standard interface.
2117     * <P>
2118     * The parameter value set by this method is stored internally and
2119     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2120     * object's command when the method <code>execute</code> is called.
2121     * Methods such as <code>execute</code> and <code>populate</code> must be
2122     * provided in any class that extends this class and implements one or
2123     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2124     * <P>
2125     * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2126     * as it is undefined in this class.
2127     * <P>
2128     * Calls made to the method <code>getParams</code> after <code>setAsciiStream</code>
2129     * has been called will return an array containing the parameter values that
2130     * have been set. The element in the array that represents the values
2131     * set with this method will itself be an array. The first element of that array
2132     * is the given <code>java.io.InputStream</code> object.
2133     * The second element is the value set for <i>length</i>.
2134     * The third element is an internal <code>BaseRowSet</code> constant
2135     * specifying that the stream passed to this method is an ASCII stream.
2136     * The parameter number is indicated by an element's position in the array
2137     * returned by the method <code>getParams</code>,
2138     * with the first element being the value for the first placeholder parameter, the
2139     * second element being the value for the second placeholder parameter, and so on.
2140     * In other words, if the input stream being set is the value for the second
2141     * placeholder parameter, the array containing it will be the second element in
2142     * the array returned by <code>getParams</code>.
2143     * <P>
2144     * Note that because the numbering of elements in an array starts at zero,
2145     * the array element that corresponds to placeholder parameter number
2146     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2147     *
2148     * @param parameterIndex the ordinal number of the placeholder parameter
2149     * in this <code>RowSet</code> object's command that is to be set.
2150     * The first parameter is 1, the second is 2, and so on; must be
2151     * <code>1</code> or greater
2152     * @param x the Java input stream that contains the ASCII parameter value
2153     * @param length the number of bytes in the stream. This is the number of bytes
2154     * the driver will send to the DBMS; lengths of 0 or less are
2155     * are undefined but will cause an invalid length exception to be
2156     * thrown in the underlying JDBC driver.
2157     * @throws SQLException if an error occurs, the parameter index is out of bounds,
2158     * or when connected to a data source, the number of bytes the driver reads
2159     * and sends to the database is not equal to the number of bytes specified
2160     * in <i>length</i>
2161     * @see #getParams
2162     */

2163    public void setAsciiStream(int parameterIndex, java.io.InputStream JavaDoc x, int length) throws SQLException {
2164        Object JavaDoc asciiStream[];
2165        checkParamIndex(parameterIndex);
2166
2167        asciiStream = new Object JavaDoc[3];
2168        asciiStream[0] = x;
2169        asciiStream[1] = new Integer JavaDoc(length);
2170        asciiStream[2] = new Integer JavaDoc(ASCII_STREAM_PARAM);
2171        
2172        if(params == null){
2173             throw new SQLException("Set initParams() before setAsciiStream");
2174        }
2175        
2176        params.put(new Integer JavaDoc(parameterIndex - 1), asciiStream);
2177    }
2178  
2179    /**
2180     * Sets the designated parameter to the given <code>java.io.InputStream</code>
2181     * object, which will have the specified number of bytes.
2182     * The contents of the stream will be read and sent to the database.
2183     * This method throws an <code>SQLException</code> object if the number of bytes
2184     * read and sent to the database is not equal to <i>length</i>.
2185     * <P>
2186     * When a very large binary value is input to a
2187     * <code>LONGVARBINARY</code> parameter, it may be more practical
2188     * to send it via a <code>java.io.InputStream</code> object.
2189     * A JDBC technology-enabled driver will read the data from the
2190     * stream as needed until it reaches end-of-file.
2191     *
2192     * <P><B>Note:</B> This stream object can be either a standard
2193     * Java stream object or your own subclass that implements the
2194     * standard interface.
2195     * <P>
2196     * The parameter value set by this method is stored internally and
2197     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2198     * object's command when the method <code>execute</code> is called.
2199     * Methods such as <code>execute</code> and <code>populate</code> must be
2200     * provided in any class that extends this class and implements one or
2201     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2202     *<P>
2203     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2204     * as it is undefined in this class.
2205     * <P>
2206     * Calls made to the method <code>getParams</code> after <code>setBinaryStream</code>
2207     * has been called will return an array containing the parameter values that
2208     * have been set. In that array, the element that represents the values
2209     * set with this method will itself be an array. The first element of that array
2210     * is the given <code>java.io.InputStream</code> object.
2211     * The second element is the value set for <i>length</i>.
2212     * The third element is an internal <code>BaseRowSet</code> constant
2213     * specifying that the stream passed to this method is a binary stream.
2214     * The parameter number is indicated by an element's position in the array
2215     * returned by the method <code>getParams</code>,
2216     * with the first element being the value for the first placeholder parameter, the
2217     * second element being the value for the second placeholder parameter, and so on.
2218     * In other words, if the input stream being set is the value for the second
2219     * placeholder parameter, the array containing it will be the second element in
2220     * the array returned by <code>getParams</code>.
2221     * <P>
2222     * Note that because the numbering of elements in an array starts at zero,
2223     * the array element that corresponds to placeholder parameter number
2224     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2225     *
2226     * @param parameterIndex the ordinal number of the placeholder parameter
2227     * in this <code>RowSet</code> object's command that is to be set.
2228     * The first parameter is 1, the second is 2, and so on; must be
2229     * <code>1</code> or greater
2230     * @param x the input stream that contains the binary value to be set
2231     * @param length the number of bytes in the stream; lengths of 0 or less are
2232     * are undefined but will cause an invalid length exception to be
2233     * thrown in the underlying JDBC driver.
2234     * @throws SQLException if an error occurs, the parameter index is out of bounds,
2235     * or when connected to a data source, the number of bytes the driver
2236     * reads and sends to the database is not equal to the number of bytes
2237     * specified in <i>length</i>
2238     * @see #getParams
2239     */

2240    public void setBinaryStream(int parameterIndex, java.io.InputStream JavaDoc x, int length) throws SQLException {
2241        Object JavaDoc binaryStream[];
2242        checkParamIndex(parameterIndex);
2243
2244        binaryStream = new Object JavaDoc[3];
2245        binaryStream[0] = x;
2246        binaryStream[1] = new Integer JavaDoc(length);
2247        binaryStream[2] = new Integer JavaDoc(BINARY_STREAM_PARAM);
2248        if(params == null){
2249             throw new SQLException("Set initParams() before setBinaryStream");
2250        }
2251        
2252        params.put(new Integer JavaDoc(parameterIndex - 1), binaryStream);
2253    }
2254
2255    
2256    /**
2257     * Sets the designated parameter to the given
2258     * <code>java.io.InputStream</code> object, which will have the specified
2259     * number of bytes. The contents of the stream will be read and sent
2260     * to the database.
2261     * This method throws an <code>SQLException</code> if the number of bytes
2262     * read and sent to the database is not equal to <i>length</i>.
2263     * <P>
2264     * When a very large Unicode value is input to a
2265     * <code>LONGVARCHAR</code> parameter, it may be more practical
2266     * to send it via a <code>java.io.InputStream</code> object.
2267     * A JDBC technology-enabled driver will read the data from the
2268     * stream as needed, until it reaches end-of-file.
2269     * The driver will do any necessary conversion from Unicode to the
2270     * database <code>CHAR</code> format.
2271     * The byte format of the Unicode stream must be Java UTF-8, as
2272     * defined in the Java Virtual Machine Specification.
2273     *
2274     * <P><B>Note:</B> This stream object can be either a standard
2275     * Java stream object or your own subclass that implements the
2276     * standard interface.
2277     * <P>
2278     * This method is deprecated; the method <code>getCharacterStream</code>
2279     * should be used in its place.
2280     * <P>
2281     * The parameter value set by this method is stored internally and
2282     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2283     * object's command when the method <code>execute</code> is called.
2284     * Calls made to the method <code>getParams</code> after <code>setUnicodeStream</code>
2285     * has been called will return an array containing the parameter values that
2286     * have been set. In that array, the element that represents the values
2287     * set with this method will itself be an array. The first element of that array
2288     * is the given <code>java.io.InputStream</code> object.
2289     * The second element is the value set for <i>length</i>.
2290     * The third element is an internal <code>BaseRowSet</code> constant
2291     * specifying that the stream passed to this method is a Unicode stream.
2292     * The parameter number is indicated by an element's position in the array
2293     * returned by the method <code>getParams</code>,
2294     * with the first element being the value for the first placeholder parameter, the
2295     * second element being the value for the second placeholder parameter, and so on.
2296     * In other words, if the input stream being set is the value for the second
2297     * placeholder parameter, the array containing it will be the second element in
2298     * the array returned by <code>getParams</code>.
2299     * <P>
2300     * Note that because the numbering of elements in an array starts at zero,
2301     * the array element that corresponds to placeholder parameter number
2302     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2303     *
2304     * @param parameterIndex the ordinal number of the placeholder parameter
2305     * in this <code>RowSet</code> object's command that is to be set.
2306     * The first parameter is 1, the second is 2, and so on; must be
2307     * <code>1</code> or greater
2308     * @param x the <code>java.io.InputStream</code> object that contains the
2309     * UNICODE parameter value
2310     * @param length the number of bytes in the input stream
2311     * @throws SQLException if an error occurs, the parameter index is out of bounds,
2312     * or the number of bytes the driver reads and sends to the database is
2313     * not equal to the number of bytes specified in <i>length</i>
2314     * @deprecated getCharacterStream should be used in its place
2315     * @see #getParams
2316     */

2317    
2318    public void setUnicodeStream(int parameterIndex, java.io.InputStream JavaDoc x, int length) throws SQLException {
2319        Object JavaDoc unicodeStream[];
2320        checkParamIndex(parameterIndex);
2321
2322        unicodeStream = new Object JavaDoc[3];
2323        unicodeStream[0] = x;
2324        unicodeStream[1] = new Integer JavaDoc(length);
2325        unicodeStream[2] = new Integer JavaDoc(UNICODE_STREAM_PARAM);
2326        if(params == null){
2327             throw new SQLException("Set initParams() before setUnicodeStream");
2328        }
2329        params.put(new Integer JavaDoc(parameterIndex - 1), unicodeStream);
2330    }
2331    
2332    /**
2333     * Sets the designated parameter to the given <code>java.io.Reader</code>
2334     * object, which will have the specified number of characters. The
2335     * contents of the reader will be read and sent to the database.
2336     * This method throws an <code>SQLException</code> if the number of bytes
2337     * read and sent to the database is not equal to <i>length</i>.
2338     * <P>
2339     * When a very large Unicode value is input to a
2340     * <code>LONGVARCHAR</code> parameter, it may be more practical
2341     * to send it via a <code>Reader</code> object.
2342     * A JDBC technology-enabled driver will read the data from the
2343     * stream as needed until it reaches end-of-file.
2344     * The driver will do any necessary conversion from Unicode to the
2345     * database <code>CHAR</code> format.
2346     * The byte format of the Unicode stream must be Java UTF-8, as
2347     * defined in the Java Virtual Machine Specification.
2348     *
2349     * <P><B>Note:</B> This stream object can be either a standard
2350     * Java stream object or your own subclass that implements the
2351     * standard interface.
2352     * <P>
2353     * The parameter value set by this method is stored internally and
2354     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2355     * object's command when the method <code>execute</code> is called.
2356     * Methods such as <code>execute</code> and <code>populate</code> must be
2357     * provided in any class that extends this class and implements one or
2358     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2359     * <P>
2360     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2361     * as it is undefined in this class.
2362     * <P>
2363     * Calls made to the method <code>getParams</code> after
2364     * <code>setCharacterStream</code>
2365     * has been called will return an array containing the parameter values that
2366     * have been set. In that array, the element that represents the values
2367     * set with this method will itself be an array. The first element of that array
2368     * is the given <code>java.io.Reader</code> object.
2369     * The second element is the value set for <i>length</i>.
2370     * The parameter number is indicated by an element's position in the array
2371     * returned by the method <code>getParams</code>,
2372     * with the first element being the value for the first placeholder parameter, the
2373     * second element being the value for the second placeholder parameter, and so on.
2374     * In other words, if the reader being set is the value for the second
2375     * placeholder parameter, the array containing it will be the second element in
2376     * the array returned by <code>getParams</code>.
2377     * <P>
2378     * Note that because the numbering of elements in an array starts at zero,
2379     * the array element that corresponds to placeholder parameter number
2380     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2381     *
2382     * @param parameterIndex the ordinal number of the placeholder parameter
2383     * in this <code>RowSet</code> object's command that is to be set.
2384     * The first parameter is 1, the second is 2, and so on; must be
2385     * <code>1</code> or greater
2386     * @param reader the <code>Reader</code> object that contains the
2387     * Unicode data
2388     * @param length the number of characters in the stream; lengths of 0 or
2389     * less are undefined but will cause an invalid length exception to
2390     * be thrown in the underlying JDBC driver.
2391     * @throws SQLException if an error occurs, the parameter index is out of bounds,
2392     * or when connected to a data source, the number of bytes the driver
2393     * reads and sends to the database is not equal to the number of bytes
2394     * specified in <i>length</i>
2395     * @see #getParams
2396     */

2397    public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException {
2398        Object JavaDoc charStream[];
2399        checkParamIndex(parameterIndex);
2400
2401        charStream = new Object JavaDoc[2];
2402        charStream[0] = reader;
2403        charStream[1] = new Integer JavaDoc(length);
2404        if(params == null){
2405             throw new SQLException("Set initParams() before setCharacterStream");
2406        }
2407        params.put(new Integer JavaDoc(parameterIndex - 1), charStream);
2408    }
2409
2410    /**
2411     * Sets the designated parameter to an <code>Object</code> in the Java
2412     * programming language. The second parameter must be an
2413     * <code>Object</code> type. For integral values, the
2414     * <code>java.lang</code> equivalent
2415     * objects should be used. For example, use the class <code>Integer</code>
2416     * for an <code>int</code>.
2417     * <P>
2418     * The driver converts this object to the specified
2419     * target SQL type before sending it to the database.
2420     * If the object has a custom mapping (is of a class implementing
2421     * <code>SQLData</code>), the driver should call the method
2422     * <code>SQLData.writeSQL</code> to write the object to the SQL
2423     * data stream. If, on the other hand, the object is of a class
2424     * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2425     * <code>Struct</code>, or <code>Array</code>,
2426     * the driver should pass it to the database as a value of the
2427     * corresponding SQL type.
2428     * <P>
2429     * <p>Note that this method may be used to pass database-
2430     * specific abstract data types.
2431     * <P>
2432     * The parameter value set by this method is stored internally and
2433     * will be supplied as the appropriate parameter in this <code>RowSet</code
2434     * object's command when the method <code>execute</code> is called.
2435     * Methods such as <code>execute</code> and <code>populate</code> must be
2436     * provided in any class that extends this class and implements one or
2437     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2438     * <P>
2439     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2440     * as it is undefined in this class.
2441     * <P>
2442     * Calls made to the method <code>getParams</code> after this version of
2443     * <code>setObject</code>
2444     * has been called will return an array containing the parameter values that
2445     * have been set. In that array, the element that represents the values
2446     * set with this method will itself be an array. The first element of that array
2447     * is the given <code>Object</code> instance, and the
2448     * second element is the value set for <i>targetSqlType</i>. The
2449     * third element is the value set for <i>scale</i>, which the driver will
2450     * ignore if the type of the object being set is not
2451     * <code>java.sql.Types.NUMERIC</code> or <code>java.sql.Types.DECIMAL</code>.
2452     * The parameter number is indicated by an element's position in the array
2453     * returned by the method <code>getParams</code>,
2454     * with the first element being the value for the first placeholder parameter, the
2455     * second element being the value for the second placeholder parameter, and so on.
2456     * In other words, if the object being set is the value for the second
2457     * placeholder parameter, the array containing it will be the second element in
2458     * the array returned by <code>getParams</code>.
2459     *<P>
2460     * Note that because the numbering of elements in an array starts at zero,
2461     * the array element that corresponds to placeholder parameter number
2462     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2463     *
2464     *
2465     * @param parameterIndex the ordinal number of the placeholder parameter
2466     * in this <code>RowSet</code> object's command that is to be set.
2467     * The first parameter is 1, the second is 2, and so on; must be
2468     * <code>1</code> or greater
2469     * @param x the <code>Object</code> containing the input parameter value;
2470     * must be an <code>Object</code> type
2471     * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
2472     * to be sent to the database. The <code>scale</code> argument may
2473     * further qualify this type. If a non-standard <i>targetSqlType</i>
2474     * is supplied, this method will not throw a <code>SQLException</code>.
2475     * This allows implicit support for non-standard SQL types.
2476     * @param scale for the types <code>java.sql.Types.DECIMAL</code> and
2477     * <code>java.sql.Types.NUMERIC</code>, this is the number
2478     * of digits after the decimal point. For all other types, this
2479     * value will be ignored.
2480     * @throws SQLException if an error occurs or the parameter index is out of bounds
2481     * @see #getParams
2482     */

2483    public void setObject(int parameterIndex, Object JavaDoc x, int targetSqlType, int scale) throws SQLException {
2484        Object JavaDoc obj[];
2485        checkParamIndex(parameterIndex);
2486
2487        obj = new Object JavaDoc[3];
2488        obj[0] = x;
2489        obj[1] = new Integer JavaDoc(targetSqlType);
2490        obj[2] = new Integer JavaDoc(scale);
2491        if(params == null){
2492             throw new SQLException("Set initParams() before setObject");
2493        }
2494        params.put(new Integer JavaDoc(parameterIndex - 1), obj);
2495    }
2496
2497    /**
2498     * Sets the value of the designated parameter with the given
2499     * <code>Object</code> value.
2500     * This method is like <code>setObject(int parameterIndex, Object x, int
2501     * targetSqlType, int scale)</code> except that it assumes a scale of zero.
2502     * <P>
2503     * The parameter value set by this method is stored internally and
2504     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2505     * object's command when the method <code>execute</code> is called.
2506     * Methods such as <code>execute</code> and <code>populate</code></code> must be
2507     * provided in any class that extends this class and implements one or
2508     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2509     * <P>
2510     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2511     * as it is undefined in this class.
2512     * <P>
2513     * Calls made to the method <code>getParams</code> after this version of
2514     * <code>setObject</code>
2515     * has been called will return an array containing the parameter values that
2516     * have been set. In that array, the element that represents the values
2517     * set with this method will itself be an array. The first element of that array
2518     * is the given <code>Object</code> instance.
2519     * The second element is the value set for <i>targetSqlType</i>.
2520     * The parameter number is indicated by an element's position in the array
2521     * returned by the method <code>getParams</code>,
2522     * with the first element being the value for the first placeholder parameter, the
2523     * second element being the value for the second placeholder parameter, and so on.
2524     * In other words, if the object being set is the value for the second
2525     * placeholder parameter, the array containing it will be the second element in
2526     * the array returned by <code>getParams</code>.
2527     * <P>
2528     * Note that because the numbering of elements in an array starts at zero,
2529     * the array element that corresponds to placeholder parameter number
2530     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2531     *
2532     * @param parameterIndex the ordinal number of the placeholder parameter
2533     * in this <code>RowSet</code> object's command that is to be set.
2534     * The first parameter is 1, the second is 2, and so on; must be
2535     * <code>1</code> or greater
2536     * @param x the <code>Object</code> containing the input parameter value;
2537     * must be an <code>Object</code> type
2538     * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
2539     * to be sent to the database. If a non-standard <i>targetSqlType</i>
2540     * is supplied, this method will not throw a <code>SQLException</code>.
2541     * This allows implicit support for non-standard SQL types.
2542     * @throws SQLException if an error occurs or the parameter index
2543     * is out of bounds
2544     * @see #getParams
2545     */

2546    public void setObject(int parameterIndex, Object JavaDoc x, int targetSqlType) throws SQLException {
2547        Object JavaDoc obj[];
2548        checkParamIndex(parameterIndex);
2549
2550        obj = new Object JavaDoc[2];
2551        obj[0] = x;
2552        obj[1] = new Integer JavaDoc(targetSqlType);
2553        if (params == null){
2554             throw new SQLException("Set initParams() before setObject");
2555        }
2556        params.put(new Integer JavaDoc(parameterIndex - 1), obj);
2557    }
2558
2559    /**
2560     * Sets the designated parameter to an <code>Object</code> in the Java
2561     * programming language. The second parameter must be an
2562     * <code>Object</code>
2563     * type. For integral values, the <code>java.lang</code> equivalent
2564     * objects should be used. For example, use the class <code>Integer</code>
2565     * for an <code>int</code>.
2566     * <P>
2567     * The JDBC specification defines a standard mapping from
2568     * Java <code>Object</code> types to SQL types. The driver will
2569     * use this standard mapping to convert the given object
2570     * to its corresponding SQL type before sending it to the database.
2571     * If the object has a custom mapping (is of a class implementing
2572     * <code>SQLData</code>), the driver should call the method
2573     * <code>SQLData.writeSQL</code> to write the object to the SQL
2574     * data stream.
2575     * <P>
2576     * If, on the other hand, the object is of a class
2577     * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2578     * <code>Struct</code>, or <code>Array</code>,
2579     * the driver should pass it to the database as a value of the
2580     * corresponding SQL type.
2581     * <P>
2582     * This method throws an exception if there
2583     * is an ambiguity, for example, if the object is of a class
2584     * implementing more than one interface.
2585     * <P>
2586     * Note that this method may be used to pass database-specific
2587     * abstract data types.
2588     * <P>
2589     * The parameter value set by this method is stored internally and
2590     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2591     * object's command when the method <code>execute</code> is called.
2592     * Methods such as <code>execute</code> and <code>populate</code> must be
2593     * provided in any class that extends this class and implements one or
2594     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2595     * <p>
2596     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2597     * as it is undefined in this class.
2598     * <P>
2599     * After this method has been called, a call to the
2600     * method <code>getParams</code>
2601     * will return an object array of the current command parameters, which will
2602     * include the <code>Object</code> set for placeholder parameter number
2603     * <code>parameterIndex</code>.
2604     * Note that because the numbering of elements in an array starts at zero,
2605     * the array element that corresponds to placeholder parameter number
2606     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2607     *
2608     * @param parameterIndex the ordinal number of the placeholder parameter
2609     * in this <code>RowSet</code> object's command that is to be set.
2610     * The first parameter is 1, the second is 2, and so on; must be
2611     * <code>1</code> or greater
2612     * @param x the object containing the input parameter value
2613     * @throws SQLException if an error occurs the
2614     * parameter index is out of bounds, or there
2615     * is ambiguity in the implementation of the
2616     * object being set
2617     * @see #getParams
2618     */

2619    public void setObject(int parameterIndex, Object JavaDoc x) throws SQLException {
2620        checkParamIndex(parameterIndex);
2621        if (params == null) {
2622             throw new SQLException("Set initParams() before setObject");
2623        }
2624        params.put(new Integer JavaDoc(parameterIndex - 1), x);
2625    }
2626
2627    /**
2628     * Sets the designated parameter to the given <code>Ref</code> object in
2629     * the Java programming language. The driver converts this to an SQL
2630     * <code>REF</code> value when it sends it to the database. Internally, the
2631     * <code>Ref</code> is represented as a <code>SerialRef</code> to ensure
2632     * serializability.
2633     * <P>
2634     * The parameter value set by this method is stored internally and
2635     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2636     * object's command when the method <code>execute</code> is called.
2637     * Methods such as <code>execute</code> and <code>populate</code> must be
2638     * provided in any class that extends this class and implements one or
2639     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2640     * <p>
2641     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2642     * as it is undefined in this class.
2643     * <p>
2644     * After this method has been called, a call to the
2645     * method <code>getParams</code>
2646     * will return an object array of the current command parameters, which will
2647     * include the <code>Ref</code> object set for placeholder parameter number
2648     * <code>parameterIndex</code>.
2649     * Note that because the numbering of elements in an array starts at zero,
2650     * the array element that corresponds to placeholder parameter number
2651     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2652     *
2653     * @param parameterIndex the ordinal number of the placeholder parameter
2654     * in this <code>RowSet</code> object's command that is to be set.
2655     * The first parameter is 1, the second is 2, and so on; must be
2656     * <code>1</code> or greater
2657     * @param ref a <code>Ref</code> object representing an SQL <code>REF</code>
2658     * value; cannot be null
2659     * @throws SQLException if an error occurs; the parameter index is out of
2660     * bounds or the <code>Ref</code> object is <code>null</code>; or
2661     * the <code>Ref</code> object returns a <code>null</code> base type
2662     * name.
2663     * @see #getParams
2664     * @see javax.sql.rowset.serial.SerialRef
2665     */

2666    public void setRef (int parameterIndex, Ref ref) throws SQLException {
2667        checkParamIndex(parameterIndex);
2668        if (params == null) {
2669             throw new SQLException("Set initParams() before setRef");
2670        }
2671        params.put(new Integer JavaDoc(parameterIndex - 1), new SerialRef(ref));
2672    }
2673
2674    /**
2675     * Sets the designated parameter to the given <code>Blob</code> object in
2676     * the Java programming language. The driver converts this to an SQL
2677     * <code>BLOB</code> value when it sends it to the database. Internally,
2678     * the <code>Blob</code> is represented as a <code>SerialBlob</code>
2679     * to ensure serializability.
2680     * <P>
2681     * The parameter value set by this method is stored internally and
2682     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2683     * object's command when the method <code>execute</code> is called.
2684     * Methods such as <code>execute</code> and <code>populate</code> must be
2685     * provided in any class that extends this class and implements one or
2686     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2687     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2688     * as it is undefined in this class.
2689     * <p>
2690     * After this method has been called, a call to the
2691     * method <code>getParams</code>
2692     * will return an object array of the current command parameters, which will
2693     * include the <code>Blob</code> object set for placeholder parameter number
2694     * <code>parameterIndex</code>.
2695     * Note that because the numbering of elements in an array starts at zero,
2696     * the array element that corresponds to placeholder parameter number
2697     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2698     *
2699     * @param parameterIndex the ordinal number of the placeholder parameter
2700     * in this <code>RowSet</code> object's command that is to be set.
2701     * The first parameter is 1, the second is 2, and so on; must be
2702     * <code>1</code> or greater
2703     * @param x a <code>Blob</code> object representing an SQL
2704     * <code>BLOB</code> value
2705     * @throws SQLException if an error occurs or the
2706     * parameter index is out of bounds
2707     * @see #getParams
2708     * @see javax.sql.rowset.serial.SerialBlob
2709     */

2710    public void setBlob (int parameterIndex, Blob x) throws SQLException {
2711        checkParamIndex(parameterIndex);
2712        if(params == null){
2713             throw new SQLException("Set initParams() before setBlob");
2714        }
2715        params.put(new Integer JavaDoc(parameterIndex - 1), new SerialBlob(x));
2716    }
2717
2718    /**
2719     * Sets the designated parameter to the given <code>Clob</code> object in
2720     * the Java programming language. The driver converts this to an SQL
2721     * <code>CLOB</code> value when it sends it to the database. Internally, the
2722     * <code>Clob</code> is represented as a <code>SerialClob</code> to ensure
2723     * serializability.
2724     * <P>
2725     * The parameter value set by this method is stored internally and
2726     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2727     * object's command when the method <code>execute</code> is called.
2728     * Methods such as <code>execute</code> and <code>populate</code> must be
2729     * provided in any class that extends this class and implements one or
2730     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2731     * <p>
2732     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2733     * as it is undefined in this class.
2734     * <p>
2735     * After this method has been called, a call to the
2736     * method <code>getParams</code>
2737     * will return an object array of the current command parameters, which will
2738     * include the <code>Clob</code> object set for placeholder parameter number
2739     * <code>parameterIndex</code>.
2740     * Note that because the numbering of elements in an array starts at zero,
2741     * the array element that corresponds to placeholder parameter number
2742     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2743     *
2744     * @param parameterIndex the ordinal number of the placeholder parameter
2745     * in this <code>RowSet</code> object's command that is to be set.
2746     * The first parameter is 1, the second is 2, and so on; must be
2747     * <code>1</code> or greater
2748     * @param x a <code>Clob</code> object representing an SQL
2749     * <code>CLOB</code> value; cannot be null
2750     * @throws SQLException if an error occurs; the parameter index is out of
2751     * bounds or the <code>Clob</code> is null
2752     * @see #getParams
2753     * @see javax.sql.rowset.serial.SerialBlob
2754     */

2755    public void setClob (int parameterIndex, Clob x) throws SQLException {
2756        checkParamIndex(parameterIndex);
2757        if(params == null){
2758             throw new SQLException("Set initParams() before setClob");
2759        }
2760        params.put(new Integer JavaDoc(parameterIndex - 1), new SerialClob(x));
2761    }
2762
2763    /**
2764     * Sets the designated parameter to an <code>Array</code> object in the
2765     * Java programming language. The driver converts this to an SQL
2766     * <code>ARRAY</code> value when it sends it to the database. Internally,
2767     * the <code>Array</code> is represented as a <code>SerialArray</code>
2768     * to ensure serializability.
2769     * <P>
2770     * The parameter value set by this method is stored internally and
2771     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2772     * object's command when the method <code>execute</code> is called.
2773     * Methods such as <code>execute</code> and <code>populate</code> must be
2774     * provided in any class that extends this class and implements one or
2775     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2776     * <P>
2777     * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2778     * as it is undefined in this class.
2779     * <p>
2780     * After this method has been called, a call to the
2781     * method <code>getParams</code>
2782     * will return an object array of the current command parameters, which will
2783     * include the <code>Array</code> object set for placeholder parameter number
2784     * <code>parameterIndex</code>.
2785     * Note that because the numbering of elements in an array starts at zero,
2786     * the array element that corresponds to placeholder parameter number
2787     * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2788     *
2789     * @param parameterIndex the ordinal number of the placeholder parameter
2790     * in this <code>RowSet</code> object's command that is to be set.
2791     * The first parameter is 1, the second is 2, and so on; must be
2792     * <code>1</code> or greater
2793     * @param array an <code>Array</code> object representing an SQL
2794     * <code>ARRAY</code> value; cannot be null. The <code>Array</code> object
2795     * passed to this method must return a non-null Object for all
2796     * <code>getArray()</code> method calls.
2797     * @throws SQLException if an error occurs; the parameter index is out of
2798     * bounds or the <code>ARRAY</code> is null
2799     * @see #getParams
2800     * @see javax.sql.rowset.serial.SerialArray
2801     */

2802    public void setArray (int parameterIndex, Array array) throws SQLException {
2803        checkParamIndex(parameterIndex);
2804        if (params == null){
2805             throw new SQLException("Set initParams() before setArray");
2806        }
2807        params.put(new Integer JavaDoc(parameterIndex - 1), new SerialArray(array));
2808    }
2809
2810    /**
2811     * Sets the designated parameter to the given <code>java.sql.Date</code>
2812     * object.
2813     * When the DBMS does not store time zone information, the driver will use
2814     * the given <code>Calendar</code> object to construct the SQL <code>DATE</code>
2815     * value to send to the database. With a
2816     * <code>Calendar</code> object, the driver can calculate the date
2817     * taking into account a custom time zone. If no <code>Calendar</code>
2818     * object is specified, the driver uses the time zone of the Virtual Machine
2819     * that is running the application.
2820     * <P>
2821     * The parameter value set by this method is stored internally and
2822     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2823     * object's command when the method <code>execute</code> is called.
2824     * Methods such as <code>execute</code> and <code>populate</code> must be
2825     * provided in any class that extends this class and implements one or
2826     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2827     * <P>
2828     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2829     * as it is undefined in this class.
2830     * <P>
2831     * Calls made to the method <code>getParams</code> after this version of
2832     * <code>setDate</code>
2833     * has been called will return an array containing the parameter values that
2834     * have been set. In that array, the element that represents the values
2835     * set with this method will itself be an array. The first element of that array
2836     * is the given <code>java.sql.Date</code> object.
2837     * The second element is the value set for <i>cal</i>.
2838     * The parameter number is indicated by an element's position in the array
2839     * returned by the method <code>getParams</code>,
2840     * with the first element being the value for the first placeholder parameter, the
2841     * second element being the value for the second placeholder parameter, and so on.
2842     * In other words, if the date being set is the value for the second
2843     * placeholder parameter, the array containing it will be the second element in
2844     * the array returned by <code>getParams</code>.
2845     * <P>
2846     * Note that because the numbering of elements in an array starts at zero,
2847     * the array element that corresponds to placeholder parameter number
2848     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2849     *
2850     * @param parameterIndex the ordinal number of the placeholder parameter
2851     * in this <code>RowSet</code> object's command that is to be set.
2852     * The first parameter is 1, the second is 2, and so on; must be
2853     * <code>1</code> or greater
2854     * @param x a <code>java.sql.Date</code> object representing an SQL
2855     * <code>DATE</code> value
2856     * @param cal a <code>java.util.Calendar</code> object to use when
2857     * when constructing the date
2858     * @throws SQLException if an error occurs or the
2859     * parameter index is out of bounds
2860     * @see #getParams
2861     */

2862    public void setDate(int parameterIndex, java.sql.Date JavaDoc x, Calendar cal) throws SQLException {
2863        Object JavaDoc date[];
2864        checkParamIndex(parameterIndex);
2865        
2866        date = new Object JavaDoc[2];
2867        date[0] = x;
2868        date[1] = cal;
2869        if(params == null){
2870             throw new SQLException("Set initParams() before setDate");
2871        }
2872        params.put(new Integer JavaDoc(parameterIndex - 1), date);
2873    }
2874
2875    /**
2876     * Sets the designated parameter to the given <code>java.sql.Time</code>
2877     * object. The driver converts this
2878     * to an SQL <code>TIME</code> value when it sends it to the database.
2879     * <P>
2880     * When the DBMS does not store time zone information, the driver will use
2881     * the given <code>Calendar</code> object to construct the SQL <code>TIME</code>
2882     * value to send to the database. With a
2883     * <code>Calendar</code> object, the driver can calculate the date
2884     * taking into account a custom time zone. If no <code>Calendar</code>
2885     * object is specified, the driver uses the time zone of the Virtual Machine
2886     * that is running the application.
2887     * <P>
2888     * The parameter value set by this method is stored internally and
2889     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2890     * object's command when the method <code>execute</code> is called.
2891     * Methods such as <code>execute</code> and <code>populate</code> must be
2892     * provided in any class that extends this class and implements one or
2893     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2894     * <P>
2895     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2896     * as it is undefined in this class.
2897     * <P>
2898     * Calls made to the method <code>getParams</code> after this version of
2899     * <code>setTime</code>
2900     * has been called will return an array containing the parameter values that
2901     * have been set. In that array, the element that represents the values
2902     * set with this method will itself be an array. The first element of that array
2903     * is the given <code>java.sql.Time</code> object.
2904     * The second element is the value set for <i>cal</i>.
2905     * The parameter number is indicated by an element's position in the array
2906     * returned by the method <code>getParams</code>,
2907     * with the first element being the value for the first placeholder parameter, the
2908     * second element being the value for the second placeholder parameter, and so on.
2909     * In other words, if the time being set is the value for the second
2910     * placeholder parameter, the array containing it will be the second element in
2911     * the array returned by <code>getParams</code>.
2912     * <P>
2913     * Note that because the numbering of elements in an array starts at zero,
2914     * the array element that corresponds to placeholder parameter number
2915     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2916     *
2917     * @param parameterIndex the ordinal number of the placeholder parameter
2918     * in this <code>RowSet</code> object's command that is to be set.
2919     * The first parameter is 1, the second is 2, and so on; must be
2920     * <code>1</code> or greater
2921     * @param x a <code>java.sql.Time</code> object
2922     * @param cal the <code>java.util.Calendar</code> object the driver can use to
2923     * construct the time
2924     * @throws SQLException if an error occurs or the
2925     * parameter index is out of bounds
2926     * @see #getParams
2927     */

2928    public void setTime(int parameterIndex, java.sql.Time JavaDoc x, Calendar cal) throws SQLException {
2929        Object JavaDoc time[];
2930        checkParamIndex(parameterIndex);
2931        
2932        time = new Object JavaDoc[2];
2933        time[0] = x;
2934        time[1] = cal;
2935        if(params == null){
2936             throw new SQLException("Set initParams() before setTime");
2937        }
2938        params.put(new Integer JavaDoc(parameterIndex - 1), time);
2939    }
2940
2941    /**
2942     * Sets the designated parameter to the given
2943     * <code>java.sql.Timestamp</code> object. The driver converts this
2944     * to an SQL <code>TIMESTAMP</code> value when it sends it to the database.
2945     * <P>
2946     * When the DBMS does not store time zone information, the driver will use
2947     * the given <code>Calendar</code> object to construct the SQL <code>TIMESTAMP</code>
2948     * value to send to the database. With a
2949     * <code>Calendar</code> object, the driver can calculate the timestamp
2950     * taking into account a custom time zone. If no <code>Calendar</code>
2951     * object is specified, the driver uses the time zone of the Virtual Machine
2952     * that is running the application.
2953     * <P>
2954     * The parameter value set by this method is stored internally and
2955     * will be supplied as the appropriate parameter in this <code>RowSet</code>
2956     * object's command when the method <code>execute</code> is called.
2957     * Methods such as <code>execute</code> and <code>populate</code> must be
2958     * provided in any class that extends this class and implements one or
2959     * more of the standard JSR-114 <code>RowSet</code> interfaces.
2960     * <P>
2961     * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2962     * as it is undefined in this class.
2963     * <P>
2964     * Calls made to the method <code>getParams</code> after this version of
2965     * <code>setTimestamp</code>
2966     * has been called will return an array containing the parameter values that
2967     * have been set. In that array, the element that represents the values
2968     * set with this method will itself be an array. The first element of that array
2969     * is the given <code>java.sql.Timestamp</code> object.
2970     * The second element is the value set for <i>cal</i>.
2971     * The parameter number is indicated by an element's position in the array
2972     * returned by the method <code>getParams</code>,
2973     * with the first element being the value for the first placeholder parameter, the
2974     * second element being the value for the second placeholder parameter, and so on.
2975     * In other words, if the timestamp being set is the value for the second
2976     * placeholder parameter, the array containing it will be the second element in
2977     * the array returned by <code>getParams</code>.
2978     * <P>
2979     * Note that because the numbering of elements in an array starts at zero,
2980     * the array element that corresponds to placeholder parameter number
2981     * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2982     *
2983     * @param parameterIndex the ordinal number of the placeholder parameter
2984     * in this <code>RowSet</code> object's command that is to be set.
2985     * The first parameter is 1, the second is 2, and so on; must be
2986     * <code>1</code> or greater
2987     * @param x a <code>java.sql.Timestamp</code> object
2988     * @param cal the <code>java.util.Calendar</code> object the driver can use to
2989     * construct the timestamp
2990     * @throws SQLException if an error occurs or the
2991     * parameter index is out of bounds
2992     * @see #getParams
2993     */

2994    public void setTimestamp(int parameterIndex, java.sql.Timestamp JavaDoc x, Calendar cal) throws SQLException {
2995        Object JavaDoc timestamp[];
2996        checkParamIndex(parameterIndex);
2997
2998        timestamp = new Object JavaDoc[2];
2999        timestamp[0] = x;
3000        timestamp[1] = cal;
3001        if(params == null){
3002             throw new SQLException("Set initParams() before setTimestamp");
3003        }
3004        params.put(new Integer JavaDoc(parameterIndex - 1), timestamp);
3005    }
3006
3007    /**
3008     * Clears all of the current parameter values in this <code>RowSet</code>
3009     * object's internal representation of the parameters to be set in
3010     * this <code>RowSet</code> object's command when it is executed.
3011     * <P>
3012     * In general, parameter values remain in force for repeated use in
3013     * this <code>RowSet</code> object's command. Setting a parameter value with the
3014     * setter methods automatically clears the value of the
3015     * designated parameter and replaces it with the new specified value.
3016     * <P>
3017     * This method is called internally by the <code>setCommand</code>
3018     * method to clear all of the parameters set for the previous command.
3019     * <P>
3020     * Furthermore, this method differs from the <code>initParams</code>
3021     * method in that it maintains the schema of the <code>RowSet</code> object.
3022     *
3023     * @throws SQLException if an error occurs clearing the parameters
3024     */

3025    public void clearParameters() throws SQLException {
3026        params.clear();
3027    }
3028
3029    /**
3030     * Retrieves an array containing the parameter values (both Objects and
3031     * primitives) that have been set for this
3032     * <code>RowSet</code> object's command and throws an <code>SQLException</code> object
3033     * if all parameters have not been set. Before the command is sent to the
3034     * DBMS to be executed, these parameters will be substituted
3035     * for placeholder parameters in the <code>PreparedStatement</code> object
3036     * that is the command for a <code>RowSet</code> implementation extending
3037     * the <code>BaseRowSet</code> class.
3038     * <P>
3039     * Each element in the array that is returned is an <code>Object</code> instance
3040     * that contains the values of the parameters supplied to a setter method.
3041     * The order of the elements is determined by the value supplied for
3042     * <i>parameterIndex</i>. If the setter method takes only the parameter index
3043     * and the value to be set (possibly null), the array element will contain the value to be set
3044     * (which will be expressed as an <code>Object</code>). If there are additional
3045     * parameters, the array element will itself be an array containing the value to be set
3046     * plus any additional parameter values supplied to the setter method. If the method
3047     * sets a stream, the array element includes the type of stream being supplied to the
3048     * method. These additional parameters are for the use of the driver or the DBMS and may or
3049     * may not be used.
3050     * <P>
3051     * NOTE: Stored parameter values of types <code>Array</code>, <code>Blob</code>,
3052     * <code>Clob</code> and <code>Ref</code> are returned as <code>SerialArray</code>,
3053     * <code>SerialBlob</code>, <code>SerialClob</code> and <code>SerialRef</code>
3054     * respectively.
3055     *
3056     * @return an array of <code>Object</code> instances that includes the
3057     * parameter values that may be set in this <code>RowSet</code> object's
3058     * command; an empty array if no parameters have been set
3059     * @throws SQLException if an error occurs retrieveing the object array of
3060     * parameters of this <code>RowSet</code> object or if not all parameters have
3061     * been set
3062     */

3063    public Object JavaDoc[] getParams() throws SQLException {
3064        if (params == null) {
3065                    
3066            initParams();
3067            Object JavaDoc [] paramsArray = new Object JavaDoc[params.size()];
3068            return paramsArray;
3069            
3070        } else {
3071            // The parameters may be set in random order
3072
// but all must be set, check to verify all
3073
// have been set till the last parameter
3074
// else throw exception.
3075

3076            Object JavaDoc[] paramsArray = new Object JavaDoc[params.size()];
3077            for (int i = 0; i < params.size(); i++) {
3078               paramsArray[i] = params.get(new Integer JavaDoc(i));
3079               if (paramsArray[i] == null) {
3080                 throw new SQLException("missing parameter: " + (i + 1));
3081               } //end if
3082
} //end for
3083
return paramsArray;
3084
3085        } //end if
3086

3087    } //end getParams
3088

3089    static final long serialVersionUID = 4886719666485113312L;
3090 
3091} //end class
3092

3093
Popular Tags