An abstract class providing a RowSet object with its basic functionality. The basic functions include having properties and sending event notifications, which all JavaBeans components must implement.

1.0 Overview

The BaseRowSet class provides the core functionality for all RowSet implementations, and all standard implementations may use this class in combination with one or more RowSet interfaces in order to provide a standard vendor-specific implementation. To clarify, all implementations must implement at least one of the RowSet interfaces (JdbcRowSet, CachedRowSet, JoinRowSet, FilteredRowSet, or WebRowSet). This means that any implementation that extends the BaseRowSet class must also implement one of the RowSet interfaces.

The BaseRowSet class provides the following:

• Properties
  • Fields for storing current properties
  • Methods for getting and setting properties
• Event notification
• A complete set of setter methods for setting the parameters in a RowSet object's command
• Streams
  • Fields for storing stream instances
  • Constants for indicating the type of a stream

2.0 Setting Properties

All rowsets maintain a set of properties, which will usually be set using a tool. The number and kinds of properties a rowset has will vary, depending on what the RowSet implementation does and how it gets its data. For example, rowsets that get their data from a ResultSet object need to set the properties that are required for making a database connection. If a RowSet object uses the DriverManager facility to make a connection, it needs to set a property for the JDBC URL that identifies the appropriate driver, and it needs to set the properties that give the user name and password. If, on the other hand, the rowset uses a DataSource object to make the connection, which is the preferred method, it does not need to set the property for the JDBC URL. Instead, it needs to set the property for the logical name of the data source along with the properties for the user name and password.

3.0 Setting the Command and Its Parameters

When a rowset gets its data from a relational database, it executes a command (a query) that produces a ResultSet object. This query is the command that is set for the RowSet object's command property. The rowset populates itself with data by reading the data from the ResultSet object into itself. If the query contains placeholders for values to be set, the BaseRowSet setter methods are used to set these values. All setter methods allow these values to be set to null if required.

The following code fragment illustrates how the CachedRowSet object crs might have its command property set. Note that if a tool is used to set properties, this is the code that the tool would use.

crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                  "WHERE CREDIT_LIMIT > ? AND REGION = ?");

In this example, the values for CREDIT_LIMIT and REGION are placeholder parameters, which are indicated with a question mark (?). The first question mark is placeholder parameter number 1, the second question mark is placeholder parameter number 2, and so on. Any placeholder parameters must be set with values before the query can be executed. To set these placeholder parameters, the BaseRowSet class provides a set of setter methods, similar to those provided by the PreparedStatement interface, for setting values of each data type. A RowSet object stores the parameter values internally, and its execute method uses them internally to set values for the placeholder parameters before it sends the command to the DBMS to be executed.

The following code fragment demonstrates setting the two parameters in the query from the previous example.

crs.setInt(1, 5000);
   crs.setString(2, "West");

If the execute method is called at this point, the query sent to the DBMS will be:

"SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                  "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"

NOTE: Setting Array, Clob, Blob and Ref objects as a command parameter, stores these values as SerialArray, SerialClob, SerialBlob and SerialRef objects respectively.

4.0 Handling of Parameters Behind the Scenes

The placeholder parameters set with the BaseRowSet setter methods are stored as objects in an internal Hashtable object. Primitives are stored as their Object type. For example, byte is stored as Byte object, and int is stored as an Integer object. When the method execute is called, the values in the Hashtable object are substituted for the appropriate placeholder parameters in the command.

A call to the method getParams returns the values stored in the Hashtable object as an array of Object instances. An element in this array may be a simple Object instance or an array (which is a type of Object). The particular setter method used determines whether an element in this array is an Object or an array.

The majority of methods for setting placeholder parameters take two parameters, with the first parameter indicating which placeholder parameter is to be set, and the second parameter giving the value to be set. Methods such as setInt, setString, setBoolean, and setLong fall into this category. After these methods have been called, a call to the method getParams will return an array with the values that have been set. Each element in the array is an Object instance representing the values that have been set. The order of these values in the array is determined by the int (the first parameter) passed to the setter method. The values in the array are the values (the second parameter) passed to the setter method. In other words, the first element in the array is the value to be set for the first placeholder parameter in the RowSet object's command. The second element is the value to be set for the second placeholder parameter, and so on.

