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. package javax.sql.rowset;
  8. import java.sql.*;
  9. import javax.sql.*;
  10. import java.util.*;
  11. import java.io.*;
  12. import java.io.Serializable;
  13. import javax.sql.rowset.serial.*;
  14. /**
  15. * An abstract class providing a <code>RowSet</code> object with its basic functionality.
  16. * The basic functions include having properties and sending event notifications,
  17. * which all JavaBeans<sup><font size=-2>TM</font></sup> components must implement.
  18. * <P>
  19. * <h3>1.0 Overview</h3>
  20. * The <code>BaseRowSet</code> class provides the core functionality
  21. * for all <code>RowSet</code> implementations,
  22. * and all standard implementations <b>may</b> use this class in combination with
  23. * one or more <code>RowSet</code> interfaces in order to provide a standard
  24. * vendor-specific implementation. To clarify, all implementations must implement
  25. * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,
  26. * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,
  27. * or <code>WebRowSet</code>). This means that any implementation that extends
  28. * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>
  29. * interfaces.
  30. * <p>
  31. * The <code>BaseRowSet</code> class provides the following:
  32. * <p>
  33. * <UL>
  34. * <LI><b>Properties</b>
  35. * <ul>
  36. * <li>Fields for storing current properties
  37. * <li>Methods for getting and setting properties
  38. * </ul>
  39. * <p>
  40. * <LI><b>Event notification</b>
  41. * <P>
  42. * <LI><b>A complete set of setter methods</b> for setting the parameters in a
  43. * <code>RowSet</code> object's command
  44. * <p>
  45. * <LI> <b>Streams</b>
  46. * <ul>
  47. * <li>Fields for storing stream instances
  48. * <li>Constants for indicating the type of a stream
  49. * </ul>
  50. * <p>
  51. * </UL>
  52. *
  53. * <h3>2.0 Setting Properties</h3>
  54. * All rowsets maintain a set of properties, which will usually be set using
  55. * a tool. The number and kinds of properties a rowset has will vary,
  56. * depending on what the <code>RowSet</code> implementation does and how it gets
  57. * its data. For example,
  58. * rowsets that get their data from a <code>ResultSet</code> object need to
  59. * set the properties that are required for making a database connection.
  60. * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a
  61. * connection, it needs to set a property for the JDBC URL that identifies the
  62. * appropriate driver, and it needs to set the properties that give the
  63. * user name and password.
  64. * If, on the other hand, the rowset uses a <code>DataSource</code> object
  65. * to make the connection, which is the preferred method, it does not need to
  66. * set the property for the JDBC URL. Instead, it needs to set the property
  67. * for the logical name of the data source along with the properties for
  68. * the user name and password.
  69. * <P>
  70. * NOTE: In order to use a <code>DataSource</code> object for making a
  71. * connection, the <code>DataSource</code> object must have been registered
  72. * with a naming service that uses the Java Naming and Directory
  73. * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
  74. * is usually done by a person acting in the capacity of a system administrator.
  75. * <P>
  76. * <h3>3.0 Setting the Command and Its Parameters</h3>
  77. * When a rowset gets its data from a relational database, it executes a command (a query)
  78. * that produces a <code>ResultSet</code> object. This query is the command that is set
  79. * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
  80. * data from the <code>ResultSet</code> object into itself. If the query
  81. * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
  82. * are used to set these values. All setter methods allow these values to be set
  83. * to <code>null</code> if required.
  84. * <P>
  85. * The following code fragment illustrates how the
  86. * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
  87. * object <code>crs</code> might have its command property set. Note that if a
  88. * tool is used to set properties, this is the code that the tool would use.
  89. * <PRE>
  90. * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
  91. * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
  92. * </PRE>
  93. * <P>
  94. * In this example, the values for <code>CREDIT_LIMIT</code> and
  95. * <code>REGION</code> are placeholder parameters, which are indicated with a
  96. * question mark (?). The first question mark is placeholder parameter number
  97. * <code>1</code>, the second question mark is placeholder parameter number
  98. * <code>2</code>, and so on. Any placeholder parameters must be set with
  99. * values before the query can be executed. To set these
  100. * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
  101. * methods, similar to those provided by the <code>PreparedStatement</code>
  102. * interface, for setting values of each data type. A <code>RowSet</code> object stores the
  103. * parameter values internally, and its <code>execute</code> method uses them internally
  104. * to set values for the placeholder parameters
  105. * before it sends the command to the DBMS to be executed.
  106. * <P>
  107. * The following code fragment demonstrates
  108. * setting the two parameters in the query from the previous example.
  109. * <PRE>
  110. * crs.setInt(1, 5000);
  111. * crs.setString(2, "West");
  112. * </PRE>
  113. * If the <code>execute</code> method is called at this point, the query
  114. * sent to the DBMS will be:
  115. * <PRE>
  116. * "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
  117. * "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
  118. * </PRE>
  119. * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and
  120. * <code>Ref</code> objects as a command parameter, stores these values as
  121. * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>
  122. * and <code>SerialRef</code> objects respectively.
  123. *
  124. * <h3>4.0 Handling of Parameters Behind the Scenes</h3>
  125. *
  126. * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,
  127. * those that set properties and those that set placeholder parameters. The setter
  128. * methods discussed in this section are those that set placeholder parameters.
  129. * <P>
  130. * The placeholder parameters set with the <code>BaseRowSet</code> setter methods
  131. * are stored as objects in an internal <code>Hashtable</code> object.
  132. * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>
  133. * is stored as <code>Byte</code> object, and <code>int</code> is stored as
  134. * an <code>Integer</code> object.
  135. * When the method <code>execute</code> is called, the values in the
  136. * <code>Hashtable</code> object are substituted for the appropriate placeholder
  137. * parameters in the command.
  138. * <P)>
  139. * A call to the method <code>getParams</code> returns the values stored in the
  140. * <code>Hashtable</code> object as an array of <code>Object</code> instances.
  141. * An element in this array may be a simple <code>Object</code> instance or an
  142. * array (which is a type of <code>Object</code>). The particular setter method used
  143. * determines whether an element in this array is an <code>Object</code> or an array.
  144. * <P>
  145. * The majority of methods for setting placeholder parameters take two parameters,
  146. * with the first parameter
  147. * indicating which placeholder parameter is to be set, and the second parameter
  148. * giving the value to be set. Methods such as <code>getInt</code>,
  149. * <code>getString</code>, <code>getBoolean</code>, and <code>getLong</code> fall into
  150. * this category. After these methods have been called, a call to the method
  151. * <code>getParams</code> will return an array with the values that have been set. Each
  152. * element in the array is an <code>Object</code> instance representing the
  153. * values that have been set. The order of these values in the array is determined by the
  154. * <code>int</code> (the first parameter) passed to the setter method. The values in the
  155. * array are the values (the second parameter) passed to the setter method.
  156. * In other words, the first element in the array is the value
  157. * to be set for the first placeholder parameter in the <code>RowSet</code> object's
  158. * command. The second element is the value to
  159. * be set for the second placeholder parameter, and so on.
  160. * <P>
  161. * Several setter methods send the driver and DBMS information beyond the value to be set.
  162. * When the method <code>getParams</code> is called after one of these setter methods has
  163. * been used, the elements in the array will themselves be arrays to accommodate the
  164. * additional information. In this category, the method <code>setNull</code> is a special case
  165. * because one version takes only
  166. * two parameters (<code>setNull(int parameterIndex, int SqlType)</code>). Nevertheless,
  167. * it requires
  168. * an array to contain the information that will be passed to the driver and DBMS. The first
  169. * element in this array is the value to be set, which is <code>null</code>, and the
  170. * second element is the <code>int</code> supplied for <i>sqlType</i>, which
  171. * indicates the type of SQL value that is being set to <code>null</code>. This information
  172. * is needed by some DBMSs and is therefore required in order to ensure that applications
  173. * are portable.
  174. * The other version is intended to be used when the value to be set to <code>null</code>
  175. * is a user-defined type. It takes three parameters
  176. * (<code>setNull(int parameterIndex, int sqlType, String typeName)</code>) and also
  177. * requires an array to contain the information to be passed to the driver and DBMS.
  178. * The first two elements in this array are the same as for the first version of
  179. * <code>setNull</code>. The third element, <i>typeName</i>, gives the SQL name of
  180. * the user-defined type. As is true with the other setter methods, the number of the
  181. * placeholder parameter to be set is indicated by an element's position in the array
  182. * returned by <code>getParams</code>. So, for example, if the parameter
  183. * supplied to <code>setNull</code> is <code>2</code>, the second element in the array
  184. * returned by <code>getParams</code> will be an array of two or three elements.
  185. * <P>
  186. * Some methods, such as <code>setObject</code> and <code>setDate</code> have versions
  187. * that take more than two parameters, with the extra parameters giving information
  188. * to the driver or the DBMS. For example, the methods <code>setDate</code>,
  189. * <code>setTime</code>, and <code>setTimestamp</code> can take a <code>Calendar</code>
  190. * object as their third parameter. If the DBMS does not store time zone information,
  191. * the drivern uses the <code>Calendar</code> object to construct the <code>Date</code>,
  192. * <code>Time</code>, or <code>Timestamp</code> object being set. As is true with other
  193. * methods that provide additional information, the element in the array returned
  194. * by <code>getParams</code> is an array instead of a simple <code>Object</code> instance.
  195. * <P>
  196. * The methods <code>setAsciiStream</code>, <code>setBinaryStream</code>,
  197. * <code>setCharacterStream</code>, and <code>setUnicodeStream</code> (which is
  198. * deprecated, so applications should use <code>getCharacterStream</code> instead)
  199. * take three parameters, so for them, the element in the array returned by
  200. * <code>getParams</code> is also an array. What is different about these setter
  201. * methods is that in addition to the information provided by parameters, the array contains
  202. * one of the <code>BaseRowSet</code> constants indicating the type of stream being set.
  203. * <p>
  204. * NOTE: The method <code>getParams</code> is called internally by
  205. * <code>RowSet</code> implementations extending this class; it is not normally called by an
  206. * application programmer directly.
  207. *
  208. * <h3>5.0 Event Notification</h3>
  209. * The <code>BaseRowSet</code> class provides the event notification
  210. * mechanism for rowsets. It contains the field
  211. * <code>listeners</code>, methods for adding and removing listeners, and
  212. * methods for notifying listeners of changes.
  213. * <P>
  214. * A listener is an object that has implemented the <code>RowSetListener</code> interface.
  215. * If it has been added to a <code>RowSet</code> object's list of listeners, it will be notified
  216. * when an event occurs on that <code>RowSet</code> object. Each listener's
  217. * implementation of the <code>RowSetListener</code> methods defines what that object
  218. * will do when it is notified that an event has occurred.
  219. * <P>
  220. * There are three possible events for a <code>RowSet</code> object:
  221. * <OL>
  222. * <LI>the cursor moves
  223. * <LI>an individual row is changed (updated, deleted, or inserted)
  224. * <LI>the contents of the entire <code>RowSet</code> object are changed
  225. * </OL>
  226. * <P>
  227. * The <code>BaseRowSet</code> method used for the notification indicates the
  228. * type of event that has occurred. For example, the method
  229. * <code>notifyRowChanged</code> indicates that a row has been updated,
  230. * deleted, or inserted. Each of the notification methods creates a
  231. * <code>RowSetEvent</code> object, which is supplied to the listener in order to
  232. * identify the <code>RowSet</code> object on which the event occurred.
  233. * What the listener does with this information, which may be nothing, depends on how it was
  234. * implemented.
  235. * <p>
  236. * <h3>6.0 Default Behavior</h3>
  237. * A default <code>BaseRowSet</code> object is initialized with many starting values.
  238. *
  239. * The following is true of a default <code>RowSet</code> instance that extends
  240. * the <code>BaseRowSet</code> class:
  241. * <UL>
  242. * <LI>Has a scrollable cursor and does not show changes
  243. * made by others.
  244. * <LI>Is updatable.
  245. * <LI>Does not show rows that have been deleted.
  246. * <LI>Has no time limit for how long a driver may take to
  247. * execute the <code>RowSet</code> object's command.
  248. * <LI>Has no limit for the number of rows it may contain.
  249. * <LI>Has no limit for the number of bytes a column may contain. NOTE: This
  250. * limit applies only to columns that hold values of the
  251. * following types: <code>BINARY</code>, <code>VARBINARY</code>,
  252. * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
  253. * and <code>LONGVARCHAR</code>.
  254. * <LI>Will not see uncommitted data (make "dirty" reads).
  255. * <LI>Has escape processing turned on.
  256. * <LI>Has its connection's type map set to <code>null</code>.
  257. * <LI>Has an empty <code>Vector</code> object for storing the values set
  258. * for the placeholder parameters in the <code>RowSet</code> object's command.
  259. * </UL>
  260. * <p>
  261. * If other values are desired, an application must set the property values
  262. * explicitly. For example, the following line of code sets the maximum number
  263. * of rows for the <code>CachedRowSet</code> object <i>crs</i> to 500.
  264. * <PRE>
  265. * crs.setMaxRows(500);
  266. * </PRE>
  267. * Methods implemented in extensions of this <code>BaseRowSet</code> class <b>must</b> throw an
  268. * <code>SQLException</code> object for any violation of the defined assertions. Also, if the
  269. * extending class overrides and reimplements any <code>BaseRowSet</code> method and encounters
  270. * connectivity or underlying data source issues, that method <b>may</b> in addition throw an
  271. * <code>SQLException</code> object for that reason.
  272. */
  273. public abstract class BaseRowSet implements Serializable, Cloneable {
  274. /**
  275. * A constant indicating to a <code>RowSetReaderImpl</code> object
  276. * that a given parameter is a Unicode stream. This
  277. * <code>RowSetReaderImpl</code> object is provided as an extension of the
  278. * <code>SyncProvider</code> abstract class defined in the
  279. * <code>SyncFactory</code> static factory SPI mechanism.
  280. */
  281. public static final int UNICODE_STREAM_PARAM = 0;
  282. /**
  283. * A constant indicating to a <code>RowSetReaderImpl</code> object
  284. * that a given parameter is a binary stream. A
  285. * <code>RowSetReaderImpl</code> object is provided as an extension of the
  286. * <code>SyncProvider</code> abstract class defined in the
  287. * <code>SyncFactory</code> static factory SPI mechanism.
  288. */
  289. public static final int BINARY_STREAM_PARAM = 1;
  290. /**
  291. * A constant indicating to a <code>RowSetReaderImpl</code> object
  292. * that a given parameter is an ASCII stream. A
  293. * <code>RowSetReaderImpl</code> object is provided as an extension of the
  294. * <code>SyncProvider</code> abstract class defined in the
  295. * <code>SyncFactory</code> static factory SPI mechanism.
  296. */
  297. public static final int ASCII_STREAM_PARAM = 2;
  298. /**
  299. * The <code>InputStream</code> object that will be
  300. * returned by the method <code>getBinaryStream</code>, which is
  301. * specified in the <code>ResultSet</code> interface.
  302. * @serial
  303. */
  304. protected java.io.InputStream binaryStream;
  305. /**
  306. * The <code>InputStream</code> object that will be
  307. * returned by the method <code>getUnicodeStream</code>,
  308. * which is specified in the <code>ResultSet</code> interface.
  309. * @serial
  310. */
  311. protected java.io.InputStream unicodeStream;
  312. /**
  313. * The <code>InputStream</code> object that will be
  314. * returned by the method <code>getAsciiStream</code>,
  315. * which is specified in the <code>ResultSet</code> interface.
  316. * @serial
  317. */
  318. protected java.io.InputStream asciiStream;
  319. /**
  320. * The <code>Reader</code> object that will be
  321. * returned by the method <code>getCharacterStream</code>,
  322. * which is specified in the <code>ResultSet</code> interface.
  323. * @serial
  324. */
  325. protected java.io.Reader charStream;
  326. /**
  327. * The query that will be sent to the DBMS for execution when the
  328. * method <code>execute</code> is called.
  329. * @serial
  330. */
  331. private String command;
  332. /**
  333. * The JDBC URL the reader, writer, or both supply to the method
  334. * <code>DriverManager.getConnection</code> when the
  335. * <code>DriverManager</code> is used to get a connection.
  336. * <P>
  337. * The JDBC URL identifies the driver to be used to make the conndection.
  338. * This URL can be found in the documentation supplied by the driver
  339. * vendor.
  340. * @serial
  341. */
  342. private String URL;
  343. /**
  344. * The logical name of the data source that the reader/writer should use
  345. * in order to retrieve a <code>DataSource</code> object from a Java
  346. * Directory and Naming Interface (JNDI) naming service.
  347. * @serial
  348. */
  349. private String dataSource;
  350. /**
  351. * The user name the reader, writer, or both supply to the method
  352. * <code>DriverManager.getConnection</code> when the
  353. * <code>DriverManager</code> is used to get a connection.
  354. * @serial
  355. */
  356. private transient String username;
  357. /**
  358. * The password the reader, writer, or both supply to the method
  359. * <code>DriverManager.getConnection</code> when the
  360. * <code>DriverManager</code> is used to get a connection.
  361. * @serial
  362. */
  363. private transient String password;
  364. /**
  365. * A constant indicating the type of this JDBC <code>RowSet</code>
  366. * object. It must be one of the following <code>ResultSet</code>
  367. * constants: <code>TYPE_FORWARD_ONLY</code>,
  368. * <code>TYPE_SCROLL_INSENSITIVE</code>, or
  369. * <code>TYPE_SCROLL_SENSITIVE</code>.
  370. * @serial
  371. */
  372. private int rowSetType = ResultSet.TYPE_SCROLL_INSENSITIVE;
  373. /**
  374. * A <code>boolean</code> indicating whether deleted rows are visible in this
  375. * JDBC <code>RowSet</code> object .
  376. * @serial
  377. */
  378. private boolean showDeleted = false; // default is false
  379. /**
  380. * The maximum number of seconds the driver
  381. * will wait for a command to execute. This limit applies while
  382. * this JDBC <code>RowSet</code> object is connected to its data
  383. * source, that is, while it is populating itself with
  384. * data and while it is writing data back to the data source.
  385. * @serial
  386. */
  387. private int queryTimeout = 0; // default is no timeout
  388. /**
  389. * The maximum number of rows the reader should read.
  390. * @serial
  391. */
  392. private int maxRows = 0; // default is no limit
  393. /**
  394. * The maximum field size the reader should read.
  395. * @serial
  396. */
  397. private int maxFieldSize = 0; // default is no limit
  398. /**
  399. * A constant indicating the concurrency of this JDBC <code>RowSet</code>
  400. * object. It must be one of the following <code>ResultSet</code>
  401. * constants: <code>CONCUR_READ_ONLY</code> or
  402. * <code>CONCUR_UPDATABLE</code>.
  403. * @serial
  404. */
  405. private int concurrency = ResultSet.CONCUR_UPDATABLE;
  406. /**
  407. * A <code>boolean</code> indicating whether this JDBC <code>RowSet</code>
  408. * object is read-only. <code>true</code> indicates that it is read-only;
  409. * <code>false</code> that it is writable.
  410. * @serial
  411. */
  412. private boolean readOnly;
  413. /**
  414. * A <code>boolean</code> indicating whether the reader for this
  415. * JDBC <code>RowSet</code> object should perform escape processing.
  416. * <code>true</code> means that escape processing is turned on;
  417. * <code>false</code> that it is not. The default is <code>true</code>.
  418. * @serial
  419. */
  420. private boolean escapeProcessing;
  421. /**
  422. * A constant indicating the isolation level of the connection
  423. * for this JDBC <code>RowSet</code> object . It must be one of
  424. * the following <code>Connection</code> constants:
  425. * <code>TRANSACTION_NONE</code>,
  426. * <code>TRANSACTION_READ_UNCOMMITTED</code>,
  427. * <code>TRANSACTION_READ_COMMITTED</code>,
  428. * <code>TRANSACTION_REPEATABLE_READ</code> or
  429. * <code>TRANSACTION_SERIALIZABLE</code>.
  430. * @serial
  431. */
  432. private int isolation;
  433. /**
  434. * A constant used as a hint to the driver that indicates the direction in
  435. * which data from this JDBC <code>RowSet</code> object is going
  436. * to be fetched. The following <code>ResultSet</code> constants are
  437. * possible values:
  438. * <code>FETCH_FORWARD</code>,
  439. * <code>FETCH_REVERSE</code>,
  440. * <code>FETCH_UNKNOWN</code>.
  441. * <P>
  442. * Unused at this time.
  443. * @serial
  444. */
  445. private int fetchDir = ResultSet.FETCH_FORWARD; // default fetch direction
  446. /**
  447. * A hint to the driver that indicates the expected number of rows
  448. * in this JDBC <code>RowSet</code> object .
  449. * <P>
  450. * Unused at this time.
  451. * @serial
  452. */
  453. private int fetchSize = 0; // default fetchSize
  454. /**
  455. * The <code>java.util.Map</code> object that contains entries mapping
  456. * SQL type names to classes in the Java programming language for the
  457. * custom mapping of user-defined types.
  458. * @serial
  459. */
  460. private Map map;
  461. /**
  462. * A <code>Vector</code> object that holds the list of listeners
  463. * that have registered with this <code>RowSet</code> object.
  464. * @serial
  465. */
  466. private Vector listeners;
  467. /**
  468. * A <code>Vector</code> object that holds the parameters set
  469. * for this <code>RowSet</code> object's current command.
  470. * @serial
  471. */
  472. private Hashtable params; // could be transient?
  473. /**
  474. * Constructs a new <code>BaseRowSet</code> object initialized with
  475. * a default <code>Vector</code> object for its <code>listeners</code>
  476. * field. The other default values with which it is initialized are listed
  477. * in Section 6.0 of the class comment for this class.
  478. */
  479. public BaseRowSet() {
  480. // allocate the listeners collection
  481. listeners = new Vector();
  482. }
  483. /**
  484. * Performs the necessary internal configurations and initializations
  485. * to allow any JDBC <code>RowSet</code> implementation to start using
  486. * the standard facilities provided by a <code>BaseRowSet</code>
  487. * instance. This method <b>should</b> be called after the <code>RowSet</code> object
  488. * has been instantiated to correctly initialize all parameters. This method
  489. * <b>should</b> never be called by an application, but is called from with
  490. * a <code>RowSet</code> implementation extending this class.
  491. */
  492. protected void initParams() {
  493. params = new Hashtable();
  494. }
  495. //--------------------------------------------------------------------
  496. // Events
  497. //--------------------------------------------------------------------
  498. /**
  499. * The listener will be notified whenever an event occurs on this <code>RowSet</code>
  500. * object.
  501. * <P>
  502. * A listener might, for example, be a table or graph that needs to
  503. * be updated in order to accurately reflect the current state of
  504. * the <code>RowSet</code> object.
  505. * <p>
  506. * <b>Note</b>: if the <code>RowSetListener</code> object is
  507. * <code>null</code>, this method silently discards the <code>null</code>
  508. * value and does not add a null reference to the set of listeners.
  509. * <p>
  510. * <b>Note</b>: if the listener is already set, and the new <code>RowSetListerner</code>
  511. * instance is added to the set of listeners already registered to receive
  512. * event notifications from this <code>RowSet</code>.
  513. *
  514. * @param listener an object that has implemented the
  515. * <code>javax.sql.RowSetListener</code> interface and wants to be notified
  516. * of any events that occur on this <code>RowSet</code> object; May be
  517. * null.
  518. * @see #removeRowSetListener
  519. */
  520. public void addRowSetListener(RowSetListener listener) {
  521. listeners.add(listener);
  522. }
  523. /**
  524. * Removes the designated object from this <code>RowSet</code> object's list of listeners.
  525. * If the given argument is not a registered listener, this method
  526. * does nothing.
  527. *
  528. * <b>Note</b>: if the <code>RowSetListener</code> object is
  529. * <code>null</code>, this method silently discards the <code>null</code>
  530. * value.
  531. *
  532. * @param listener a <code>RowSetListener</code> object that is on the list
  533. * of listeners for this <code>RowSet</code> object
  534. * @see #addRowSetListener
  535. */
  536. public void removeRowSetListener(RowSetListener listener) {
  537. listeners.remove(listener);
  538. }
  539. /**
  540. * Determine if instance of this class extends the RowSet interface.
  541. */
  542. private void checkforRowSetInterface() throws SQLException {
  543. if ((this instanceof javax.sql.RowSet) == false) {
  544. throw new SQLException("The class extending abstract class BaseRowSet " +
  545. "must implement javax.sql.RowSet or one of it's sub-interfaces.");
  546. }
  547. }
  548. /**
  549. * Notifies all of the listeners registered with this
  550. * <code>RowSet</code> object that its cursor has moved.
  551. * <P>
  552. * When an application calls a method to move the cursor,
  553. * that method moves the cursor and then calls this method
  554. * internally. An application <b>should</b> never invoke
  555. * this method directly.
  556. *
  557. * @throws SQLException if the class extending the <code>BaseRowSet</code>
  558. * abstract class does not implement the <code>RowSet</code> interface or
  559. * one of it's sub-interfaces.
  560. */
  561. protected void notifyCursorMoved() throws SQLException {
  562. checkforRowSetInterface();
  563. if (listeners.isEmpty() == false) {
  564. RowSetEvent event = new RowSetEvent((RowSet)this);
  565. for (Iterator i = listeners.iterator(); i.hasNext(); ) {
  566. ((RowSetListener)i.next()).cursorMoved(event);
  567. }
  568. }
  569. }
  570. /**
  571. * Notifies all of the listeners registered with this <code>RowSet</code> object that
  572. * one of its rows has changed.
  573. * <P>
  574. * When an application calls a method that changes a row, such as
  575. * the <code>CachedRowSet</code> methods <code>insertRow</code>,
  576. * <code>updateRow</code>, or <code>deleteRow</code>,
  577. * that method calls <code>notifyRowChanged</code>
  578. * internally. An application <b>should</b> never invoke
  579. * this method directly.
  580. *
  581. * @throws SQLException if the class extending the <code>BaseRowSet</code>
  582. * abstract class does not implement the <code>RowSet</code> interface or
  583. * one of it's sub-interfaces.
  584. */
  585. protected void notifyRowChanged() throws SQLException {
  586. checkforRowSetInterface();
  587. if (listeners.isEmpty() == false) {
  588. RowSetEvent event = new RowSetEvent((RowSet)this);
  589. for (Iterator i = listeners.iterator(); i.hasNext(); ) {
  590. ((RowSetListener)i.next()).rowChanged(event);
  591. }
  592. }
  593. }
  594. /**
  595. * Notifies all of the listeners registered with this <code>RowSet</code>
  596. * object that its entire contents have changed.
  597. * <P>
  598. * When an application calls methods that change the entire contents
  599. * of the <code>RowSet</code> object, such as the <code>CachedRowSet</code> methods
  600. * <code>execute</code>, <code>populate</code>, <code>restoreOriginal</code>,
  601. * or <code>release</code>, that method calls <code>notifyRowSetChanged</code>
  602. * internally (either directly or indirectly). An application <b>should</b>
  603. * never invoke this method directly.
  604. *
  605. * @throws SQLException if the class extending the <code>BaseRowSet</code>
  606. * abstract class does not implement the <code>RowSet</code> interface or
  607. * one of it's sub-interfaces.
  608. */
  609. protected void notifyRowSetChanged() throws SQLException {
  610. checkforRowSetInterface();
  611. if (listeners.isEmpty() == false) {
  612. RowSetEvent event = new RowSetEvent((RowSet)this);
  613. for (Iterator i = listeners.iterator(); i.hasNext(); ) {
  614. ((RowSetListener)i.next()).rowSetChanged(event);
  615. }
  616. }
  617. }
  618. /**
  619. * Retrieves the SQL query that is the command for this
  620. * <code>RowSet</code> object. The command property contains the query that
  621. * will be executed to populate this <code>RowSet</code> object.
  622. * <P>
  623. * The SQL query returned by this method is used by <code>RowSet</code> methods
  624. * such as <code>execute</code> and <code>populate</code>, which may be implemented
  625. * by any class that extends the <code>BaseRowSet</code> abstract class and
  626. * implements one or more of the standard JSR-114 <code>RowSet</code>
  627. * interfaces.
  628. * <P>
  629. * The command is used by the <code>RowSet</code> object's
  630. * reader to obtain a <code>ResultSet</code> object. The reader then
  631. * reads the data from the <code>ResultSet</code> object and uses it to
  632. * to populate this <code>RowSet</code> object.
  633. * <P>
  634. * The default value for the <code>command</code> property is <code>null</code>.
  635. *
  636. * @return the <code>String</code> that is the value for this
  637. * <code>RowSet</code> object's <code>command</code> property;
  638. * may be <code>null</code>
  639. * @see #setCommand
  640. */
  641. public String getCommand() {
  642. return command;
  643. }
  644. /**
  645. * Sets this <code>RowSet</code> object's <code>command</code> property to
  646. * the given <code>String</code> object and clears the parameters, if any,
  647. * that were set for the previous command.
  648. * <P>
  649. * The <code>command</code> property may not be needed if the <code>RowSet</code>
  650. * object gets its data from a source that does not support commands,
  651. * such as a spreadsheet or other tabular file.
  652. * Thus, this property is optional and may be <code>null</code>.
  653. *
  654. * @param cmd a <code>String</code> object containing an SQL query
  655. * that will be set as this <code>RowSet</code> object's command
  656. * property; may be <code>null</code> but may not be an empty string
  657. * @throws SQLException if an empty string is provided as the command value
  658. * @see #getCommand
  659. */
  660. public void setCommand(String cmd) throws SQLException {
  661. // cmd equal to null or
  662. // cmd with length 0 (implies url =="")
  663. // are not independent events.
  664. if(cmd == null) {
  665. command = null;
  666. } else if (cmd.length() == 0) {
  667. throw new SQLException("Invalid command string detected. " +
  668. "Cannot be of length less than 0");
  669. } else {
  670. // "unbind" any parameters from any previous command.
  671. if(params == null){
  672. throw new SQLException("Set initParams() before setCommand");
  673. }
  674. params.clear();
  675. command = new String(cmd);
  676. }
  677. }
  678. /**
  679. * Retrieves the JDBC URL that this <code>RowSet</code> object's
  680. * <code>javax.sql.Reader</code> object uses to make a connection
  681. * with a relational database using a JDBC technology-enabled driver.
  682. *<P>
  683. * The <code>Url</code> property will be <code>null</code> if the underlying data
  684. * source is a non-SQL data source, such as a spreadsheet or an XML
  685. * data source.
  686. *
  687. * @return a <code>String</code> object that contains the JDBC URL
  688. * used to establish the connection for this <code>RowSet</code>
  689. * object; may be <code>null</code> (default value) if not set
  690. * @throws SQLException if an error occurs retrieving the URL value
  691. * @see #setUrl
  692. */
  693. public String getUrl() throws SQLException {
  694. return URL;
  695. }
  696. /**
  697. * Sets the Url property for this <code>RowSet</code> object
  698. * to the given <code>String</code> object and sets the dataSource name
  699. * property to <code>null</code>. The Url property is a
  700. * JDBC URL that is used when
  701. * the connection is created using a JDBC technology-enabled driver
  702. * ("JDBC driver") and the <code>DriverManager</code>.
  703. * The correct JDBC URL for the specific driver to be used can be found
  704. * in the driver documentation. Although there are guidelines for for how
  705. * a JDBC URL is formed,
  706. * a driver vendor can specify any <code>String</code> object except
  707. * one with a length of <code>0</code> (an empty string).
  708. * <P>
  709. * Setting the Url property is optional if connections are established using
  710. * a <code>DataSource</code> object instead of the <code>DriverManager</code>.
  711. * The driver will use either the URL property or the
  712. * dataSourceName property to create a connection, whichever was
  713. * specified most recently. If an application uses a JDBC URL, it
  714. * must load a JDBC driver that accepts the JDBC URL before it uses the
  715. * <code>RowSet</code> object to connect to a database. The <code>RowSet</code>
  716. * object will use the URL internally to create a database connection in order
  717. * to read or write data.
  718. *
  719. * @param url a <code>String</code> object that contains the JDBC URL
  720. * that will be used to establish the connection to a database for this
  721. * <code>RowSet</code> object; may be <code>null</code> but must not
  722. * be an empty string
  723. * @throws SQLException if an error occurs setting the Url property or the
  724. * parameter supplied is a string with a length of <code>0</code> (an
  725. * empty string)
  726. * @see #getUrl
  727. */
  728. public void setUrl(String url) throws SQLException {
  729. if(url == null) {
  730. url = null;
  731. } else if (url.length() < 1) {
  732. throw new SQLException("Invalid url string detected. " +
  733. "Cannot be of length less than 1");
  734. } else {
  735. URL = new String(url);
  736. }
  737. dataSource = null;
  738. }
  739. /**
  740. * Returns the logical name that when supplied to a naming service
  741. * that uses the Java Naming and Directory Interface (JNDI) API, will
  742. * retrieve a <code>javax.sql.DataSource</code> object. This
  743. * <code>DataSource</code> object can be used to establish a connection
  744. * to the data source that it represents.
  745. * <P>
  746. * Users should set either the url or the data source name property.
  747. * The driver will use the property set most recently to establish a
  748. * connection.
  749. *
  750. * @return a <code>String</code> object that identifies the
  751. * <code>DataSource</code> object to be used for making a
  752. * connection; if no logical name has been set, <code>null</code>
  753. * is returned.
  754. * @see #setDataSourceName
  755. */
  756. public String getDataSourceName() {
  757. return dataSource;
  758. }
  759. /**
  760. * Sets the <code>DataSource</code> name property for this <code>RowSet</code>
  761. * object to the given logical name and sets this <code>RowSet</code> object's
  762. * Url property to <code>null</code>. The name must have been bound to a
  763. * <code>DataSource</code> object in a JNDI naming service so that an
  764. * application can do a lookup using that name to retrieve the
  765. * <code>DataSource</code> object bound to it. The <code>DataSource</code>
  766. * object can then be used to establish a connection to the data source it
  767. * represents.
  768. * <P>
  769. * Users should set either the Url property or the dataSourceName property.
  770. * If both properties are set, the driver will use the property set most recently.
  771. *
  772. * @param name a <code>String</code> object with the name that can be supplied
  773. * to a naming service based on JNDI technology to retrieve the
  774. * <code>DataSource</code> object that can be used to get a connection;
  775. * may be <code>null</code> but must not be an empty string
  776. * @throws SQLException if an empty string is provided as the <code>DataSource</code>
  777. * name
  778. * @see #getDataSourceName
  779. */
  780. public void setDataSourceName(String name) throws SQLException {
  781. if (name == null) {
  782. dataSource = null;
  783. } else if (name.equals("")) {
  784. throw new SQLException("DataSource name cannot be empty string");
  785. } else {
  786. dataSource = new String(name);
  787. }
  788. URL = null;
  789. }
  790. /**
  791. * Returns the user name used to create a database connection. Because it
  792. * is not serialized, the username property is set at runtime before
  793. * calling the method <code>execute</code>.
  794. *
  795. * @return the <code>String</code> object containing the user name that
  796. * is supplied to the data source to create a connection; may be
  797. * <code>null</code> (default value) if not set
  798. * @see #setUsername
  799. */
  800. public String getUsername() {
  801. return username;
  802. }
  803. /**
  804. * Sets the username property for this <code>RowSet</code> object
  805. * to the given user name. Because it
  806. * is not serialized, the username property is set at run time before
  807. * calling the method <code>execute</code>.
  808. *
  809. * @param name the <code>String</code> object containing the user name that
  810. * is supplied to the data source to create a connection. It may be null.
  811. * @see #getUsername
  812. */
  813. public void setUsername(String name) {
  814. if(name == null)
  815. {
  816. username = null;
  817. } else {
  818. username = new String(name);
  819. }
  820. }
  821. /**
  822. * Returns the password used to create a database connection for this
  823. * <code>RowSet</code> object. Because the password property is not
  824. * serialized, it is set at run time before calling the method
  825. * <code>execute</code>. The default value is <code>null</code>
  826. *
  827. * @return the <code>String</code> object that represents the password
  828. * that must be supplied to the database to create a connection
  829. * @see #setPassword
  830. */
  831. public String getPassword() {
  832. return password;
  833. }
  834. /**
  835. * Sets the password used to create a database connection for this
  836. * <code>RowSet</code> object to the given <code>String</code>
  837. * object. Because the password property is not
  838. * serialized, it is set at run time before calling the method
  839. * <code>execute</code>.
  840. *
  841. * @param pass the <code>String</code> object that represents the password
  842. * that is supplied to the database to create a connection. It may be
  843. * null.
  844. * @see #getPassword
  845. */
  846. public void setPassword(String pass) {
  847. if(pass == null)
  848. {
  849. password = null;
  850. } else {
  851. password = new String(pass);
  852. }
  853. }
  854. /**
  855. * Sets the type for this <code>RowSet</code> object to the specified type.
  856. * The default type is <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>.
  857. *
  858. * @param type one of the following constants:
  859. * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
  860. * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
  861. * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
  862. * @throws SQLException if the parameter supplied is not one of the
  863. * following constants:
  864. * <code>ResultSet.TYPE_FORWARD_ONLY</code> or
  865. * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>
  866. * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
  867. * @see #getConcurrency
  868. * @see #getType
  869. */
  870. public void setType(int type) throws SQLException {
  871. if ((type != ResultSet.TYPE_FORWARD_ONLY) &&
  872. (type != ResultSet.TYPE_SCROLL_INSENSITIVE) &&
  873. (type != ResultSet.TYPE_SCROLL_SENSITIVE)) {
  874. throw new SQLException("Invalid type of RowSet set. Must be either " +
  875. "ResultSet.TYPE_FORWARD_ONLY or ResultSet.TYPE_SCROLL_INSENSITIVE " +
  876. "or ResultSet.TYPE_SCROLL_SENSITIVE.");
  877. }
  878. this.rowSetType = type;
  879. }
  880. /**
  881. * Returns the type of this <code>RowSet</code> object. The type is initially
  882. * determined by the statement that created the <code>RowSet</code> object.
  883. * The <code>RowSet</code> object can call the method
  884. * <code>setType</code> at any time to change its
  885. * type. The default is <code>TYPE_SCROLL_INSENSITIVE</code>.
  886. *
  887. * @return the type of this JDBC <code>RowSet</code>
  888. * object, which must be one of the following:
  889. * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
  890. * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
  891. * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
  892. * @throws SQLException if an error occurs getting the type of
  893. * of this <code>RowSet</code> object
  894. * @see #setType
  895. */
  896. public int getType() throws SQLException {
  897. return rowSetType;
  898. }
  899. /**
  900. * Sets the concurrency for this <code>RowSet</code> object to
  901. * the specified concurrency. The default concurrency for any <code>RowSet</code>
  902. * object (connected or disconnected) is <code>ResultSet.CONCUR_UPDATABLE</code>,
  903. * but this method may be called at any time to change the concurrency.
  904. * <P>
  905. * @param concurrency one of the following constants:
  906. * <code>ResultSet.CONCUR_READ_ONLY</code> or
  907. * <code>ResultSet.CONCUR_UPDATABLE</code>
  908. * @throws SQLException if the parameter supplied is not one of the
  909. * following constants:
  910. * <code>ResultSet.CONCUR_UPDATABLE</code> or
  911. * <code>ResultSet.CONCUR_READ_ONLY</code>
  912. * @see #getConcurrency
  913. * @see #isReadOnly
  914. */
  915. public void setConcurrency(int concurrency) throws SQLException {
  916. if((concurrency != ResultSet.CONCUR_READ_ONLY) &&
  917. (concurrency != ResultSet.CONCUR_UPDATABLE)) {
  918. throw new SQLException("Invalid concurrency set. Must be either " +
  919. "ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE.");
  920. }
  921. this.concurrency = concurrency;
  922. }
  923. /**
  924. * Returns a <code>boolean</code> indicating whether this
  925. * <code>RowSet</code> object is read-only.
  926. * Any attempts to update a read-only <code>RowSet</code> object will result in an
  927. * <code>SQLException</code> being thrown. By default,
  928. * rowsets are updatable if updates are possible.
  929. *
  930. * @return <code>true</code> if this <code>RowSet</code> object
  931. * cannot be updated; <code>false</code> otherwise
  932. * @see #setConcurrency
  933. * @see #setReadOnly
  934. */
  935. public boolean isReadOnly() {
  936. return readOnly;
  937. };
  938. /**
  939. * Sets this <code>RowSet</code> object's readOnly property to the given <code>boolean</code>.
  940. *
  941. * @param value <code>true</code> to indicate that this
  942. * <code>RowSet</code> object is read-only;
  943. * <code>false</code> to indicate that it is updatable
  944. */
  945. public void setReadOnly(boolean value) {
  946. readOnly = value;
  947. }
  948. /**
  949. * Returns the transaction isolation property for this
  950. * <code>RowSet</code> object's connection. This property represents
  951. * the transaction isolation level requested for use in transactions.
  952. * <P>
  953. * For <code>RowSet</code> implementations such as
  954. * the <code>CachedRowSet</code> that operate in a disconnected environment,
  955. * the <code>SyncProvider</code> object
  956. * offers complementary locking and data integrity options. The
  957. * options described below are pertinent only to connected <code>RowSet</code>
  958. * objects (<code>JdbcRowSet</code> objects).
  959. *
  960. * @return one of the following constants:
  961. * <code>Connection.TRANSACTION_NONE</code>,
  962. * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
  963. * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
  964. * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
  965. * <code>Connection.TRANSACTION_SERIALIZABLE</code>
  966. * @see javax.sql.rowset.spi.SyncFactory
  967. * @see javax.sql.rowset.spi.SyncProvider
  968. * @see #setTransactionIsolation
  969. */
  970. public int getTransactionIsolation() {
  971. return isolation;
  972. };
  973. /**
  974. * Sets the transaction isolation property for this JDBC <code>RowSet</code> object to the given
  975. * constant. The DBMS will use this transaction isolation level for
  976. * transactions if it can.
  977. * <p>
  978. * For <code>RowSet</code> implementations such as
  979. * the <code>CachedRowSet</code> that operate in a disconnected environment,
  980. * the <code>SyncProvider</code> object being used
  981. * offers complementary locking and data integrity options. The
  982. * options described below are pertinent only to connected <code>RowSet</code>
  983. * objects (<code>JdbcRowSet</code> objects).
  984. *
  985. * @param level one of the following constants, listed in ascending order:
  986. * <code>Connection.TRANSACTION_NONE</code>,
  987. * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
  988. * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
  989. * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
  990. * <code>Connection.TRANSACTION_SERIALIZABLE</code>
  991. * @throws SQLException if the given parameter is not one of the Connection
  992. * constants
  993. * @see javax.sql.rowset.spi.SyncFactory
  994. * @see javax.sql.rowset.spi.SyncProvider
  995. * @see #getTransactionIsolation
  996. */
  997. public void setTransactionIsolation(int level) throws SQLException {
  998. if ((level != Connection.TRANSACTION_NONE) &&
  999. (level != Connection.TRANSACTION_READ_COMMITTED) &&
  1000. (level != Connection.TRANSACTION_READ_UNCOMMITTED) &&
  1001. (level != Connection.TRANSACTION_REPEATABLE_READ) &&
  1002. (level != Connection.TRANSACTION_SERIALIZABLE))
  1003. {
  1004. throw new SQLException("Invalid transaction isolation set. Must " +
  1005. "be either " +
  1006. "Connection.TRANSACTION_NONE or " +
  1007. "Connection.TRANSACTION_READ_UNCOMMITTED or " +
  1008. "Connection.TRANSACTION_READ_COMMITTED or " +
  1009. "Connection.RRANSACTION_REPEATABLE_READ or " +
  1010. "Connection.TRANSACTION_SERIALIZABLE");
  1011. }
  1012. this.isolation = level;
  1013. }
  1014. /**
  1015. * Retrieves the type map associated with the <code>Connection</code>
  1016. * object for this <code>RowSet</code> object.
  1017. * <P>
  1018. * Drivers that support the JDBC 3.0 API will create
  1019. * <code>Connection</code> objects with an associated type map.
  1020. * This type map, which is initially empty, can contain one or more
  1021. * fully-qualified SQL names and <code>Class</code> objects indicating
  1022. * the class to which the named SQL value will be mapped. The type mapping
  1023. * specified in the connection's type map is used for custom type mapping
  1024. * when no other type map supersedes it.
  1025. * <p>
  1026. * If a type map is explicitly supplied to a method that can perform
  1027. * custom mapping, that type map supersedes the connection's type map.
  1028. *
  1029. * @return the <code>java.util.Map</code> object that is the type map
  1030. * for this <code>RowSet</code> object's connection
  1031. */
  1032. public java.util.Map<String,Class<?>> getTypeMap() {
  1033. return map;
  1034. }
  1035. /**
  1036. * Installs the given <code>java.util.Map</code> object as the type map
  1037. * associated with the <code>Connection</code> object for this
  1038. * <code>RowSet</code> object. The custom mapping indicated in
  1039. * this type map will be used unless a different type map is explicitly
  1040. * supplied to a method, in which case the type map supplied will be used.
  1041. *
  1042. * @param map a <code>java.util.Map</code> object that contains the
  1043. * mapping from SQL type names for user defined types (UDT) to classes in
  1044. * the Java programming language. Each entry in the <code>Map</code>
  1045. * object consists of the fully qualified SQL name of a UDT and the
  1046. * <code>Class</code> object for the <code>SQLData</code> implementation
  1047. * of that UDT. May be <code>null</code>.
  1048. */
  1049. public void setTypeMap(java.util.Map<String,Class<?>> map) {
  1050. this.map = map;
  1051. }
  1052. /**
  1053. * Retrieves the maximum number of bytes that can be used for a column
  1054. * value in this <code>RowSet</code> object.
  1055. * This limit applies only to columns that hold values of the
  1056. * following types: <code>BINARY</code>, <code>VARBINARY</code>,
  1057. * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
  1058. * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
  1059. * data is silently discarded.
  1060. *
  1061. * @return an <code>int</code> indicating the current maximum column size
  1062. * limit; zero means that there is no limit
  1063. * @throws SQLException if an error occurs internally determining the
  1064. * maximum limit of the column size
  1065. */
  1066. public int getMaxFieldSize() throws SQLException {
  1067. return maxFieldSize;
  1068. }
  1069. /**
  1070. * Sets the maximum number of bytes that can be used for a column
  1071. * value in this <code>RowSet</code> object to the given number.
  1072. * This limit applies only to columns that hold values of the
  1073. * following types: <code>BINARY</code>, <code>VARBINARY</code>,
  1074. * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
  1075. * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
  1076. * data is silently discarded. For maximum portability, it is advisable to
  1077. * use values greater than 256.
  1078. *
  1079. * @param max an <code>int</code> indicating the new maximum column size
  1080. * limit; zero means that there is no limit
  1081. * @throws SQLException if (1) an error occurs internally setting the
  1082. * maximum limit of the column size or (2) a size of less than 0 is set
  1083. */
  1084. public void setMaxFieldSize(int max) throws SQLException {
  1085. if (max < 0) {
  1086. throw new SQLException("Invalid max field size set. Cannot be of " +
  1087. "value: " + max);
  1088. }
  1089. maxFieldSize = max;
  1090. }
  1091. /**
  1092. * Retrieves the maximum number of rows that this <code>RowSet</code> object may contain. If
  1093. * this limit is exceeded, the excess rows are silently dropped.
  1094. *
  1095. * @return an <code>int</code> indicating the current maximum number of
  1096. * rows; zero means that there is no limit
  1097. * @throws SQLException if an error occurs internally determining the
  1098. * maximum limit of rows that a <code>Rowset</code> object can contain
  1099. */
  1100. public int getMaxRows() throws SQLException {
  1101. return maxRows;
  1102. }
  1103. /**
  1104. * Sets the maximum number of rows that this <code>RowSet</code> object may contain to
  1105. * the given number. If this limit is exceeded, the excess rows are
  1106. * silently dropped.
  1107. *
  1108. * @param max an <code>int</code> indicating the current maximum number
  1109. * of rows; zero means that there is no limit
  1110. * @throws SQLException if an error occurs internally setting the
  1111. * maximum limit on the number of rows that a JDBC <code>RowSet</code> object
  1112. * can contain; or if <i>max</i> is less than <code>0</code> or
  1113. * if <i>max</i> is less than the <code>fetchSize</code> of the
  1114. * <code>RowSet</code>
  1115. */
  1116. public void setMaxRows(int max) throws SQLException {
  1117. if (max < 0) {
  1118. throw new SQLException("Invalid max row size set. Cannot be of " +
  1119. "value: " + max);
  1120. } else if (max < this.getFetchSize()) {
  1121. throw new SQLException("Invalid max row size set. Cannot be less " +
  1122. "than the fetchSize.");
  1123. }
  1124. this.maxRows = max;
  1125. }
  1126. /**
  1127. * Sets to the given <code>boolean</code> whether or not the driver will
  1128. * scan for escape syntax and do escape substitution before sending SQL
  1129. * statements to the database. The default is for the driver to do escape
  1130. * processing.
  1131. * <P>
  1132. * Note: Since <code>PreparedStatement</code> objects have usually been
  1133. * parsed prior to making this call, disabling escape processing for
  1134. * prepared statements will likely have no effect.
  1135. *
  1136. * @param enable <code>true</code> to enable escape processing;
  1137. * <code>false</code> to disable it
  1138. * @throws SQLException if an error occurs setting the underlying JDBC
  1139. * technology-enabled driver to process the escape syntax
  1140. */
  1141. public void setEscapeProcessing(boolean enable) throws SQLException {
  1142. escapeProcessing = enable;
  1143. }
  1144. /**
  1145. * Retrieves the maximum number of seconds the driver will wait for a
  1146. * query to execute. If the limit is exceeded, an <code>SQLException</code>
  1147. * is thrown.
  1148. *
  1149. * @return the current query timeout limit in seconds; zero means that
  1150. * there is no limit
  1151. * @throws SQLException if an error occurs in determining the query
  1152. * time-out value
  1153. */
  1154. public int getQueryTimeout() throws SQLException {
  1155. return queryTimeout;
  1156. }
  1157. /**
  1158. * Sets to the given number the maximum number of seconds the driver will
  1159. * wait for a query to execute. If the limit is exceeded, an
  1160. * <code>SQLException</code> is thrown.
  1161. *
  1162. * @param seconds the new query time-out limit in seconds; zero means that
  1163. * there is no limit; must not be less than zero
  1164. * @throws SQLException if an error occurs setting the query
  1165. * time-out or if the query time-out value is less than 0
  1166. */
  1167. public void setQueryTimeout(int seconds) throws SQLException {
  1168. if (seconds < 0) {
  1169. throw new SQLException("Invalid query timeout value set. Cannot be " +
  1170. "of value: " + seconds);
  1171. }
  1172. this.queryTimeout = seconds;
  1173. }
  1174. /**
  1175. * Retrieves a <code>boolean</code> indicating whether rows marked
  1176. * for deletion appear in the set of current rows.
  1177. * The default value is <code>false</code>.
  1178. * <P>
  1179. * Note: Allowing deleted rows to remain visible complicates the behavior
  1180. * of some of the methods. However, most <code>RowSet</code> object users
  1181. * can simply ignore this extra detail because only sophisticated
  1182. * applications will likely want to take advantage of this feature.
  1183. *
  1184. * @return <code>true</code> if deleted rows are visible;
  1185. * <code>false</code> otherwise
  1186. * @throws SQLException if an error occurs determining if deleted rows
  1187. * are visible or not
  1188. * @see #setShowDeleted
  1189. */
  1190. public boolean getShowDeleted() throws SQLException {
  1191. return showDeleted;
  1192. }
  1193. /**
  1194. * Sets the property <code>showDeleted</code> to the given
  1195. * <code>boolean</code> value, which determines whether
  1196. * rows marked for deletion appear in the set of current rows.
  1197. *
  1198. * @param value <code>true</code> if deleted rows should be shown;
  1199. * <code>false</code> otherwise
  1200. * @throws SQLException if an error occurs setting whether deleted
  1201. * rows are visible or not
  1202. * @see #getShowDeleted
  1203. */
  1204. public void setShowDeleted(boolean value) throws SQLException {
  1205. showDeleted = value;
  1206. }
  1207. /**
  1208. * Ascertains whether escape processing is enabled for this
  1209. * <code>RowSet</code> object.
  1210. *
  1211. * @return <code>true</code> if escape processing is turned on;
  1212. * <code>false</code> otherwise
  1213. * @throws SQLException if an error occurs determining if escape
  1214. * processing is enabled or not or if the internal escape
  1215. * processing trigger has not been enabled
  1216. */
  1217. public boolean getEscapeProcessing() throws SQLException {
  1218. return escapeProcessing;
  1219. }
  1220. /**
  1221. * Gives the driver a performance hint as to the direction in
  1222. * which the rows in this <code>RowSet</code> object will be
  1223. * processed. The driver may ignore this hint.
  1224. * <P>
  1225. * A <code>RowSet</code> object inherits the default properties of the
  1226. * <code>ResultSet</code> object from which it got its data. That
  1227. * <code>ResultSet</code> object's default fetch direction is set by
  1228. * the <code>Statement</code> object that created it.
  1229. * <P>
  1230. * This method applies to a <code>RowSet</code> object only while it is
  1231. * connected to a database using a JDBC driver.
  1232. * <p>
  1233. * A <code>RowSet</code> object may use this method at any time to change
  1234. * its setting for the fetch direction.
  1235. *
  1236. * @param direction one of <code>ResultSet.FETCH_FORWARD</code>,
  1237. * <code>ResultSet.FETCH_REVERSE</code>, or
  1238. * <code>ResultSet.FETCH_UNKNOWN</code>
  1239. * @throws SQLException if (1) the <code>RowSet</code> type is
  1240. * <code>TYPE_FORWARD_ONLY</code> and the given fetch direction is not
  1241. * <code>FETCH_FORWARD</code> or (2) the given fetch direction is not
  1242. * one of the following:
  1243. * ResultSet.FETCH_FORWARD,
  1244. * ResultSet.FETCH_REVERSE, or
  1245. * ResultSet.FETCH_UNKNOWN
  1246. * @see #getFetchDirection
  1247. */
  1248. public void setFetchDirection(int direction) throws SQLException {
  1249. // Changed the condition checking to the below as there were two
  1250. // conditions that had to be checked
  1251. // 1. RowSet is TYPE_FORWARD_ONLY and direction is not FETCH_FORWARD
  1252. // 2. Direction is not one of the valid values
  1253. if (((getType() == ResultSet.TYPE_FORWARD_ONLY) && (direction != ResultSet.FETCH_FORWARD)) ||
  1254. ((direction != ResultSet.FETCH_FORWARD) &&
  1255. (direction != ResultSet.FETCH_REVERSE) &&
  1256. (direction != ResultSet.FETCH_UNKNOWN))) {
  1257. throw new SQLException("Invalid Fetch Direction");
  1258. }
  1259. fetchDir = direction;
  1260. }
  1261. /**
  1262. * Retrieves this <code>RowSet</code> object's current setting for the
  1263. * fetch direction. The default type is <code>ResultSet.FETCH_FORWARD</code>
  1264. *
  1265. * @return one of <code>ResultSet.FETCH_FORWARD</code>,
  1266. * <code>ResultSet.FETCH_REVERSE</code>, or
  1267. * <code>ResultSet.FETCH_UNKNOWN</code>
  1268. * @throws SQLException if an error occurs in determining the
  1269. * current fetch direction for fetching rows
  1270. * @see #setFetchDirection
  1271. */
  1272. public int getFetchDirection() throws SQLException {
  1273. //Added the following code to throw a
  1274. //SQL Exception if the fetchDir is not
  1275. //set properly.Bug id:4914155
  1276. // This checking is not necessary!
  1277. /*
  1278. if((fetchDir != ResultSet.FETCH_FORWARD) &&
  1279. (fetchDir != ResultSet.FETCH_REVERSE) &&
  1280. (fetchDir != ResultSet.FETCH_UNKNOWN)) {
  1281. throw new SQLException("Fetch Direction Invalid");
  1282. }
  1283. */
  1284. return (fetchDir);
  1285. }
  1286. /**
  1287. * Sets the fetch size for this <code>RowSet</code> object to the given number of
  1288. * rows. The fetch size gives a JDBC technology-enabled driver ("JDBC driver")
  1289. * a hint as to the
  1290. * number of rows that should be fetched from the database when more rows
  1291. * are needed for this <code>RowSet</code> object. If the fetch size specified
  1292. * is zero, the driver ignores the value and is free to make its own best guess
  1293. * as to what the fetch size should be.
  1294. * <P>
  1295. * A <code>RowSet</code> object inherits the default properties of the
  1296. * <code>ResultSet</code> object from which it got its data. That
  1297. * <code>ResultSet</code> object's default fetch size is set by
  1298. * the <code>Statement</code> object that created it.
  1299. * <P>
  1300. * This method applies to a <code>RowSet</code> object only while it is
  1301. * connected to a database using a JDBC driver.
  1302. * For connected <code>RowSet</code> implementations such as
  1303. * <code>JdbcRowSet</code>, this method has a direct and immediate effect
  1304. * on the underlying JDBC driver.
  1305. * <P>
  1306. * A <code>RowSet</code> object may use this method at any time to change
  1307. * its setting for the fetch size.
  1308. * <p>
  1309. * For <code>RowSet</code> implementations such as
  1310. * <code>CachedRowSet</code>, which operate in a disconnected environment,
  1311. * the <code>SyncProvider</code> object being used
  1312. * may leverage the fetch size to poll the data source and
  1313. * retrieve a number of rows that do not exceed the fetch size and that may
  1314. * form a subset of the actual rows returned by the original query. This is
  1315. * an implementation variance determined by the specific <code>SyncProvider</code>
  1316. * object employed by the disconnected <code>RowSet</code> object.
  1317. * <P>
  1318. *
  1319. * @param rows the number of rows to fetch; <code>0</code> to let the
  1320. * driver decide what the best fetch size is; must not be less
  1321. * than <code>0</code> or more than the maximum number of rows
  1322. * allowed for this <code>RowSet</code> object (the number returned
  1323. * by a call to the method {@link #getMaxRows})
  1324. * @throws SQLException if the specified fetch size is less than <code>0</code>
  1325. * or more than the limit for the maximum number of rows
  1326. * @see #getFetchSize
  1327. */
  1328. public void setFetchSize(int rows) throws SQLException {
  1329. //Added this checking as maxRows can be 0 when this function is called
  1330. //maxRows = 0 means rowset can hold any number of rows, os this checking
  1331. // is needed to take care of this condition.
  1332. if (getMaxRows() == 0 && rows >= 0) {
  1333. fetchSize = rows;
  1334. return;
  1335. }
  1336. if ((rows < 0) || (rows > getMaxRows())) {
  1337. throw new SQLException("Invalid fetch size set. Cannot be of " +
  1338. "value: " + rows);
  1339. }
  1340. fetchSize = rows;
  1341. }
  1342. /**
  1343. * Returns the fetch size for this <code>RowSet</code> object. The default
  1344. * value is zero.
  1345. *
  1346. * @return the number of rows suggested as the fetch size when this <code>RowSet</code> object
  1347. * needs more rows from the database
  1348. * @throws SQLException if an error occurs determining the number of rows in the
  1349. * current fetch size
  1350. * @see #setFetchSize
  1351. */
  1352. public int getFetchSize() throws SQLException {
  1353. return fetchSize;
  1354. }
  1355. /**
  1356. * Returns the concurrency for this <code>RowSet</code> object.
  1357. * The default is <code>CONCUR_UPDATABLE</code> for both connected and
  1358. * disconnected <code>RowSet</code> objects.
  1359. * <P>
  1360. * An application can call the method <code>setConcurrency</code> at any time
  1361. * to change a <code>RowSet</code> object's concurrency.
  1362. * <p>
  1363. * @return the concurrency type for this <code>RowSet</code>
  1364. * object, which must be one of the following:
  1365. * <code>ResultSet.CONCUR_READ_ONLY</code> or
  1366. * <code>ResultSet.CONCUR_UPDATABLE</code>
  1367. * @throws SQLException if an error occurs getting the concurrency
  1368. * of this <code>RowSet</code> object
  1369. * @see #setConcurrency
  1370. * @see #isReadOnly
  1371. */
  1372. public int getConcurrency() throws SQLException {
  1373. return concurrency;
  1374. }
  1375. //-----------------------------------------------------------------------
  1376. // Parameters
  1377. //-----------------------------------------------------------------------
  1378. /**
  1379. * Checks the given index to see whether it is less than <code>1</code> and
  1380. * throws an <code>SQLException</code> object if it is.
  1381. * <P>
  1382. * This method is called by many methods internally; it is never
  1383. * called by an application directly.
  1384. *
  1385. * @param idx an <code>int</code> indicating which parameter is to be
  1386. * checked; the first parameter is <code>1</code>
  1387. * @throws SQLException if the parameter is less than <code>1</code>
  1388. */
  1389. private void checkParamIndex(int idx) throws SQLException {
  1390. if ((idx < 1)) {
  1391. throw new SQLException("Invalid Parameter Index");
  1392. }
  1393. }
  1394. //---------------------------------------------------------------------
  1395. // setter methods for setting the parameters in a <code>RowSet</code> object's command
  1396. //---------------------------------------------------------------------
  1397. /**
  1398. * Sets the designated parameter to SQL <code>NULL</code>.
  1399. * Note that the parameter's SQL type must be specified using one of the
  1400. * type codes defined in <code>java.sql.Types</code>. This SQL type is
  1401. * specified in the second parameter.
  1402. * <p>
  1403. * Note that the second parameter tells the DBMS the data type of the value being
  1404. * set to <code>NULL</code>. Some DBMSs require this information, so it is required
  1405. * in order to make code more portable.
  1406. * <P>
  1407. * The parameter value set by this method is stored internally and
  1408. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1409. * object's command when the method <code>execute</code> is called.
  1410. * Methods such as <code>execute</code> and <code>populate</code> must be
  1411. * provided in any class that extends this class and implements one or
  1412. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1413. * <P>
  1414. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1415. * as it is undefined in this class.
  1416. * <P>
  1417. * Calls made to the method <code>getParams</code> after this version of
  1418. * <code>setNull</code>
  1419. * has been called will return an <code>Object</code> array containing the parameter values that
  1420. * have been set. In that array, the element that represents the values
  1421. * set with this method will itself be an array. The first element of that array
  1422. * is <code>null</code>.
  1423. * The second element is the value set for <i>sqlType</i>.
  1424. * The parameter number is indicated by an element's position in the array
  1425. * returned by the method <code>getParams</code>,
  1426. * with the first element being the value for the first placeholder parameter, the
  1427. * second element being the value for the second placeholder parameter, and so on.
  1428. * In other words, if the second placeholder parameter is being set to
  1429. * <code>null</code>, the array containing it will be the second element in
  1430. * the array returned by <code>getParams</code>.
  1431. * <P>
  1432. * Note that because the numbering of elements in an array starts at zero,
  1433. * the array element that corresponds to placeholder parameter number
  1434. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  1435. *
  1436. * @param parameterIndex the ordinal number of the placeholder parameter
  1437. * in this <code>RowSet</code> object's command that is to be set.
  1438. * The first parameter is 1, the second is 2, and so on; must be
  1439. * <code>1</code> or greater
  1440. * @param sqlType an <code>int</code> that is one of the SQL type codes
  1441. * defined in the class {@link java.sql.Types}. If a non-standard
  1442. * <i>sqlType</i> is supplied, this method will not throw a
  1443. * <code>SQLException</code>. This allows implicit support for
  1444. * non-standard SQL types.
  1445. * @throws SQLException if a database access error occurs or the given
  1446. * parameter index is out of bounds
  1447. * @see #getParams
  1448. */
  1449. public void setNull(int parameterIndex, int sqlType) throws SQLException {
  1450. Object nullVal[];
  1451. checkParamIndex(parameterIndex);
  1452. nullVal = new Object[2];
  1453. nullVal[0] = null;
  1454. nullVal[1] = new Integer(sqlType);
  1455. if (params == null){
  1456. throw new SQLException("Set initParams() before setNull");
  1457. }
  1458. params.put(new Integer(parameterIndex - 1), nullVal);
  1459. }
  1460. /**
  1461. * Sets the designated parameter to SQL <code>NULL</code>.
  1462. *
  1463. * Although this version of the method <code>setNull</code> is intended
  1464. * for user-defined
  1465. * and <code>REF</code> parameters, this method may be used to set a null
  1466. * parameter for any JDBC type. The following are user-defined types:
  1467. * <code>STRUCT</code>, <code>DISTINCT</code>, and <code>JAVA_OBJECT</code>,
  1468. * and named array types.
  1469. *
  1470. * <P><B>Note:</B> To be portable, applications must give the
  1471. * SQL type code and the fully qualified SQL type name when specifying
  1472. * a <code>NULL</code> user-defined or <code>REF</code> parameter.
  1473. * In the case of a user-defined type, the name is the type name of
  1474. * the parameter itself. For a <code>REF</code> parameter, the name is
  1475. * the type name of the referenced type. If a JDBC technology-enabled
  1476. * driver does not need the type code or type name information,
  1477. * it may ignore it.
  1478. * <P>
  1479. * If the parameter does not have a user-defined or <code>REF</code> type,
  1480. * the given <code>typeName</code> parameter is ignored.
  1481. * <P>
  1482. * The parameter value set by this method is stored internally and
  1483. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1484. * object's command when the method <code>execute</code> is called.
  1485. * Methods such as <code>execute</code> and <code>populate</code> must be
  1486. * provided in any class that extends this class and implements one or
  1487. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1488. * <P>
  1489. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1490. * as it is undefined in this class.
  1491. * <P>
  1492. * Calls made to the method <code>getParams</code> after this version of
  1493. * <code>setNull</code>
  1494. * has been called will return an <code>Object</code> array containing the parameter values that
  1495. * have been set. In that array, the element that represents the values
  1496. * set with this method will itself be an array. The first element of that array
  1497. * is <code>null</code>.
  1498. * The second element is the value set for <i>sqlType</i>, and the third
  1499. * element is the value set for <i>typeName</i>.
  1500. * The parameter number is indicated by an element's position in the array
  1501. * returned by the method <code>getParams</code>,
  1502. * with the first element being the value for the first placeholder parameter, the
  1503. * second element being the value for the second placeholder parameter, and so on.
  1504. * In other words, if the second placeholder parameter is being set to
  1505. * <code>null</code>, the array containing it will be the second element in
  1506. * the array returned by <code>getParams</code>.
  1507. * <P>
  1508. * Note that because the numbering of elements in an array starts at zero,
  1509. * the array element that corresponds to placeholder parameter number
  1510. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  1511. *
  1512. * @param parameterIndex the ordinal number of the placeholder parameter
  1513. * in this <code>RowSet</code> object's command that is to be set.
  1514. * The first parameter is 1, the second is 2, and so on; must be
  1515. * <code>1</code> or greater
  1516. * @param sqlType a value from <code>java.sql.Types</code>
  1517. * @param typeName the fully qualified name of an SQL user-defined type,
  1518. * which is ignored if the parameter is not a user-defined
  1519. * type or <code>REF</code> value
  1520. * @throws SQLException if an error occurs or the given parameter index
  1521. * is out of bounds
  1522. * @see #getParams
  1523. */
  1524. public void setNull(int parameterIndex, int sqlType, String typeName)
  1525. throws SQLException {
  1526. Object nullVal[];
  1527. checkParamIndex(parameterIndex);
  1528. nullVal = new Object[3];
  1529. nullVal[0] = null;
  1530. nullVal[1] = new Integer(sqlType);
  1531. nullVal[2] = new String(typeName);
  1532. if(params == null){
  1533. throw new SQLException("Set initParams() before setNull");
  1534. }
  1535. params.put(new Integer(parameterIndex - 1), nullVal);
  1536. }
  1537. /**
  1538. * Sets the designated parameter to the given <code>boolean</code> in the
  1539. * Java programming language. The driver converts this to an SQL
  1540. * <code>BIT</code> value when it sends it to the database.
  1541. * <P>
  1542. * The parameter value set by this method is stored internally and
  1543. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1544. * object's command when the method <code>execute</code> is called.
  1545. * Methods such as <code>execute</code>, <code>populate</code> must be
  1546. * provided in any class that extends this class and implements one or
  1547. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1548. * <p>
  1549. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1550. * as it is undefined in this class.
  1551. *
  1552. * @param parameterIndex the ordinal number of the placeholder parameter
  1553. * in this <code>RowSet</code> object's command that is to be set.
  1554. * The first parameter is 1, the second is 2, and so on; must be
  1555. * <code>1</code> or greater
  1556. * @param x the parameter value
  1557. * @throws SQLException if an error occurs or the
  1558. * parameter index is out of bounds
  1559. * @see #getParams
  1560. */
  1561. public void setBoolean(int parameterIndex, boolean x) throws SQLException {
  1562. checkParamIndex(parameterIndex);
  1563. if(params == null){
  1564. throw new SQLException("Set initParams() before setNull");
  1565. }
  1566. params.put(new Integer(parameterIndex - 1), new Boolean(x));
  1567. }
  1568. /**
  1569. * Sets the designated parameter to the given <code>byte</code> in the Java
  1570. * programming language. The driver converts this to an SQL
  1571. * <code>TINYINT</code> value when it sends it to the database.
  1572. * <P>
  1573. * The parameter value set by this method is stored internally and
  1574. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1575. * object's command when the method <code>execute</code> is called.
  1576. * Methods such as <code>execute</code> and <code>populate</code> must be
  1577. * provided in any class that extends this class and implements one or
  1578. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1579. * <p>
  1580. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1581. * as it is undefined in this class.
  1582. *
  1583. * @param parameterIndex the ordinal number of the placeholder parameter
  1584. * in this <code>RowSet</code> object's command that is to be set.
  1585. * The first parameter is 1, the second is 2, and so on; must be
  1586. * <code>1</code> or greater
  1587. * @param x the parameter value
  1588. * @throws SQLException if an error occurs or the
  1589. * parameter index is out of bounds
  1590. * @see #getParams
  1591. */
  1592. public void setByte(int parameterIndex, byte x) throws SQLException {
  1593. checkParamIndex(parameterIndex);
  1594. if(params == null){
  1595. throw new SQLException("Set initParams() before setByte");
  1596. }
  1597. params.put(new Integer(parameterIndex - 1), new Byte(x));
  1598. }
  1599. /**
  1600. * Sets the designated parameter to the given <code>short</code> in the
  1601. * Java programming language. The driver converts this to an SQL
  1602. * <code>SMALLINT</code> value when it sends it to the database.
  1603. * <P>
  1604. * The parameter value set by this method is stored internally and
  1605. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1606. * object's command when the method <code>execute</code> is called.
  1607. * Methods such as <code>execute</code> and <code>populate</code> must be
  1608. * provided in any class that extends this class and implements one or
  1609. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1610. * <p>
  1611. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1612. * as it is undefined in this class.
  1613. * <p>
  1614. * @param parameterIndex the ordinal number of the placeholder parameter
  1615. * in this <code>RowSet</code> object's command that is to be set.
  1616. * The first parameter is 1, the second is 2, and so on; must be
  1617. * <code>1</code> or greater
  1618. * @param x the parameter value
  1619. * @throws SQLException if an error occurs or the
  1620. * parameter index is out of bounds
  1621. * @see #getParams
  1622. */
  1623. public void setShort(int parameterIndex, short x) throws SQLException {
  1624. checkParamIndex(parameterIndex);
  1625. if(params == null){
  1626. throw new SQLException("Set initParams() before setShort");
  1627. }
  1628. params.put(new Integer(parameterIndex - 1), new Short(x));
  1629. }
  1630. /**
  1631. * Sets the designated parameter to an <code>int</code> in the Java
  1632. * programming language. The driver converts this to an SQL
  1633. * <code>INTEGER</code> value when it sends it to the database.
  1634. * <P>
  1635. * The parameter value set by this method is stored internally and
  1636. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1637. * object's command when the method <code>execute</code> is called.
  1638. * Methods such as <code>execute</code> and <code>populate</code> must be
  1639. * provided in any class that extends this class and implements one or
  1640. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1641. * <P>
  1642. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1643. * as it is undefined in this class.
  1644. *
  1645. * @param parameterIndex the ordinal number of the placeholder parameter
  1646. * in this <code>RowSet</code> object's command that is to be set.
  1647. * The first parameter is 1, the second is 2, and so on; must be
  1648. * <code>1</code> or greater
  1649. * @param x the parameter value
  1650. * @throws SQLException if an error occurs or the
  1651. * parameter index is out of bounds
  1652. * @see #getParams
  1653. */
  1654. public void setInt(int parameterIndex, int x) throws SQLException {
  1655. checkParamIndex(parameterIndex);
  1656. if(params == null){
  1657. throw new SQLException("Set initParams() before setInt");
  1658. }
  1659. params.put(new Integer(parameterIndex - 1), new Integer(x));
  1660. }
  1661. /**
  1662. * Sets the designated parameter to the given <code>long</code> in the Java
  1663. * programming language. The driver converts this to an SQL
  1664. * <code>BIGINT</code> value when it sends it to the database.
  1665. * <P>
  1666. * The parameter value set by this method is stored internally and
  1667. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1668. * object's command when the method <code>execute</code> is called.
  1669. * Methods such as <code>execute</code> and <code>populate</code> must be
  1670. * provided in any class that extends this class and implements one or
  1671. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1672. * <P>
  1673. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1674. * as it is undefined in this class.
  1675. *
  1676. * @param parameterIndex the ordinal number of the placeholder parameter
  1677. * in this <code>RowSet</code> object's command that is to be set.
  1678. * The first parameter is 1, the second is 2, and so on; must be
  1679. * <code>1</code> or greater
  1680. * @param x the parameter value
  1681. * @throws SQLException if an error occurs or the
  1682. * parameter index is out of bounds
  1683. * @see #getParams
  1684. */
  1685. public void setLong(int parameterIndex, long x) throws SQLException {
  1686. checkParamIndex(parameterIndex);
  1687. if(params == null){
  1688. throw new SQLException("Set initParams() before setLong");
  1689. }
  1690. params.put(new Integer(parameterIndex - 1), new Long(x));
  1691. }
  1692. /**
  1693. * Sets the designated parameter to the given <code>float</code> in the
  1694. * Java programming language. The driver converts this to an SQL
  1695. * <code>FLOAT</code> value when it sends it to the database.
  1696. * <P>
  1697. * The parameter value set by this method is stored internally and
  1698. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1699. * object's command when the method <code>execute</code> is called.
  1700. * Methods such as <code>execute</code> and <code>populate</code> must be
  1701. * provided in any class that extends this class and implements one or
  1702. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1703. * <P>
  1704. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1705. * as it is undefined in this class.
  1706. *
  1707. * @param parameterIndex the ordinal number of the placeholder parameter
  1708. * in this <code>RowSet</code> object's command that is to be set.
  1709. * The first parameter is 1, the second is 2, and so on; must be
  1710. * <code>1</code> or greater
  1711. * @param x the parameter value
  1712. * @throws SQLException if an error occurs or the
  1713. * parameter index is out of bounds
  1714. * @see #getParams
  1715. */
  1716. public void setFloat(int parameterIndex, float x) throws SQLException {
  1717. checkParamIndex(parameterIndex);
  1718. if(params == null){
  1719. throw new SQLException("Set initParams() before setFloat");
  1720. }
  1721. params.put(new Integer(parameterIndex - 1), new Float(x));
  1722. }
  1723. /**
  1724. * Sets the designated parameter to the given <code>double</code> in the
  1725. * Java programming language. The driver converts this to an SQL
  1726. * <code>DOUBLE</code> value when it sends it to the database.
  1727. * <P>
  1728. * The parameter value set by this method is stored internally and
  1729. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1730. * object's command when the method <code>execute</code> is called.
  1731. * Methods such as <code>execute</code> and <code>populate</code> must be
  1732. * provided in any class that extends this class and implements one or
  1733. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1734. * <P>
  1735. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1736. * as it is undefined in this class.
  1737. * S
  1738. * @param parameterIndex the ordinal number of the placeholder parameter
  1739. * in this <code>RowSet</code> object's command that is to be set.
  1740. * The first parameter is 1, the second is 2, and so on; must be
  1741. * <code>1</code> or greater
  1742. * @param x the parameter value
  1743. * @throws SQLException if an error occurs or the
  1744. * parameter index is out of bounds
  1745. * @see #getParams
  1746. */
  1747. public void setDouble(int parameterIndex, double x) throws SQLException {
  1748. checkParamIndex(parameterIndex);
  1749. if(params == null){
  1750. throw new SQLException("Set initParams() before setDouble");
  1751. }
  1752. params.put(new Integer(parameterIndex - 1), new Double(x));
  1753. }
  1754. /**
  1755. * Sets the designated parameter to the given
  1756. * <code>java.lang.BigDecimal</code> value. The driver converts this to
  1757. * an SQL <code>NUMERIC</code> value when it sends it to the database.
  1758. * <P>
  1759. * The parameter value set by this method is stored internally and
  1760. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1761. * object's command when the method <code>execute</code> is called.
  1762. * Methods such as <code>execute</code> and <code>populate</code> must be
  1763. * provided in any class that extends this class and implements one or
  1764. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1765. * <P>
  1766. * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1767. * as it is undefined in this class.
  1768. *
  1769. * @param parameterIndex the ordinal number of the placeholder parameter
  1770. * in this <code>RowSet</code> object's command that is to be set.
  1771. * The first parameter is 1, the second is 2, and so on; must be
  1772. * <code>1</code> or greater
  1773. * @param x the parameter value
  1774. * @throws SQLException if an error occurs or the
  1775. * parameter index is out of bounds
  1776. * @see #getParams
  1777. */
  1778. public void setBigDecimal(int parameterIndex, java.math.BigDecimal x) throws SQLException {
  1779. checkParamIndex(parameterIndex);
  1780. if(params == null){
  1781. throw new SQLException("Set initParams() before setBigDecimal");
  1782. }
  1783. params.put(new Integer(parameterIndex - 1), x);
  1784. }
  1785. /**
  1786. * Sets the designated parameter to the given <code>String</code>
  1787. * value. The driver converts this to an SQL
  1788. * <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
  1789. * (depending on the argument's size relative to the driver's limits
  1790. * on <code>VARCHAR</code> values) when it sends it to the database.
  1791. * <P>
  1792. * The parameter value set by this method is stored internally and
  1793. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1794. * object's command when the method <code>execute</code> is called.
  1795. * Methods such as <code>execute</code> and <code>populate</code> must be
  1796. * provided in any class that extends this class and implements one or
  1797. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1798. * <p>
  1799. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1800. * as it is undefined in this class.
  1801. * <p>
  1802. * @param parameterIndex the ordinal number of the placeholder parameter
  1803. * in this <code>RowSet</code> object's command that is to be set.
  1804. * The first parameter is 1, the second is 2, and so on; must be
  1805. * <code>1</code> or greater
  1806. * @param x the parameter value
  1807. * @throws SQLException if an error occurs or the
  1808. * parameter index is out of bounds
  1809. * @see #getParams
  1810. */
  1811. public void setString(int parameterIndex, String x) throws SQLException {
  1812. checkParamIndex(parameterIndex);
  1813. if(params == null){
  1814. throw new SQLException("Set initParams() before setString");
  1815. }
  1816. params.put(new Integer(parameterIndex - 1), x);
  1817. }
  1818. /**
  1819. * Sets the designated parameter to the given array of bytes.
  1820. * The driver converts this to an SQL
  1821. * <code>VARBINARY</code> or <code>LONGVARBINARY</code> value
  1822. * (depending on the argument's size relative to the driver's limits
  1823. * on <code>VARBINARY</code> values) when it sends it to the database.
  1824. * <P>
  1825. * The parameter value set by this method is stored internally and
  1826. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1827. * object's command when the method <code>execute</code> is called.
  1828. * Methods such as <code>execute</code> and <code>populate</code> must be
  1829. * provided in any class that extends this class and implements one or
  1830. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1831. * <p>
  1832. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1833. * as it is undefined in this class.
  1834. *
  1835. * @param parameterIndex the ordinal number of the placeholder parameter
  1836. * in this <code>RowSet</code> object's command that is to be set.
  1837. * The first parameter is 1, the second is 2, and so on; must be
  1838. * <code>1</code> or greater
  1839. * @param x the parameter value
  1840. * @throws SQLException if an error occurs or the
  1841. * parameter index is out of bounds
  1842. * @see #getParams
  1843. */
  1844. public void setBytes(int parameterIndex, byte x[]) throws SQLException {
  1845. checkParamIndex(parameterIndex);
  1846. if(params == null){
  1847. throw new SQLException("Set initParams() before setBytes");
  1848. }
  1849. params.put(new Integer(parameterIndex - 1), x);
  1850. }
  1851. /**
  1852. * Sets the designated parameter to the given <code>java.sql.Date</code>
  1853. * value. The driver converts this to an SQL
  1854. * <code>DATE</code> value when it sends it to the database.
  1855. * <P>
  1856. * The parameter value set by this method is stored internally and
  1857. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1858. * object's command when the method <code>execute</code> is called.
  1859. * Methods such as <code>execute</code> and <code>populate</code> must be
  1860. * provided in any class that extends this class and implements one or
  1861. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1862. * <P>
  1863. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1864. * as it is undefined in this class.
  1865. * <P>
  1866. * Calls made to the method <code>getParams</code> after this version
  1867. * of <code>setDate</code>
  1868. * has been called will return an array with the value to be set for
  1869. * placeholder parameter number <i>parameterIndex</i> being the <code>Date</code>
  1870. * object supplied as the second parameter.
  1871. * Note that because the numbering of elements in an array starts at zero,
  1872. * the array element that corresponds to placeholder parameter number
  1873. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  1874. *
  1875. * @param parameterIndex the ordinal number of the placeholder parameter
  1876. * in this <code>RowSet</code> object's command that is to be set.
  1877. * The first parameter is 1, the second is 2, and so on; must be
  1878. * <code>1</code> or greater
  1879. * @param x the parameter value
  1880. * @throws SQLException if an error occurs or the
  1881. * parameter index is out of bounds
  1882. * @see #getParams
  1883. */
  1884. public void setDate(int parameterIndex, java.sql.Date x) throws SQLException {
  1885. checkParamIndex(parameterIndex);
  1886. if(params == null){
  1887. throw new SQLException("Set initParams() before setDate");
  1888. }
  1889. params.put(new Integer(parameterIndex - 1), x);
  1890. }
  1891. /**
  1892. * Sets the designated parameter to the given <code>java.sql.Time</code>
  1893. * value. The driver converts this to an SQL <code>TIME</code> value
  1894. * when it sends it to the database.
  1895. * <P>
  1896. * The parameter value set by this method is stored internally and
  1897. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1898. * object's command when the method <code>execute</code> is called.
  1899. * Methods such as <code>execute</code> and <code>populate</code> must be
  1900. * provided in any class that extends this class and implements one or
  1901. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1902. * <P>
  1903. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1904. * as it is undefined in this class.
  1905. * <P>
  1906. * Calls made to the method <code>getParams</code> after this version
  1907. * of the method <code>setTime</code>
  1908. * has been called will return an array of the parameters that have been set.
  1909. * The parameter to be set for parameter placeholder number <i>parameterIndex</i>
  1910. * will be the <code>Time</code> object that was set as the second parameter
  1911. * to this method.
  1912. * <P>
  1913. * Note that because the numbering of elements in an array starts at zero,
  1914. * the array element that corresponds to placeholder parameter number
  1915. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  1916. *
  1917. * @param parameterIndex the ordinal number of the placeholder parameter
  1918. * in this <code>RowSet</code> object's command that is to be set.
  1919. * The first parameter is 1, the second is 2, and so on; must be
  1920. * <code>1</code> or greater
  1921. * @param x a <code>java.sql.Time</code> object, which is to be set as the value
  1922. * for placeholder parameter <i>parameterIndex</i>
  1923. * @throws SQLException if an error occurs or the
  1924. * parameter index is out of bounds
  1925. * @see #getParams
  1926. */
  1927. public void setTime(int parameterIndex, java.sql.Time x) throws SQLException {
  1928. checkParamIndex(parameterIndex);
  1929. if(params == null){
  1930. throw new SQLException("Set initParams() before setTime");
  1931. }
  1932. params.put(new Integer(parameterIndex - 1), x);
  1933. }
  1934. /**
  1935. * Sets the designated parameter to the given
  1936. * <code>java.sql.Timestamp</code> value.
  1937. * The driver converts this to an SQL <code>TIMESTAMP</code> value when it
  1938. * sends it to the database.
  1939. * <P>
  1940. * The parameter value set by this method is stored internally and
  1941. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1942. * object's command when the method <code>execute</code> is called.
  1943. * Methods such as <code>execute</code> and <code>populate</code> must be
  1944. * provided in any class that extends this class and implements one or
  1945. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  1946. * <P>
  1947. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  1948. * as it is undefined in this class.
  1949. * <P>
  1950. * Calls made to the method <code>getParams</code> after this version of
  1951. * <code>setTimestamp</code>
  1952. * has been called will return an array with the value for parameter placeholder
  1953. * number <i>parameterIndex</i> being the <code>Timestamp</code> object that was
  1954. * supplied as the second parameter to this method.
  1955. * Note that because the numbering of elements in an array starts at zero,
  1956. * the array element that corresponds to placeholder parameter number
  1957. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  1958. *
  1959. * @param parameterIndex the ordinal number of the placeholder parameter
  1960. * in this <code>RowSet</code> object's command that is to be set.
  1961. * The first parameter is 1, the second is 2, and so on; must be
  1962. * <code>1</code> or greater
  1963. * @param x a <code>java.sql.Timestamp</code> object
  1964. * @throws SQLException if an error occurs or the
  1965. * parameter index is out of bounds
  1966. * @see #getParams
  1967. */
  1968. public void setTimestamp(int parameterIndex, java.sql.Timestamp x) throws SQLException {
  1969. checkParamIndex(parameterIndex);
  1970. if(params == null){
  1971. throw new SQLException("Set initParams() before setTimestamp");
  1972. }
  1973. params.put(new Integer(parameterIndex - 1), x);
  1974. }
  1975. /**
  1976. * Sets the designated parameter to the given
  1977. * <code>java.io.InputStream</code> object,
  1978. * which will have the specified number of bytes.
  1979. * The contents of the stream will be read and sent to the database.
  1980. * This method throws an <code>SQLException</code> object if the number of bytes
  1981. * read and sent to the database is not equal to <i>length</i>.
  1982. * <P>
  1983. * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
  1984. * parameter, it may be more practical to send it via a
  1985. * <code>java.io.InputStream</code> object. A JDBC technology-enabled
  1986. * driver will read the data from the stream as needed until it reaches
  1987. * end-of-file. The driver will do any necessary conversion from ASCII to
  1988. * the database <code>CHAR</code> format.
  1989. *
  1990. * <P><B>Note:</B> This stream object can be either a standard
  1991. * Java stream object or your own subclass that implements the
  1992. * standard interface.
  1993. * <P>
  1994. * The parameter value set by this method is stored internally and
  1995. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  1996. * object's command when the method <code>execute</code> is called.
  1997. * Methods such as <code>execute</code> and <code>populate</code> must be
  1998. * provided in any class that extends this class and implements one or
  1999. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2000. * <P>
  2001. * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2002. * as it is undefined in this class.
  2003. * <P>
  2004. * Calls made to the method <code>getParams</code> after <code>setAsciiStream</code>
  2005. * has been called will return an array containing the parameter values that
  2006. * have been set. The element in the array that represents the values
  2007. * set with this method will itself be an array. The first element of that array
  2008. * is the given <code>java.io.InputStream</code> object.
  2009. * The second element is the value set for <i>length</i>.
  2010. * The third element is an internal <code>BaseRowSet</code> constant
  2011. * specifying that the stream passed to this method is an ASCII stream.
  2012. * The parameter number is indicated by an element's position in the array
  2013. * returned by the method <code>getParams</code>,
  2014. * with the first element being the value for the first placeholder parameter, the
  2015. * second element being the value for the second placeholder parameter, and so on.
  2016. * In other words, if the input stream being set is the value for the second
  2017. * placeholder parameter, the array containing it will be the second element in
  2018. * the array returned by <code>getParams</code>.
  2019. * <P>
  2020. * Note that because the numbering of elements in an array starts at zero,
  2021. * the array element that corresponds to placeholder parameter number
  2022. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2023. *
  2024. * @param parameterIndex the ordinal number of the placeholder parameter
  2025. * in this <code>RowSet</code> object's command that is to be set.
  2026. * The first parameter is 1, the second is 2, and so on; must be
  2027. * <code>1</code> or greater
  2028. * @param x the Java input stream that contains the ASCII parameter value
  2029. * @param length the number of bytes in the stream. This is the number of bytes
  2030. * the driver will send to the DBMS; lengths of 0 or less are
  2031. * are undefined but will cause an invalid length exception to be
  2032. * thrown in the underlying JDBC driver.
  2033. * @throws SQLException if an error occurs, the parameter index is out of bounds,
  2034. * or when connected to a data source, the number of bytes the driver reads
  2035. * and sends to the database is not equal to the number of bytes specified
  2036. * in <i>length</i>
  2037. * @see #getParams
  2038. */
  2039. public void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
  2040. Object asciiStream[];
  2041. checkParamIndex(parameterIndex);
  2042. asciiStream = new Object[3];
  2043. asciiStream[0] = x;
  2044. asciiStream[1] = new Integer(length);
  2045. asciiStream[2] = new Integer(ASCII_STREAM_PARAM);
  2046. if(params == null){
  2047. throw new SQLException("Set initParams() before setAsciiStream");
  2048. }
  2049. params.put(new Integer(parameterIndex - 1), asciiStream);
  2050. }
  2051. /**
  2052. * Sets the designated parameter to the given <code>java.io.InputStream</code>
  2053. * object, which will have the specified number of bytes.
  2054. * The contents of the stream will be read and sent to the database.
  2055. * This method throws an <code>SQLException</code> object if the number of bytes
  2056. * read and sent to the database is not equal to <i>length</i>.
  2057. * <P>
  2058. * When a very large binary value is input to a
  2059. * <code>LONGVARBINARY</code> parameter, it may be more practical
  2060. * to send it via a <code>java.io.InputStream</code> object.
  2061. * A JDBC technology-enabled driver will read the data from the
  2062. * stream as needed until it reaches end-of-file.
  2063. *
  2064. * <P><B>Note:</B> This stream object can be either a standard
  2065. * Java stream object or your own subclass that implements the
  2066. * standard interface.
  2067. * <P>
  2068. * The parameter value set by this method is stored internally and
  2069. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2070. * object's command when the method <code>execute</code> is called.
  2071. * Methods such as <code>execute</code> and <code>populate</code> must be
  2072. * provided in any class that extends this class and implements one or
  2073. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2074. *<P>
  2075. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2076. * as it is undefined in this class.
  2077. * <P>
  2078. * Calls made to the method <code>getParams</code> after <code>setBinaryStream</code>
  2079. * has been called will return an array containing the parameter values that
  2080. * have been set. In that array, the element that represents the values
  2081. * set with this method will itself be an array. The first element of that array
  2082. * is the given <code>java.io.InputStream</code> object.
  2083. * The second element is the value set for <i>length</i>.
  2084. * The third element is an internal <code>BaseRowSet</code> constant
  2085. * specifying that the stream passed to this method is a binary stream.
  2086. * The parameter number is indicated by an element's position in the array
  2087. * returned by the method <code>getParams</code>,
  2088. * with the first element being the value for the first placeholder parameter, the
  2089. * second element being the value for the second placeholder parameter, and so on.
  2090. * In other words, if the input stream being set is the value for the second
  2091. * placeholder parameter, the array containing it will be the second element in
  2092. * the array returned by <code>getParams</code>.
  2093. * <P>
  2094. * Note that because the numbering of elements in an array starts at zero,
  2095. * the array element that corresponds to placeholder parameter number
  2096. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2097. *
  2098. * @param parameterIndex the ordinal number of the placeholder parameter
  2099. * in this <code>RowSet</code> object's command that is to be set.
  2100. * The first parameter is 1, the second is 2, and so on; must be
  2101. * <code>1</code> or greater
  2102. * @param x the input stream that contains the binary value to be set
  2103. * @param length the number of bytes in the stream; lengths of 0 or less are
  2104. * are undefined but will cause an invalid length exception to be
  2105. * thrown in the underlying JDBC driver.
  2106. * @throws SQLException if an error occurs, the parameter index is out of bounds,
  2107. * or when connected to a data source, the number of bytes the driver
  2108. * reads and sends to the database is not equal to the number of bytes
  2109. * specified in <i>length</i>
  2110. * @see #getParams
  2111. */
  2112. public void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
  2113. Object binaryStream[];
  2114. checkParamIndex(parameterIndex);
  2115. binaryStream = new Object[3];
  2116. binaryStream[0] = x;
  2117. binaryStream[1] = new Integer(length);
  2118. binaryStream[2] = new Integer(BINARY_STREAM_PARAM);
  2119. if(params == null){
  2120. throw new SQLException("Set initParams() before setBinaryStream");
  2121. }
  2122. params.put(new Integer(parameterIndex - 1), binaryStream);
  2123. }
  2124. /**
  2125. * Sets the designated parameter to the given
  2126. * <code>java.io.InputStream</code> object, which will have the specified
  2127. * number of bytes. The contents of the stream will be read and sent
  2128. * to the database.
  2129. * This method throws an <code>SQLException</code> if the number of bytes
  2130. * read and sent to the database is not equal to <i>length</i>.
  2131. * <P>
  2132. * When a very large Unicode value is input to a
  2133. * <code>LONGVARCHAR</code> parameter, it may be more practical
  2134. * to send it via a <code>java.io.InputStream</code> object.
  2135. * A JDBC technology-enabled driver will read the data from the
  2136. * stream as needed, until it reaches end-of-file.
  2137. * The driver will do any necessary conversion from Unicode to the
  2138. * database <code>CHAR</code> format.
  2139. * The byte format of the Unicode stream must be Java UTF-8, as
  2140. * defined in the Java Virtual Machine Specification.
  2141. *
  2142. * <P><B>Note:</B> This stream object can be either a standard
  2143. * Java stream object or your own subclass that implements the
  2144. * standard interface.
  2145. * <P>
  2146. * This method is deprecated; the method <code>getCharacterStream</code>
  2147. * should be used in its place.
  2148. * <P>
  2149. * The parameter value set by this method is stored internally and
  2150. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2151. * object's command when the method <code>execute</code> is called.
  2152. * Calls made to the method <code>getParams</code> after <code>setUnicodeStream</code>
  2153. * has been called will return an array containing the parameter values that
  2154. * have been set. In that array, the element that represents the values
  2155. * set with this method will itself be an array. The first element of that array
  2156. * is the given <code>java.io.InputStream</code> object.
  2157. * The second element is the value set for <i>length</i>.
  2158. * The third element is an internal <code>BaseRowSet</code> constant
  2159. * specifying that the stream passed to this method is a Unicode stream.
  2160. * The parameter number is indicated by an element's position in the array
  2161. * returned by the method <code>getParams</code>,
  2162. * with the first element being the value for the first placeholder parameter, the
  2163. * second element being the value for the second placeholder parameter, and so on.
  2164. * In other words, if the input stream being set is the value for the second
  2165. * placeholder parameter, the array containing it will be the second element in
  2166. * the array returned by <code>getParams</code>.
  2167. * <P>
  2168. * Note that because the numbering of elements in an array starts at zero,
  2169. * the array element that corresponds to placeholder parameter number
  2170. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2171. *
  2172. * @param parameterIndex the ordinal number of the placeholder parameter
  2173. * in this <code>RowSet</code> object's command that is to be set.
  2174. * The first parameter is 1, the second is 2, and so on; must be
  2175. * <code>1</code> or greater
  2176. * @param x the <code>java.io.InputStream</code> object that contains the
  2177. * UNICODE parameter value
  2178. * @param length the number of bytes in the input stream
  2179. * @throws SQLException if an error occurs, the parameter index is out of bounds,
  2180. * or the number of bytes the driver reads and sends to the database is
  2181. * not equal to the number of bytes specified in <i>length</i>
  2182. * @deprecated getCharacterStream should be used in its place
  2183. * @see #getParams
  2184. */
  2185. public void setUnicodeStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
  2186. Object unicodeStream[];
  2187. checkParamIndex(parameterIndex);
  2188. unicodeStream = new Object[3];
  2189. unicodeStream[0] = x;
  2190. unicodeStream[1] = new Integer(length);
  2191. unicodeStream[2] = new Integer(UNICODE_STREAM_PARAM);
  2192. if(params == null){
  2193. throw new SQLException("Set initParams() before setUnicodeStream");
  2194. }
  2195. params.put(new Integer(parameterIndex - 1), unicodeStream);
  2196. }
  2197. /**
  2198. * Sets the designated parameter to the given <code>java.io.Reader</code>
  2199. * object, which will have the specified number of characters. The
  2200. * contents of the reader will be read and sent to the database.
  2201. * This method throws an <code>SQLException</code> if the number of bytes
  2202. * read and sent to the database is not equal to <i>length</i>.
  2203. * <P>
  2204. * When a very large Unicode value is input to a
  2205. * <code>LONGVARCHAR</code> parameter, it may be more practical
  2206. * to send it via a <code>Reader</code> object.
  2207. * A JDBC technology-enabled driver will read the data from the
  2208. * stream as needed until it reaches end-of-file.
  2209. * The driver will do any necessary conversion from Unicode to the
  2210. * database <code>CHAR</code> format.
  2211. * The byte format of the Unicode stream must be Java UTF-8, as
  2212. * defined in the Java Virtual Machine Specification.
  2213. *
  2214. * <P><B>Note:</B> This stream object can be either a standard
  2215. * Java stream object or your own subclass that implements the
  2216. * standard interface.
  2217. * <P>
  2218. * The parameter value set by this method is stored internally and
  2219. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2220. * object's command when the method <code>execute</code> is called.
  2221. * Methods such as <code>execute</code> and <code>populate</code> must be
  2222. * provided in any class that extends this class and implements one or
  2223. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2224. * <P>
  2225. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2226. * as it is undefined in this class.
  2227. * <P>
  2228. * Calls made to the method <code>getParams</code> after
  2229. * <code>setCharacterStream</code>
  2230. * has been called will return an array containing the parameter values that
  2231. * have been set. In that array, the element that represents the values
  2232. * set with this method will itself be an array. The first element of that array
  2233. * is the given <code>java.io.Reader</code> object.
  2234. * The second element is the value set for <i>length</i>.
  2235. * The parameter number is indicated by an element's position in the array
  2236. * returned by the method <code>getParams</code>,
  2237. * with the first element being the value for the first placeholder parameter, the
  2238. * second element being the value for the second placeholder parameter, and so on.
  2239. * In other words, if the reader being set is the value for the second
  2240. * placeholder parameter, the array containing it will be the second element in
  2241. * the array returned by <code>getParams</code>.
  2242. * <P>
  2243. * Note that because the numbering of elements in an array starts at zero,
  2244. * the array element that corresponds to placeholder parameter number
  2245. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2246. *
  2247. * @param parameterIndex the ordinal number of the placeholder parameter
  2248. * in this <code>RowSet</code> object's command that is to be set.
  2249. * The first parameter is 1, the second is 2, and so on; must be
  2250. * <code>1</code> or greater
  2251. * @param reader the <code>Reader</code> object that contains the
  2252. * Unicode data
  2253. * @param length the number of characters in the stream; lengths of 0 or
  2254. * less are undefined but will cause an invalid length exception to
  2255. * be thrown in the underlying JDBC driver.
  2256. * @throws SQLException if an error occurs, the parameter index is out of bounds,
  2257. * or when connected to a data source, the number of bytes the driver
  2258. * reads and sends to the database is not equal to the number of bytes
  2259. * specified in <i>length</i>
  2260. * @see #getParams
  2261. */
  2262. public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException {
  2263. Object charStream[];
  2264. checkParamIndex(parameterIndex);
  2265. charStream = new Object[2];
  2266. charStream[0] = reader;
  2267. charStream[1] = new Integer(length);
  2268. if(params == null){
  2269. throw new SQLException("Set initParams() before setCharacterStream");
  2270. }
  2271. params.put(new Integer(parameterIndex - 1), charStream);
  2272. }
  2273. /**
  2274. * Sets the designated parameter to an <code>Object</code> in the Java
  2275. * programming language. The second parameter must be an
  2276. * <code>Object</code> type. For integral values, the
  2277. * <code>java.lang</code> equivalent
  2278. * objects should be used. For example, use the class <code>Integer</code>
  2279. * for an <code>int</code>.
  2280. * <P>
  2281. * The driver converts this object to the specified
  2282. * target SQL type before sending it to the database.
  2283. * If the object has a custom mapping (is of a class implementing
  2284. * <code>SQLData</code>), the driver should call the method
  2285. * <code>SQLData.writeSQL</code> to write the object to the SQL
  2286. * data stream. If, on the other hand, the object is of a class
  2287. * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
  2288. * <code>Struct</code>, or <code>Array</code>,
  2289. * the driver should pass it to the database as a value of the
  2290. * corresponding SQL type.
  2291. * <P>
  2292. * <p>Note that this method may be used to pass database-
  2293. * specific abstract data types.
  2294. * <P>
  2295. * The parameter value set by this method is stored internally and
  2296. * will be supplied as the appropriate parameter in this <code>RowSet</code
  2297. * object's command when the method <code>execute</code> is called.
  2298. * Methods such as <code>execute</code> and <code>populate</code> must be
  2299. * provided in any class that extends this class and implements one or
  2300. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2301. * <P>
  2302. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2303. * as it is undefined in this class.
  2304. * <P>
  2305. * Calls made to the method <code>getParams</code> after this version of
  2306. * <code>setObject</code>
  2307. * has been called will return an array containing the parameter values that
  2308. * have been set. In that array, the element that represents the values
  2309. * set with this method will itself be an array. The first element of that array
  2310. * is the given <code>Object</code> instance, and the
  2311. * second element is the value set for <i>targetSqlType</i>. The
  2312. * third element is the value set for <i>scale</i>, which the driver will
  2313. * ignore if the type of the object being set is not
  2314. * <code>java.sql.Types.NUMERIC</code> or <code>java.sql.Types.DECIMAL</code>.
  2315. * The parameter number is indicated by an element's position in the array
  2316. * returned by the method <code>getParams</code>,
  2317. * with the first element being the value for the first placeholder parameter, the
  2318. * second element being the value for the second placeholder parameter, and so on.
  2319. * In other words, if the object being set is the value for the second
  2320. * placeholder parameter, the array containing it will be the second element in
  2321. * the array returned by <code>getParams</code>.
  2322. *<P>
  2323. * Note that because the numbering of elements in an array starts at zero,
  2324. * the array element that corresponds to placeholder parameter number
  2325. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2326. *
  2327. *
  2328. * @param parameterIndex the ordinal number of the placeholder parameter
  2329. * in this <code>RowSet</code> object's command that is to be set.
  2330. * The first parameter is 1, the second is 2, and so on; must be
  2331. * <code>1</code> or greater
  2332. * @param x the <code>Object</code> containing the input parameter value;
  2333. * must be an <code>Object</code> type
  2334. * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
  2335. * to be sent to the database. The <code>scale</code> argument may
  2336. * further qualify this type. If a non-standard <i>targetSqlType</i>
  2337. * is supplied, this method will not throw a <code>SQLException</code>.
  2338. * This allows implicit support for non-standard SQL types.
  2339. * @param scale for the types <code>java.sql.Types.DECIMAL</code> and
  2340. * <code>java.sql.Types.NUMERIC</code>, this is the number
  2341. * of digits after the decimal point. For all other types, this
  2342. * value will be ignored.
  2343. * @throws SQLException if an error occurs or the parameter index is out of bounds
  2344. * @see #getParams
  2345. */
  2346. public void setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException {
  2347. Object obj[];
  2348. checkParamIndex(parameterIndex);
  2349. obj = new Object[3];
  2350. obj[0] = x;
  2351. obj[1] = new Integer(targetSqlType);
  2352. obj[2] = new Integer(scale);
  2353. if(params == null){
  2354. throw new SQLException("Set initParams() before setObject");
  2355. }
  2356. params.put(new Integer(parameterIndex - 1), obj);
  2357. }
  2358. /**
  2359. * Sets the value of the designated parameter with the given
  2360. * <code>Object</code> value.
  2361. * This method is like <code>setObject(int parameterIndex, Object x, int
  2362. * targetSqlType, int scale)</code> except that it assumes a scale of zero.
  2363. * <P>
  2364. * The parameter value set by this method is stored internally and
  2365. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2366. * object's command when the method <code>execute</code> is called.
  2367. * Methods such as <code>execute</code> and <code>populate</code></code> must be
  2368. * provided in any class that extends this class and implements one or
  2369. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2370. * <P>
  2371. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2372. * as it is undefined in this class.
  2373. * <P>
  2374. * Calls made to the method <code>getParams</code> after this version of
  2375. * <code>setObject</code>
  2376. * has been called will return an array containing the parameter values that
  2377. * have been set. In that array, the element that represents the values
  2378. * set with this method will itself be an array. The first element of that array
  2379. * is the given <code>Object</code> instance.
  2380. * The second element is the value set for <i>targetSqlType</i>.
  2381. * The parameter number is indicated by an element's position in the array
  2382. * returned by the method <code>getParams</code>,
  2383. * with the first element being the value for the first placeholder parameter, the
  2384. * second element being the value for the second placeholder parameter, and so on.
  2385. * In other words, if the object being set is the value for the second
  2386. * placeholder parameter, the array containing it will be the second element in
  2387. * the array returned by <code>getParams</code>.
  2388. * <P>
  2389. * Note that because the numbering of elements in an array starts at zero,
  2390. * the array element that corresponds to placeholder parameter number
  2391. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2392. *
  2393. * @param parameterIndex the ordinal number of the placeholder parameter
  2394. * in this <code>RowSet</code> object's command that is to be set.
  2395. * The first parameter is 1, the second is 2, and so on; must be
  2396. * <code>1</code> or greater
  2397. * @param x the <code>Object</code> containing the input parameter value;
  2398. * must be an <code>Object</code> type
  2399. * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
  2400. * to be sent to the database. If a non-standard <i>targetSqlType</i>
  2401. * is supplied, this method will not throw a <code>SQLException</code>.
  2402. * This allows implicit support for non-standard SQL types.
  2403. * @throws SQLException if an error occurs or the parameter index
  2404. * is out of bounds
  2405. * @see #getParams
  2406. */
  2407. public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException {
  2408. Object obj[];
  2409. checkParamIndex(parameterIndex);
  2410. obj = new Object[2];
  2411. obj[0] = x;
  2412. obj[1] = new Integer(targetSqlType);
  2413. if (params == null){
  2414. throw new SQLException("Set initParams() before setObject");
  2415. }
  2416. params.put(new Integer(parameterIndex - 1), obj);
  2417. }
  2418. /**
  2419. * Sets the designated parameter to an <code>Object</code> in the Java
  2420. * programming language. The second parameter must be an
  2421. * <code>Object</code>
  2422. * type. For integral values, the <code>java.lang</code> equivalent
  2423. * objects should be used. For example, use the class <code>Integer</code>
  2424. * for an <code>int</code>.
  2425. * <P>
  2426. * The JDBC specification defines a standard mapping from
  2427. * Java <code>Object</code> types to SQL types. The driver will
  2428. * use this standard mapping to convert the given object
  2429. * to its corresponding SQL type before sending it to the database.
  2430. * If the object has a custom mapping (is of a class implementing
  2431. * <code>SQLData</code>), the driver should call the method
  2432. * <code>SQLData.writeSQL</code> to write the object to the SQL
  2433. * data stream.
  2434. * <P>
  2435. * If, on the other hand, the object is of a class
  2436. * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
  2437. * <code>Struct</code>, or <code>Array</code>,
  2438. * the driver should pass it to the database as a value of the
  2439. * corresponding SQL type.
  2440. * <P>
  2441. * This method throws an exception if there
  2442. * is an ambiguity, for example, if the object is of a class
  2443. * implementing more than one interface.
  2444. * <P>
  2445. * Note that this method may be used to pass database-specific
  2446. * abstract data types.
  2447. * <P>
  2448. * The parameter value set by this method is stored internally and
  2449. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2450. * object's command when the method <code>execute</code> is called.
  2451. * Methods such as <code>execute</code> and <code>populate</code> must be
  2452. * provided in any class that extends this class and implements one or
  2453. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2454. * <p>
  2455. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2456. * as it is undefined in this class.
  2457. * <P>
  2458. * After this method has been called, a call to the
  2459. * method <code>getParams</code>
  2460. * will return an object array of the current command parameters, which will
  2461. * include the <code>Object</code> set for placeholder parameter number
  2462. * <code>parameterIndex</code>.
  2463. * Note that because the numbering of elements in an array starts at zero,
  2464. * the array element that corresponds to placeholder parameter number
  2465. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2466. *
  2467. * @param parameterIndex the ordinal number of the placeholder parameter
  2468. * in this <code>RowSet</code> object's command that is to be set.
  2469. * The first parameter is 1, the second is 2, and so on; must be
  2470. * <code>1</code> or greater
  2471. * @param x the object containing the input parameter value
  2472. * @throws SQLException if an error occurs the
  2473. * parameter index is out of bounds, or there
  2474. * is ambiguity in the implementation of the
  2475. * object being set
  2476. * @see #getParams
  2477. */
  2478. public void setObject(int parameterIndex, Object x) throws SQLException {
  2479. checkParamIndex(parameterIndex);
  2480. if (params == null) {
  2481. throw new SQLException("Set initParams() before setObject");
  2482. }
  2483. params.put(new Integer(parameterIndex - 1), x);
  2484. }
  2485. /**
  2486. * Sets the designated parameter to the given <code>Ref</code> object in
  2487. * the Java programming language. The driver converts this to an SQL
  2488. * <code>REF</code> value when it sends it to the database. Internally, the
  2489. * <code>Ref</code> is represented as a <code>SerialRef</code> to ensure
  2490. * serializability.
  2491. * <P>
  2492. * The parameter value set by this method is stored internally and
  2493. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2494. * object's command when the method <code>execute</code> is called.
  2495. * Methods such as <code>execute</code> and <code>populate</code> must be
  2496. * provided in any class that extends this class and implements one or
  2497. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2498. * <p>
  2499. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2500. * as it is undefined in this class.
  2501. * <p>
  2502. * After this method has been called, a call to the
  2503. * method <code>getParams</code>
  2504. * will return an object array of the current command parameters, which will
  2505. * include the <code>Ref</code> object set for placeholder parameter number
  2506. * <code>parameterIndex</code>.
  2507. * Note that because the numbering of elements in an array starts at zero,
  2508. * the array element that corresponds to placeholder parameter number
  2509. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2510. *
  2511. * @param parameterIndex the ordinal number of the placeholder parameter
  2512. * in this <code>RowSet</code> object's command that is to be set.
  2513. * The first parameter is 1, the second is 2, and so on; must be
  2514. * <code>1</code> or greater
  2515. * @param ref a <code>Ref</code> object representing an SQL <code>REF</code>
  2516. * value; cannot be null
  2517. * @throws SQLException if an error occurs; the parameter index is out of
  2518. * bounds or the <code>Ref</code> object is <code>null</code> or
  2519. * the <code>Ref</code> object returns a <code>null</code> base type
  2520. * name.
  2521. * @see #getParams
  2522. * @see javax.sql.rowset.serial.SerialRef
  2523. */
  2524. public void setRef (int parameterIndex, Ref ref) throws SQLException {
  2525. checkParamIndex(parameterIndex);
  2526. if (params == null) {
  2527. throw new SQLException("Set initParams() before setRef");
  2528. }
  2529. params.put(new Integer(parameterIndex - 1), new SerialRef(ref));
  2530. }
  2531. /**
  2532. * Sets the designated parameter to the given <code>Blob</code> object in
  2533. * the Java programming language. The driver converts this to an SQL
  2534. * <code>BLOB</code> value when it sends it to the database. Internally,
  2535. * the <code>Blob</code> is represented as a <code>SerialBlob</code>
  2536. * to ensure serializability.
  2537. * <P>
  2538. * The parameter value set by this method is stored internally and
  2539. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2540. * object's command when the method <code>execute</code> is called.
  2541. * Methods such as <code>execute</code> and <code>populate</code> must be
  2542. * provided in any class that extends this class and implements one or
  2543. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2544. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2545. * as it is undefined in this class.
  2546. * <p>
  2547. * After this method has been called, a call to the
  2548. * method <code>getParams</code>
  2549. * will return an object array of the current command parameters, which will
  2550. * include the <code>Blob</code> object set for placeholder parameter number
  2551. * <code>parameterIndex</code>.
  2552. * Note that because the numbering of elements in an array starts at zero,
  2553. * the array element that corresponds to placeholder parameter number
  2554. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2555. *
  2556. * @param parameterIndex the ordinal number of the placeholder parameter
  2557. * in this <code>RowSet</code> object's command that is to be set.
  2558. * The first parameter is 1, the second is 2, and so on; must be
  2559. * <code>1</code> or greater
  2560. * @param x a <code>Blob</code> object representing an SQL
  2561. * <code>BLOB</code> value
  2562. * @throws SQLException if an error occurs or the
  2563. * parameter index is out of bounds
  2564. * @see #getParams
  2565. * @see javax.sql.rowset.serial.SerialBlob
  2566. */
  2567. public void setBlob (int parameterIndex, Blob x) throws SQLException {
  2568. checkParamIndex(parameterIndex);
  2569. if(params == null){
  2570. throw new SQLException("Set initParams() before setBlob");
  2571. }
  2572. params.put(new Integer(parameterIndex - 1), new SerialBlob(x));
  2573. }
  2574. /**
  2575. * Sets the designated parameter to the given <code>Clob</code> object in
  2576. * the Java programming language. The driver converts this to an SQL
  2577. * <code>CLOB</code> value when it sends it to the database. Internally, the
  2578. * <code>Clob</code> is represented as a <code>SerialClob</code> to ensure
  2579. * serializability.
  2580. * <P>
  2581. * The parameter value set by this method is stored internally and
  2582. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2583. * object's command when the method <code>execute</code> is called.
  2584. * Methods such as <code>execute</code> and <code>populate</code> must be
  2585. * provided in any class that extends this class and implements one or
  2586. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2587. * <p>
  2588. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2589. * as it is undefined in this class.
  2590. * <p>
  2591. * After this method has been called, a call to the
  2592. * method <code>getParams</code>
  2593. * will return an object array of the current command parameters, which will
  2594. * include the <code>Clob</code> object set for placeholder parameter number
  2595. * <code>parameterIndex</code>.
  2596. * Note that because the numbering of elements in an array starts at zero,
  2597. * the array element that corresponds to placeholder parameter number
  2598. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2599. *
  2600. * @param parameterIndex the ordinal number of the placeholder parameter
  2601. * in this <code>RowSet</code> object's command that is to be set.
  2602. * The first parameter is 1, the second is 2, and so on; must be
  2603. * <code>1</code> or greater
  2604. * @param x a <code>Clob</code> object representing an SQL
  2605. * <code>CLOB</code> value; cannot be null
  2606. * @throws SQLException if an error occurs; the parameter index is out of
  2607. * bounds or the <code>Clob</code> is null
  2608. * @see #getParams
  2609. * @see javax.sql.rowset.serial.SerialBlob
  2610. */
  2611. public void setClob (int parameterIndex, Clob x) throws SQLException {
  2612. checkParamIndex(parameterIndex);
  2613. if(params == null){
  2614. throw new SQLException("Set initParams() before setClob");
  2615. }
  2616. params.put(new Integer(parameterIndex - 1), new SerialClob(x));
  2617. }
  2618. /**
  2619. * Sets the designated parameter to an <code>Array</code> object in the
  2620. * Java programming language. The driver converts this to an SQL
  2621. * <code>ARRAY</code> value when it sends it to the database. Internally,
  2622. * the <code>Array</code> is represented as a <code>SerialArray</code>
  2623. * to ensure serializability.
  2624. * <P>
  2625. * The parameter value set by this method is stored internally and
  2626. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2627. * object's command when the method <code>execute</code> is called.
  2628. * Methods such as <code>execute</code> and <code>populate</code> must be
  2629. * provided in any class that extends this class and implements one or
  2630. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2631. * <P>
  2632. * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2633. * as it is undefined in this class.
  2634. * <p>
  2635. * After this method has been called, a call to the
  2636. * method <code>getParams</code>
  2637. * will return an object array of the current command parameters, which will
  2638. * include the <code>Array</code> object set for placeholder parameter number
  2639. * <code>parameterIndex</code>.
  2640. * Note that because the numbering of elements in an array starts at zero,
  2641. * the array element that corresponds to placeholder parameter number
  2642. * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
  2643. *
  2644. * @param parameterIndex the ordinal number of the placeholder parameter
  2645. * in this <code>RowSet</code> object's command that is to be set.
  2646. * The first parameter is 1, the second is 2, and so on; must be
  2647. * <code>1</code> or greater
  2648. * @param array an <code>Array</code> object representing an SQL
  2649. * <code>ARRAY</code> value; cannot be null. The <code>Array</code> object
  2650. * passed to this method must return a non-null Object for all
  2651. * <code>getArray()</code> method calls.
  2652. * @throws SQLException if an error occurs; the parameter index is out of
  2653. * bounds or the <code>ARRAY</code> is null
  2654. * @see #getParams
  2655. * @see javax.sql.rowset.serial.SerialArray
  2656. */
  2657. public void setArray (int parameterIndex, Array array) throws SQLException {
  2658. checkParamIndex(parameterIndex);
  2659. if (params == null){
  2660. throw new SQLException("Set initParams() before setArray");
  2661. }
  2662. params.put(new Integer(parameterIndex - 1), new SerialArray(array));
  2663. }
  2664. /**
  2665. * Sets the designated parameter to the given <code>java.sql.Date</code>
  2666. * object.
  2667. * When the DBMS does not store time zone information, the driver will use
  2668. * the given <code>Calendar</code> object to construct the SQL <code>DATE</code>
  2669. * value to send to the database. With a
  2670. * <code>Calendar</code> object, the driver can calculate the date
  2671. * taking into account a custom time zone. If no <code>Calendar</code>
  2672. * object is specified, the driver uses the time zone of the Virtual Machine
  2673. * that is running the application.
  2674. * <P>
  2675. * The parameter value set by this method is stored internally and
  2676. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2677. * object's command when the method <code>execute</code> is called.
  2678. * Methods such as <code>execute</code> and <code>populate</code> must be
  2679. * provided in any class that extends this class and implements one or
  2680. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2681. * <P>
  2682. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2683. * as it is undefined in this class.
  2684. * <P>
  2685. * Calls made to the method <code>getParams</code> after this version of
  2686. * <code>setDate</code>
  2687. * has been called will return an array containing the parameter values that
  2688. * have been set. In that array, the element that represents the values
  2689. * set with this method will itself be an array. The first element of that array
  2690. * is the given <code>java.sql.Date</code> object.
  2691. * The second element is the value set for <i>cal</i>.
  2692. * The parameter number is indicated by an element's position in the array
  2693. * returned by the method <code>getParams</code>,
  2694. * with the first element being the value for the first placeholder parameter, the
  2695. * second element being the value for the second placeholder parameter, and so on.
  2696. * In other words, if the date being set is the value for the second
  2697. * placeholder parameter, the array containing it will be the second element in
  2698. * the array returned by <code>getParams</code>.
  2699. * <P>
  2700. * Note that because the numbering of elements in an array starts at zero,
  2701. * the array element that corresponds to placeholder parameter number
  2702. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  2703. *
  2704. * @param parameterIndex the ordinal number of the placeholder parameter
  2705. * in this <code>RowSet</code> object's command that is to be set.
  2706. * The first parameter is 1, the second is 2, and so on; must be
  2707. * <code>1</code> or greater
  2708. * @param x a <code>java.sql.Date</code> object representing an SQL
  2709. * <code>DATE</code> value
  2710. * @param cal a <code>java.util.Calendar</code> object to use when
  2711. * when constructing the date
  2712. * @throws SQLException if an error occurs or the
  2713. * parameter index is out of bounds
  2714. * @see #getParams
  2715. */
  2716. public void setDate(int parameterIndex, java.sql.Date x, Calendar cal) throws SQLException {
  2717. Object date[];
  2718. checkParamIndex(parameterIndex);
  2719. date = new Object[2];
  2720. date[0] = x;
  2721. date[1] = cal;
  2722. if(params == null){
  2723. throw new SQLException("Set initParams() before setDate");
  2724. }
  2725. params.put(new Integer(parameterIndex - 1), date);
  2726. }
  2727. /**
  2728. * Sets the designated parameter to the given <code>java.sql.Time</code>
  2729. * object. The driver converts this
  2730. * to an SQL <code>TIME</code> value when it sends it to the database.
  2731. * <P>
  2732. * When the DBMS does not store time zone information, the driver will use
  2733. * the given <code>Calendar</code> object to construct the SQL <code>TIME</code>
  2734. * value to send to the database. With a
  2735. * <code>Calendar</code> object, the driver can calculate the date
  2736. * taking into account a custom time zone. If no <code>Calendar</code>
  2737. * object is specified, the driver uses the time zone of the Virtual Machine
  2738. * that is running the application.
  2739. * <P>
  2740. * The parameter value set by this method is stored internally and
  2741. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2742. * object's command when the method <code>execute</code> is called.
  2743. * Methods such as <code>execute</code> and <code>populate</code> must be
  2744. * provided in any class that extends this class and implements one or
  2745. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2746. * <P>
  2747. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2748. * as it is undefined in this class.
  2749. * <P>
  2750. * Calls made to the method <code>getParams</code> after this version of
  2751. * <code>setTime</code>
  2752. * has been called will return an array containing the parameter values that
  2753. * have been set. In that array, the element that represents the values
  2754. * set with this method will itself be an array. The first element of that array
  2755. * is the given <code>java.sql.Time</code> object.
  2756. * The second element is the value set for <i>cal</i>.
  2757. * The parameter number is indicated by an element's position in the array
  2758. * returned by the method <code>getParams</code>,
  2759. * with the first element being the value for the first placeholder parameter, the
  2760. * second element being the value for the second placeholder parameter, and so on.
  2761. * In other words, if the time being set is the value for the second
  2762. * placeholder parameter, the array containing it will be the second element in
  2763. * the array returned by <code>getParams</code>.
  2764. * <P>
  2765. * Note that because the numbering of elements in an array starts at zero,
  2766. * the array element that corresponds to placeholder parameter number
  2767. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  2768. *
  2769. * @param parameterIndex the ordinal number of the placeholder parameter
  2770. * in this <code>RowSet</code> object's command that is to be set.
  2771. * The first parameter is 1, the second is 2, and so on; must be
  2772. * <code>1</code> or greater
  2773. * @param x a <code>java.sql.Time</code> object
  2774. * @param cal the <code>java.util.Calendar</code> object the driver can use to
  2775. * construct the time
  2776. * @throws SQLException if an error occurs or the
  2777. * parameter index is out of bounds
  2778. * @see #getParams
  2779. */
  2780. public void setTime(int parameterIndex, java.sql.Time x, Calendar cal) throws SQLException {
  2781. Object time[];
  2782. checkParamIndex(parameterIndex);
  2783. time = new Object[2];
  2784. time[0] = x;
  2785. time[1] = cal;
  2786. if(params == null){
  2787. throw new SQLException("Set initParams() before setTime");
  2788. }
  2789. params.put(new Integer(parameterIndex - 1), time);
  2790. }
  2791. /**
  2792. * Sets the designated parameter to the given
  2793. * <code>java.sql.Timestamp</code> object. The driver converts this
  2794. * to an SQL <code>TIMESTAMP</code> value when it sends it to the database.
  2795. * <P>
  2796. * When the DBMS does not store time zone information, the driver will use
  2797. * the given <code>Calendar</code> object to construct the SQL <code>TIMESTAMP</code>
  2798. * value to send to the database. With a
  2799. * <code>Calendar</code> object, the driver can calculate the timestamp
  2800. * taking into account a custom time zone. If no <code>Calendar</code>
  2801. * object is specified, the driver uses the time zone of the Virtual Machine
  2802. * that is running the application.
  2803. * <P>
  2804. * The parameter value set by this method is stored internally and
  2805. * will be supplied as the appropriate parameter in this <code>RowSet</code>
  2806. * object's command when the method <code>execute</code> is called.
  2807. * Methods such as <code>execute</code> and <code>populate</code> must be
  2808. * provided in any class that extends this class and implements one or
  2809. * more of the standard JSR-114 <code>RowSet</code> interfaces.
  2810. * <P>
  2811. * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
  2812. * as it is undefined in this class.
  2813. * <P>
  2814. * Calls made to the method <code>getParams</code> after this version of
  2815. * <code>setTimestamp</code>
  2816. * has been called will return an array containing the parameter values that
  2817. * have been set. In that array, the element that represents the values
  2818. * set with this method will itself be an array. The first element of that array
  2819. * is the given <code>java.sql.Timestamp</code> object.
  2820. * The second element is the value set for <i>cal</i>.
  2821. * The parameter number is indicated by an element's position in the array
  2822. * returned by the method <code>getParams</code>,
  2823. * with the first element being the value for the first placeholder parameter, the
  2824. * second element being the value for the second placeholder parameter, and so on.
  2825. * In other words, if the timestamp being set is the value for the second
  2826. * placeholder parameter, the array containing it will be the second element in
  2827. * the array returned by <code>getParams</code>.
  2828. * <P>
  2829. * Note that because the numbering of elements in an array starts at zero,
  2830. * the array element that corresponds to placeholder parameter number
  2831. * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
  2832. *
  2833. * @param parameterIndex the ordinal number of the placeholder parameter
  2834. * in this <code>RowSet</code> object's command that is to be set.
  2835. * The first parameter is 1, the second is 2, and so on; must be
  2836. * <code>1</code> or greater
  2837. * @param x a <code>java.sql.Timestamp</code> object
  2838. * @param cal the <code>java.util.Calendar</code> object the driver can use to
  2839. * construct the timestamp
  2840. * @throws SQLException if an error occurs or the
  2841. * parameter index is out of bounds
  2842. * @see #getParams
  2843. */
  2844. public void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) throws SQLException {
  2845. Object timestamp[];
  2846. checkParamIndex(parameterIndex);
  2847. timestamp = new Object[2];
  2848. timestamp[0] = x;
  2849. timestamp[1] = cal;
  2850. if(params == null){
  2851. throw new SQLException("Set initParams() before setTimestamp");
  2852. }
  2853. params.put(new Integer(parameterIndex - 1), timestamp);
  2854. }
  2855. /**
  2856. * Clears all of the current parameter values in this <code>RowSet</code>
  2857. * object's internal representation of the parameters to be set in
  2858. * this <code>RowSet</code> object's command when it is executed.
  2859. * <P>
  2860. * In general, parameter values remain in force for repeated use in
  2861. * this <code>RowSet</code> object's command. Setting a parameter value with the
  2862. * setter methods automatically clears the value of the
  2863. * designated parameter and replaces it with the new specified value.
  2864. * <P>
  2865. * This method is called internally by the <code>setCommand</code>
  2866. * method to clear all of the parameters set for the previous command.
  2867. * <P>
  2868. * Furthermore, this method differs from the <code>initParams</code>
  2869. * method in that it maintains the schema of the <code>RowSet</code> object.
  2870. *
  2871. * @throws SQLException if an error occurs clearing the parameters
  2872. */
  2873. public void clearParameters() throws SQLException {
  2874. params.clear();
  2875. }
  2876. /**
  2877. * Retrieves an array containing the parameter values (both Objects and
  2878. * primitives) that have been set for this
  2879. * <code>RowSet</code> object's command and throws an <code>SQLException</code> object
  2880. * if all parameters have not been set. Before the command is sent to the
  2881. * DBMS to be executed, these parameters will be substituted
  2882. * for placeholder parameters in the <code>PreparedStatement</code> object
  2883. * that is the command for a <code>RowSet</code> implementation extending
  2884. * the <code>BaseRowSet</code> class.
  2885. * <P>
  2886. * Each element in the array that is returned is an <code>Object</code> instance
  2887. * that contains the values of the parameters supplied to a setter method.
  2888. * The order of the elements is determined by the value supplied for
  2889. * <i>parameterIndex</i>. If the setter method takes only the parameter index
  2890. * and the value to be set (possibly null), the array element will contain the value to be set
  2891. * (which will be expressed as an <code>Object</code>). If there are additional
  2892. * parameters, the array element will itself be an array containing the value to be set
  2893. * plus any additional parameter values supplied to the setter method. If the method
  2894. * sets a stream, the array element includes the type of stream being supplied to the
  2895. * method. These additional parameters are for the use of the driver or the DBMS and may or
  2896. * may not be used.
  2897. * <P>
  2898. * NOTE: Stored parameter values of types <code>Array</code>, <code>Blob</code>,
  2899. * <code>Clob</code> and <code>Ref</code> are returned as <code>SerialArray</code>,
  2900. * <code>SerialBlob</code>, <code>SerialClob</code> and <code>SerialRef</code>
  2901. * respectively.
  2902. *
  2903. * @return an array of <code>Object</code> instances that includes the
  2904. * parameter values that may be set in this <code>RowSet</code> object's
  2905. * command; an empty array if no parameters have been set
  2906. * @throws SQLException if an error occurs retrieveing the object array of
  2907. * parameters of this <code>RowSet</code> object or if not all parameters have
  2908. * been set
  2909. */
  2910. public Object[] getParams() throws SQLException {
  2911. if (params == null) {
  2912. initParams();
  2913. Object [] paramsArray = new Object[params.size()];
  2914. return paramsArray;
  2915. } else {
  2916. // The parameters may be set in random order
  2917. // but all must be set, check to verify all
  2918. // have been set till the last parameter
  2919. // else throw exception.
  2920. Object[] paramsArray = new Object[params.size()];
  2921. for (int i = 0; i < params.size(); i++) {
  2922. paramsArray[i] = params.get(new Integer(i));
  2923. if (paramsArray[i] == null) {
  2924. throw new SQLException("missing parameter: " + (i + 1));
  2925. } //end if
  2926. } //end for
  2927. return paramsArray;
  2928. } //end if
  2929. } //end getParams
  2930. static final long serialVersionUID = 4886719666485113312L;
  2931. } //end class