|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object![]()
![]()
![]()
javax.sql.rowset.BaseRowSet
, Cloneable

public abstract class BaseRowSet

, Cloneable

An abstract class providing a RowSet object with its basic functionality.
The basic functions include having properties and sending event notifications,
which all JavaBeansTM components must implement.
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:
RowSet object's command
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.
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
InterfaceTM (JNDI) API. This registration
is usually done by a person acting in the capacity of a system administrator.
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
CachedRowSetTM
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.
BaseRowSet 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 getInt,
getString, getBoolean, and getLong 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 drivern 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.
NOTE: The method getParams is called internally by
RowSet implementations extending this class; it is not normally called by an
application programmer directly.
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:
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.
BaseRowSet object is initialized with many starting values.
The following is true of a default RowSet instance that extends
the BaseRowSet class:
RowSet object's command.
BINARY, VARBINARY,
LONGVARBINARY, CHAR, VARCHAR,
and LONGVARCHAR.
null.
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.
| Field Summary | |
|---|---|
static int |
ASCII_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object
that a given parameter is an ASCII stream. |
protected InputStream |
asciiStream
The InputStream object that will be
returned by the method getAsciiStream,
which is specified in the ResultSet interface. |
static int |
BINARY_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object
that a given parameter is a binary stream. |
protected InputStream |
binaryStream
The InputStream object that will be
returned by the method getBinaryStream, which is
specified in the ResultSet interface. |
protected Reader |
charStream
The Reader object that will be
returned by the method getCharacterStream,
which is specified in the ResultSet interface. |
static int |
UNICODE_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object
that a given parameter is a Unicode stream. |
protected InputStream |
unicodeStream
The InputStream object that will be
returned by the method getUnicodeStream,
which is specified in the ResultSet interface. |
| Constructor Summary | |
|---|---|
BaseRowSet
Constructs a new BaseRowSet object initialized with
a default Vector object for its listeners
field. |
|
| Method Summary | |
|---|---|
void |
addRowSetListener
The listener will be notified whenever an event occurs on this RowSet
object. |
void |
clearParameters
Clears all of the current parameter values in this RowSet
object's internal representation of the parameters to be set in
this RowSet object's command when it is executed. |
String |
getCommand
Retrieves the SQL query that is the command for this RowSet object. |
int |
getConcurrency
Returns the concurrency for this RowSet object. |
String |
getDataSourceName
Returns the logical name that when supplied to a naming service that uses the Java Naming and Directory Interface (JNDI) API, will retrieve a javax.sql.DataSource object. |
boolean |
getEscapeProcessing
Ascertains whether escape processing is enabled for this RowSet object. |
int |
getFetchDirection
Retrieves this RowSet object's current setting for the
fetch direction. |
int |
getFetchSize
Returns the fetch size for this RowSet object. |
int |
getMaxFieldSize
Retrieves the maximum number of bytes that can be used for a column value in this RowSet object. |
int |
getMaxRows
Retrieves the maximum number of rows that this RowSet object may contain. |
Object |
getParams
Retrieves an array containing the parameter values (both Objects and primitives) that have been set for this RowSet object's command and throws an SQLException object
if all parameters have not been set. |
String |
getPassword
Returns the password used to create a database connection for this RowSet object. |
int |
getQueryTimeout
Retrieves the maximum number of seconds the driver will wait for a query to execute. |
boolean |
getShowDeleted
Retrieves a boolean indicating whether rows marked
for deletion appear in the set of current rows. |
int |
getTransactionIsolation
Returns the transaction isolation property for this RowSet object's connection. |
int |
getType
Returns the type of this RowSet object. |
Map |
getTypeMap
Retrieves the type map associated with the Connection
object for this RowSet object. |
String |
getUrl
Retrieves the JDBC URL that this RowSet object's
javax.sql.Reader object uses to make a connection
with a relational database using a JDBC technology-enabled driver. |
String |
getUsername
Returns the user name used to create a database connection. |
protected void |
initParams
Performs the necessary internal configurations and initializations to allow any JDBC RowSet implementation to start using
the standard facilities provided by a BaseRowSet
instance. |
boolean |
isReadOnly
Returns a boolean indicating whether this
RowSet object is read-only. |
protected void |
notifyCursorMoved
Notifies all of the listeners registered with this RowSet object that its cursor has moved. |
protected void |
notifyRowChanged
Notifies all of the listeners registered with this RowSet object that
one of its rows has changed. |
protected void |
notifyRowSetChanged
Notifies all of the listeners registered with this RowSet
object that its entire contents have changed. |
void |
removeRowSetListener
Removes the designated object from this RowSet object's list of listeners. |
void |
setArray
Sets the designated parameter to an Array object in the
Java programming language. |
void |
setAsciiStream
Sets the designated parameter to the given java.io.InputStream object,
which will have the specified number of bytes. |
void |
setBigDecimal
Sets the designated parameter to the given java.lang.BigDecimal value. |
void |
setBinaryStream
Sets the designated parameter to the given java.io.InputStream
object, which will have the specified number of bytes. |
void |
setBlob
Sets the designated parameter to the given Blob object in
the Java programming language. |
void |
setBoolean
Sets the designated parameter to the given boolean in the
Java programming language. |
void |
setByte
Sets the designated parameter to the given byte in the Java
programming language. |
void |
setBytes
Sets the designated parameter to the given array of bytes. |
void |
setCharacterStream
Sets the designated parameter to the given java.io.Reader
object, which will have the specified number of characters. |
void |
setClob
Sets the designated parameter to the given Clob object in
the Java programming language. |
void |
setCommand
Sets this RowSet object's command property to
the given String object and clears the parameters, if any,
that were set for the previous command. |
void |
setConcurrency
Sets the concurrency for this RowSet object to
the specified concurrency. |
void |
setDataSourceName
Sets the DataSource name property for this RowSet
object to the given logical name and sets this RowSet object's
Url property to null. |
void |
setDate
Sets the designated parameter to the given java.sql.Date
value. |
void |
setDate
Sets the designated parameter to the given java.sql.Date
object. |
void |
setDouble
Sets the designated parameter to the given double in the
Java programming language. |
void |
setEscapeProcessing
Sets to the given boolean whether or not the driver will
scan for escape syntax and do escape substitution before sending SQL
statements to the database. |
void |
setFetchDirection
Gives the driver a performance hint as to the direction in which the rows in this RowSet object will be
processed. |
void |
setFetchSize
Sets the fetch size for this RowSet object to the given number of
rows. |
void |
setFloat
Sets the designated parameter to the given float in the
Java programming language. |
void |
setInt
Sets the designated parameter to an int in the Java
programming language. |
void |
setLong
Sets the designated parameter to the given long in the Java
programming language. |
void |
setMaxFieldSize
Sets the maximum number of bytes that can be used for a column value in this RowSet object to the given number. |
void |
setMaxRows
Sets the maximum number of rows that this RowSet object may contain to
the given number. |
void |
setNull
Sets the designated parameter to SQL NULL. |
void |
setNull
Sets the designated parameter to SQL NULL. |
void |
setObject
Sets the designated parameter to an Object in the Java
programming language. |
void |
setObject
Sets the value of the designated parameter with the given Object value. |
void |
setObject
Sets the designated parameter to an Object in the Java
programming language. |
void |
setPassword
Sets the password used to create a database connection for this RowSet object to the given String
object. |
void |
setQueryTimeout
Sets to the given number the maximum number of seconds the driver will wait for a query to execute. |
void |
setReadOnly
Sets this RowSet object's readOnly property to the given boolean. |
void |
setRef
Sets the designated parameter to the given Ref object in
the Java programming language. |
void |
setShort
Sets the designated parameter to the given short in the
Java programming language. |
void |
setShowDeleted
Sets the property showDeleted to the given
boolean value, which determines whether
rows marked for deletion appear in the set of current rows. |
void |
setString
Sets the designated parameter to the given String
value. |
void |
setTime
Sets the designated parameter to the given java.sql.Time
value. |
void |
setTime
Sets the designated parameter to the given java.sql.Time
object. |
void |
setTimestamp
Sets the designated parameter to the given java.sql.Timestamp value. |
void |
setTimestamp
Sets the designated parameter to the given java.sql.Timestamp object. |
void |
setTransactionIsolation
Sets the transaction isolation property for this JDBC RowSet object to the given
constant. |
void |
setType
Sets the type for this RowSet object to the specified type. |
void |
setTypeMap |