92 * <P>
93 * NOTE: In order to use a <code>DataSource</code> object for making a
94 * connection, the <code>DataSource</code> object must have been registered
95 * with a naming service that uses the Java Naming and Directory
96 * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
97 * is usually done by a person acting in the capacity of a system administrator.
98 * <P>
99 * <h3>3.0 Setting the Command and Its Parameters</h3>
100 * When a rowset gets its data from a relational database, it executes a command (a query)
101 * that produces a <code>ResultSet</code> object. This query is the command that is set
102 * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
103 * data from the <code>ResultSet</code> object into itself. If the query
104 * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
105 * are used to set these values. All setter methods allow these values to be set
106 * to <code>null</code> if required.
107 * <P>
108 * The following code fragment illustrates how the
109 * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
110 * object <code>crs</code> might have its command property set. Note that if a
111 * tool is used to set properties, this is the code that the tool would use.
112 * <PRE>
113 * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
114 * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
115 * </PRE>
116 * <P>
117 * In this example, the values for <code>CREDIT_LIMIT</code> and
118 * <code>REGION</code> are placeholder parameters, which are indicated with a
119 * question mark (?). The first question mark is placeholder parameter number
120 * <code>1</code>, the second question mark is placeholder parameter number
121 * <code>2</code>, and so on. Any placeholder parameters must be set with
122 * values before the query can be executed. To set these
123 * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
124 * methods, similar to those provided by the <code>PreparedStatement</code>
125 * interface, for setting values of each data type. A <code>RowSet</code> object stores the
126 * parameter values internally, and its <code>execute</code> method uses them internally
127 * to set values for the placeholder parameters
128 * before it sends the command to the DBMS to be executed.
129 * <P>
130 * The following code fragment demonstrates
131 * setting the two parameters in the query from the previous example.
132 * <PRE>
133 * crs.setInt(1, 5000);
134 * crs.setString(2, "West");
135 * </PRE>
136 * If the <code>execute</code> method is called at this point, the query
137 * sent to the DBMS will be:
138 * <PRE>
139 * "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
140 * "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
141 * </PRE>
142 * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and
143 * <code>Ref</code> objects as a command parameter, stores these values as
144 * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>
145 * and <code>SerialRef</code> objects respectively.
146 *
147 * <h3>4.0 Handling of Parameters Behind the Scenes</h3>
148 *
149 * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,
150 * those that set properties and those that set placeholder parameters. The setter
151 * methods discussed in this section are those that set placeholder parameters.
152 * <P>
153 * The placeholder parameters set with the <code>BaseRowSet</code> setter methods
154 * are stored as objects in an internal <code>Hashtable</code> object.
155 * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>
156 * is stored as <code>Byte</code> object, and <code>int</code> is stored as
157 * an <code>Integer</code> object.
158 * When the method <code>execute</code> is called, the values in the
159 * <code>Hashtable</code> object are substituted for the appropriate placeholder
160 * parameters in the command.
161 * <P)>
162 * A call to the method <code>getParams</code> returns the values stored in the
163 * <code>Hashtable</code> object as an array of <code>Object</code> instances.
164 * An element in this array may be a simple <code>Object</code> instance or an
165 * array (which is a type of <code>Object</code>). The particular setter method used
166 * determines whether an element in this array is an <code>Object</code> or an array.
167 * <P>
168 * The majority of methods for setting placeholder parameters take two parameters,
169 * with the first parameter
170 * indicating which placeholder parameter is to be set, and the second parameter
171 * giving the value to be set. Methods such as <code>setInt</code>,
172 * <code>setString</code>, <code>setBoolean</code>, and <code>setLong</code> fall into
173 * this category. After these methods have been called, a call to the method
174 * <code>getParams</code> will return an array with the values that have been set. Each
175 * element in the array is an <code>Object</code> instance representing the
176 * values that have been set. The order of these values in the array is determined by the
177 * <code>int</code> (the first parameter) passed to the setter method. The values in the
178 * array are the values (the second parameter) passed to the setter method.
179 * In other words, the first element in the array is the value
180 * to be set for the first placeholder parameter in the <code>RowSet</code> object's
181 * command. The second element is the value to
2518 * <code>Object</code> type. For integral values, the
2519 * <code>java.lang</code> equivalent
2520 * objects should be used. For example, use the class <code>Integer</code>
2521 * for an <code>int</code>.
2522 * <P>
2523 * The driver converts this object to the specified
2524 * target SQL type before sending it to the database.
2525 * If the object has a custom mapping (is of a class implementing
2526 * <code>SQLData</code>), the driver should call the method
2527 * <code>SQLData.writeSQL</code> to write the object to the SQL
2528 * data stream. If, on the other hand, the object is of a class
2529 * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2530 * <code>Struct</code>, or <code>Array</code>,
2531 * the driver should pass it to the database as a value of the
2532 * corresponding SQL type.
2533 * <P>
2534 * <p>Note that this method may be used to pass database-
2535 * specific abstract data types.
2536 * <P>
2537 * The parameter value set by this method is stored internally and
2538 * will be supplied as the appropriate parameter in this <code>RowSet</code
2539 * object's command when the method <code>execute</code> is called.
2540 * Methods such as <code>execute</code> and <code>populate</code> must be
2541 * provided in any class that extends this class and implements one or
2542 * more of the standard JSR-114 <code>RowSet</code> interfaces.
2543 * <P>
2544 * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2545 * as it is undefined in this class.
2546 * <P>
2547 * Calls made to the method <code>getParams</code> after this version of
2548 * <code>setObject</code>
2549 * has been called will return an array containing the parameter values that
2550 * have been set. In that array, the element that represents the values
2551 * set with this method will itself be an array. The first element of that array
2552 * is the given <code>Object</code> instance, and the
2553 * second element is the value set for <i>targetSqlType</i>. The
2554 * third element is the value set for <i>scale</i>, which the driver will
2555 * ignore if the type of the object being set is not
2556 * <code>java.sql.Types.NUMERIC</code> or <code>java.sql.Types.DECIMAL</code>.
2557 * The parameter number is indicated by an element's position in the array
2558 * returned by the method <code>getParams</code>,
|
92 * <P>
93 * NOTE: In order to use a <code>DataSource</code> object for making a
94 * connection, the <code>DataSource</code> object must have been registered
95 * with a naming service that uses the Java Naming and Directory
96 * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
97 * is usually done by a person acting in the capacity of a system administrator.
98 * <P>
99 * <h3>3.0 Setting the Command and Its Parameters</h3>
100 * When a rowset gets its data from a relational database, it executes a command (a query)
101 * that produces a <code>ResultSet</code> object. This query is the command that is set
102 * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
103 * data from the <code>ResultSet</code> object into itself. If the query
104 * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
105 * are used to set these values. All setter methods allow these values to be set
106 * to <code>null</code> if required.
107 * <P>
108 * The following code fragment illustrates how the
109 * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
110 * object <code>crs</code> might have its command property set. Note that if a
111 * tool is used to set properties, this is the code that the tool would use.
112 * <PRE>{@code
113 * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
114 * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
115 * }</PRE>
116 * <P>
117 * In this example, the values for <code>CREDIT_LIMIT</code> and
118 * <code>REGION</code> are placeholder parameters, which are indicated with a
119 * question mark (?). The first question mark is placeholder parameter number
120 * <code>1</code>, the second question mark is placeholder parameter number
121 * <code>2</code>, and so on. Any placeholder parameters must be set with
122 * values before the query can be executed. To set these
123 * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
124 * methods, similar to those provided by the <code>PreparedStatement</code>
125 * interface, for setting values of each data type. A <code>RowSet</code> object stores the
126 * parameter values internally, and its <code>execute</code> method uses them internally
127 * to set values for the placeholder parameters
128 * before it sends the command to the DBMS to be executed.
129 * <P>
130 * The following code fragment demonstrates
131 * setting the two parameters in the query from the previous example.
132 * <PRE>{@code
133 * crs.setInt(1, 5000);
134 * crs.setString(2, "West");
135 * }</PRE>
136 * If the <code>execute</code> method is called at this point, the query
137 * sent to the DBMS will be:
138 * <PRE>{@code
139 * "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
140 * "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
141 * }</PRE>
142 * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and
143 * <code>Ref</code> objects as a command parameter, stores these values as
144 * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>
145 * and <code>SerialRef</code> objects respectively.
146 *
147 * <h3>4.0 Handling of Parameters Behind the Scenes</h3>
148 *
149 * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,
150 * those that set properties and those that set placeholder parameters. The setter
151 * methods discussed in this section are those that set placeholder parameters.
152 * <P>
153 * The placeholder parameters set with the <code>BaseRowSet</code> setter methods
154 * are stored as objects in an internal <code>Hashtable</code> object.
155 * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>
156 * is stored as <code>Byte</code> object, and <code>int</code> is stored as
157 * an <code>Integer</code> object.
158 * When the method <code>execute</code> is called, the values in the
159 * <code>Hashtable</code> object are substituted for the appropriate placeholder
160 * parameters in the command.
161 * <P>
162 * A call to the method <code>getParams</code> returns the values stored in the
163 * <code>Hashtable</code> object as an array of <code>Object</code> instances.
164 * An element in this array may be a simple <code>Object</code> instance or an
165 * array (which is a type of <code>Object</code>). The particular setter method used
166 * determines whether an element in this array is an <code>Object</code> or an array.
167 * <P>
168 * The majority of methods for setting placeholder parameters take two parameters,
169 * with the first parameter
170 * indicating which placeholder parameter is to be set, and the second parameter
171 * giving the value to be set. Methods such as <code>setInt</code>,
172 * <code>setString</code>, <code>setBoolean</code>, and <code>setLong</code> fall into
173 * this category. After these methods have been called, a call to the method
174 * <code>getParams</code> will return an array with the values that have been set. Each
175 * element in the array is an <code>Object</code> instance representing the
176 * values that have been set. The order of these values in the array is determined by the
177 * <code>int</code> (the first parameter) passed to the setter method. The values in the
178 * array are the values (the second parameter) passed to the setter method.
179 * In other words, the first element in the array is the value
180 * to be set for the first placeholder parameter in the <code>RowSet</code> object's
181 * command. The second element is the value to
2518 * <code>Object</code> type. For integral values, the
2519 * <code>java.lang</code> equivalent
2520 * objects should be used. For example, use the class <code>Integer</code>
2521 * for an <code>int</code>.
2522 * <P>
2523 * The driver converts this object to the specified
2524 * target SQL type before sending it to the database.
2525 * If the object has a custom mapping (is of a class implementing
2526 * <code>SQLData</code>), the driver should call the method
2527 * <code>SQLData.writeSQL</code> to write the object to the SQL
2528 * data stream. If, on the other hand, the object is of a class
2529 * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2530 * <code>Struct</code>, or <code>Array</code>,
2531 * the driver should pass it to the database as a value of the
2532 * corresponding SQL type.
2533 * <P>
2534 * <p>Note that this method may be used to pass database-
2535 * specific abstract data types.
2536 * <P>
2537 * The parameter value set by this method is stored internally and
2538 * will be supplied as the appropriate parameter in this <code>RowSet</code>
2539 * object's command when the method <code>execute</code> is called.
2540 * Methods such as <code>execute</code> and <code>populate</code> must be
2541 * provided in any class that extends this class and implements one or
2542 * more of the standard JSR-114 <code>RowSet</code> interfaces.
2543 * <P>
2544 * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2545 * as it is undefined in this class.
2546 * <P>
2547 * Calls made to the method <code>getParams</code> after this version of
2548 * <code>setObject</code>
2549 * has been called will return an array containing the parameter values that
2550 * have been set. In that array, the element that represents the values
2551 * set with this method will itself be an array. The first element of that array
2552 * is the given <code>Object</code> instance, and the
2553 * second element is the value set for <i>targetSqlType</i>. The
2554 * third element is the value set for <i>scale</i>, which the driver will
2555 * ignore if the type of the object being set is not
2556 * <code>java.sql.Types.NUMERIC</code> or <code>java.sql.Types.DECIMAL</code>.
2557 * The parameter number is indicated by an element's position in the array
2558 * returned by the method <code>getParams</code>,
|