An abstract class providing a
object with its basic functionality. The basic functions include having properties and sending event notifications, which all JavaBeans™ components must implement.
class provides the core functionality for all
implementations, and all standard implementations may
use this class in combination with one or more
interfaces in order to provide a standard vendor-specific implementation. To clarify, all implementations must implement at least one of the
). This means that any implementation that extends the
class must also implement one of the
BaseRowSet class provides the following:
- Fields for storing current properties
- Methods for getting and setting properties
A complete set of setter methods for setting the parameters in a
RowSet object's command
- 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
implementation does and how it gets its data. For example, rowsets that get their data from a
object need to set the properties that are required for making a database connection. If a
object uses the
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
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.
NOTE: In order to use a
DataSource object for making a connection, the
DataSource object must have been registered with a naming service that uses the Java Naming and Directory Interface™ (JNDI) API. This registration is usually done by a person acting in the capacity of a system administrator.
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
object. This query is the command that is set for the
object's command property. The rowset populates itself with data by reading the data from the
object into itself. If the query contains placeholders for values to be set, the
setter methods are used to set these values. All setter methods allow these values to be set to
The following code fragment illustrates how the
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
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.
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'"
objects as a command parameter, stores these values as
4.0 Handling of Parameters Behind the Scenes
class provides two kinds of setter methods, those that set properties and those that set placeholder parameters. The setter methods discussed in this section are those that set placeholder parameters.
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
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
2, the second element in the array returned by
getParams will be an array of two or three elements.
Some methods, such as
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
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
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
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.
NOTE: The method
getParams is called internally by
RowSet implementations extending this class; it is not normally called by an application programmer directly.
5.0 Event Notification
class provides the event notification mechanism for rowsets. It contains the field
, 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
- the cursor moves
- an individual row is changed (updated, deleted, or inserted)
- the contents of the entire
RowSet object are changed
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
object is initialized with many starting values. The following is true of a default
instance that extends the
- 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:
- Will not see uncommitted data (make "dirty" reads).
- Has escape processing turned on.
- Has its connection's type map set to
- 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.
Methods implemented in extensions of this
object for any violation of the defined assertions. Also, if the extending class overrides and reimplements any
method and encounters connectivity or underlying data source issues, that method may
in addition throw an
object for that reason.