Several setter methods send the driver and DBMS information beyond the value to be set. When the method getParams is called after one of these setter methods has been used, the elements in the array will themselves be arrays to accommodate the additional information. In this category, the method setNull is a special case because one version takes only two parameters (setNull(int parameterIndex, int SqlType)). Nevertheless, it requires an array to contain the information that will be passed to the driver and DBMS. The first element in this array is the value to be set, which is null, and the second element is the int supplied for sqlType, which indicates the type of SQL value that is being set to null. This information is needed by some DBMSs and is therefore required in order to ensure that applications are portable. The other version is intended to be used when the value to be set to null is a user-defined type. It takes three parameters (setNull(int parameterIndex, int sqlType, String typeName)) and also requires an array to contain the information to be passed to the driver and DBMS. The first two elements in this array are the same as for the first version of setNull. The third element, typeName, gives the SQL name of the user-defined type. As is true with the other setter methods, the number of the placeholder parameter to be set is indicated by an element's position in the array returned by getParams. So, for example, if the parameter supplied to setNull is 2, the second element in the array returned by getParams will be an array of two or three elements.

Some methods, such as setObject and setDate have versions that take more than two parameters, with the extra parameters giving information to the driver or the DBMS. For example, the methods setDate, setTime, and setTimestamp can take a Calendar object as their third parameter. If the DBMS does not store time zone information, the driver uses the Calendar object to construct the Date, Time, or Timestamp object being set. As is true with other methods that provide additional information, the element in the array returned by getParams is an array instead of a simple Object instance.

The methods setAsciiStream, setBinaryStream, setCharacterStream, and setUnicodeStream (which is deprecated, so applications should use getCharacterStream instead) take three parameters, so for them, the element in the array returned by getParams is also an array. What is different about these setter methods is that in addition to the information provided by parameters, the array contains one of the BaseRowSet constants indicating the type of stream being set.

5.0 Event Notification

The BaseRowSet class provides the event notification mechanism for rowsets. It contains the field listeners, methods for adding and removing listeners, and methods for notifying listeners of changes.

A listener is an object that has implemented the RowSetListener interface. If it has been added to a RowSet object's list of listeners, it will be notified when an event occurs on that RowSet object. Each listener's implementation of the RowSetListener methods defines what that object will do when it is notified that an event has occurred.

There are three possible events for a RowSet object:

1. the cursor moves
2. an individual row is changed (updated, deleted, or inserted)
3. the contents of the entire RowSet object are changed

The BaseRowSet method used for the notification indicates the type of event that has occurred. For example, the method notifyRowChanged indicates that a row has been updated, deleted, or inserted. Each of the notification methods creates a RowSetEvent object, which is supplied to the listener in order to identify the RowSet object on which the event occurred. What the listener does with this information, which may be nothing, depends on how it was implemented.

6.0 Default Behavior

A default BaseRowSet object is initialized with many starting values. The following is true of a default RowSet instance that extends the BaseRowSet class:

• Has a scrollable cursor and does not show changes made by others.
• Is updatable.
• Does not show rows that have been deleted.
• Has no time limit for how long a driver may take to execute the RowSet object's command.
• Has no limit for the number of rows it may contain.
• Has no limit for the number of bytes a column may contain.

  Note

  This limit applies only to columns that hold values of the following types: BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR.

• Will not see uncommitted data (make "dirty" reads).
• Has escape processing turned on.
• Has its connection's type map set to null.
• Has an empty Vector object for storing the values set for the placeholder parameters in the RowSet object's command.

If other values are desired, an application must set the property values explicitly. For example, the following line of code sets the maximum number of rows for the CachedRowSet object crs to 500.

   crs.setMaxRows(500);

Methods implemented in extensions of this BaseRowSet class must throw an SQLException object for any violation of the defined assertions. Also, if the extending class overrides and reimplements any BaseRowSet method and encounters connectivity or underlying data source issues, that method may in addition throw an SQLException object for that reason.