Java javax.sql.rowset 类 BaseRowSet（JDK5）

所有类

概述  软件包   类  使用  树  已过时  索引  帮助
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

javax.sql.rowset
类 BaseRowSet

java.lang.Object
  javax.sql.rowset.BaseRowSet

所有已实现的接口：

Serializable, Cloneable

---

public abstract class BaseRowSet
   
   
   
   
   
extends Object
   
   
   
   
   
   
   
   
   
   
implements Serializable, Cloneable
   
   
   
   
   

提供一个具有基本功能的 RowSet 对象的抽象类。基本功能包括设置属性和发送事件通知，这是所有 JavaBeans^TM 组件都必须实现的。

1.0 概述

BaseRowSet 类为所有 RowSet 实现提供核心功能，所有标准实现可以结合使用此类和一个或多个 RowSet 接口来提供标准特定于供应商的实现。更详细地说，即所有实现必须至少实现一个 RowSet 接口（JdbcRowSet、CachedRowSet、JoinRowSet、FilteredRowSet 或 WebRowSet）。这意味着所有扩展 BaseRowSet 类的实现也必须实现一个 RowSet 接口。

BaseRowSet 类提供以下内容：

• 属性
  • 用于存储当前属性的字段
  • 用于获取和设置属性的方法

• 事件通知

• 完整的设置方法集 用于设置 RowSet 对象命令中的各个参数

• 流
  • 用于存储流实例的字段
  • 指示流类型的常量

2.0 设置属性

所有 rowset 都维护一个属性集，通常使用某种工具来设置这些属性。rowset 具有的属性的数量和种类各不相同，这取决于 RowSet 实现的用途及其获得数据的方式。例如，从 ResultSet 对象获得其数据的 rowset 需要设置那些建立数据库连接所需的属性。如果某个 RowSet 对象使用 DriverManager 设施建立连接，则它需要设置一个标识合适驱动程序的 JDBC URL 属性，还需要设置那些提供用户名和密码的属性。另一方面，如果 rowset 使用 DataSource 对象建立连接（这是首选的方法），则它无需设置 JDBC URL 属性。但是它需要设置用于数据源逻辑名的属性，以及用户名和密码的属性。

注：要使用 DataSource 对象建立连接，该 DataSource 对象必须已经向使用 Java Naming and Directory Interface^TM (JNDI) API 的命名服务注册。通常由具有系统管理员资格的人员完成此注册。

3.0 设置命令及其参数

rowset 从关系型数据库获取其数据时，它执行一条可生成 ResultSet 对象的命令（查询）。此查询就是为 RowSet 对象的 command 属性所设置的命令。rowset 使用数据填充自身的方式是将数据从 ResultSet 对象读取到其自身。如果查询为要设置的值包含占位符，则使用 BaseRowSet 的设置方法设置这些值。如有必要，所有设置方法都允许将这些值设置为 null。

以下代码片断展示了如何设置 CachedRowSet^TM 对象 crs 的 command 属性。注意，如果使用某种工具设置属性，则这就是该工具应使用的代码。

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

在此示例中，CREDIT_LIMIT 和 REGION 的值是占位符参数，用一个问号 (?) 指示。第一个问号是占位符参数编号 1，第二个问号是占位符参数编号 2，依此类推。执行查询前必须为占位符参数设置值。要设置这些占位符参数，BaseRowSet 类提供了一组与 PreparedStatement 接口类似的设置方法，用于设置每种数据类型的值。RowSet 对象内部存储该参数值，该对象的 execute 方法在将要执行的命令发送到 DBMS 前，使用这些值内部设置占位符参数的值。

以下代码片断演示了如何设置前一个示例查询中的两个参数。

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

如果此时调用 execute 方法，则发送到 DBMS 的查询是：

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

注：将 Array、Clob、Blob 和 Ref 对象设置为命令参数，将这些值分别存储为 SerialArray、SerialClob、SerialBlob 和 SerialRef 对象。

4.0 在后台处理参数

注：BaseRowSet 类提供两类设置方法：一类设置属性，一类设置占位符参数。此部分中讨论的设置方法是设置占位符参数的那一类。

使用 BaseRowSet 的设置方法设置的占位符参数以对象的形式存储在内部 Hashtable 对象中。基本类型则以其 Object 类型存储。例如，byte 以 Byte 对象的形式存储，int 则以 Integer 对象的形式存储。调用方法 execute 时，Hashtable 对象中的值替换命令中的适当占位符参数。 调用方法 getParams 能够以 Object 实例数组的形式返回存储在 Hashtable 对象中的值。此数组中的元素可以是一个简单的 Object 实例，也可以是一个数组（ Object 类型）。使用特定的设置方法可确定此数组中某个元素是 Object 还是数组。

大多数设置占位符参数的方法采用两个参数，第一个参数指示要设置的占位符参数，第二个参数给出要设置的值。getInt、getString、getBoolean 和 getLong 之类的方法属于此类。调用这些方法后，调用方法 getParams 将返回一个数组，其中带有已经设置的值。每个数组元素都是一个 Object 实例，表示已经设置的值。根据传递到设置方法的 int（第一个参数）来确定这些值在数组中的顺序。该数组中的值就是传递给设置方法的值（第二个参数）。换句话说，数组中的第一个元素是为 RowSet 对象的命令中第一个占位符参数所设置的值。第二个元素是为第二个占位符参数所设置的值，依此类推。

一些设置方法除了要设置的值外，还发送驱动程序和 DBMS 信息。如果在使用了此类设置方法后再调用方法 getParams，则数组中的元素本身就是数组，以容纳附加信息。在此类别中，方法 setNull 是一个特例，因为它有一种形式只带有两个参数 (setNull(int parameterIndex, int SqlType))。尽管如此，它仍然需要一个数组来包含要传递给驱动程序和 DBMS 的信息。此数组中的第一个元素是要设置的值，该值为 null；第二个元素是为 sqlType 提供的 int，指示要设置为 null 的 SQL 值的类型。某些 DBMS 需要此信息，因此为了确保应用程序的可移植性，此信息是必需的。当要设置为 null 的值是用户定义的类型时，可使用该方法的另一种形式。这种形式带有三个参数 (setNull(int parameterIndex, int sqlType, String typeName))，同样需要一个数组来包含要传递给驱动程序和 DBMS 的信息。此数组中的前两个参数与第一种 setNull 相同。第三个参数 typeName 给出了用户定义类型的 SQL 名称。与其他设置方法一样，通过 getParams 返回的数组中元素的位置来指示要设置的占位符参数的编号。所以，举例来说，如果提供给 setNull 的参数是 2，则 getParams 返回的数组中的第二个元素将是一个两元素或三元素数组。

某些方法（如 setObject 和 setDate）还有带有多于两个参数的形式，这些额外的参数为驱动程序或 DBMS 提供信息。例如，方法 setDate、setTime 和 setTimestamp 可将 Calendar 对象作为其第三个参数。如果 DBMS 没有存储时区信息，则驱动程序使用 Calendar 对象来构造正在设置的 Date、Time 或 Timestamp 对象。与提供附加信息的其他方法一样，getParams 返回的数组中的元素是一个数组，而不是简单的 Object 实例。

方法 setAsciiStream、setBinaryStream、setCharacterStream 和 setUnicodeStream（该方法已废弃，所以应用程序应该使用 getCharacterStream）带有三个参数，所以对于这些方法，getParams 返回的数组中的元素也是一个数组。这些设置方法的不同之处在于除了由参数提供的信息外，该数组还包含一个 BaseRowSet 常量，指示正在设置的流类型。

注：由扩展此类的 RowSet 实现内部调用方法 getParams；应用程序的程序员通常不直接调用此方法。

5.0 事件通知

BaseRowSet 类为 rowset 提供了事件通知机制。它包含字段 listeners、添加和移除侦听器的方法，以及将更改通知给侦听器的方法。

侦听器是一个实现了 RowSetListener 接口的对象。如果已经将侦听器添加到 RowSet 对象的侦听器列表，则 RowSet 对象上发生事件时它将获得通知。每个侦听器的 RowSetListener 方法实现定义了获得发生事件的通知时，该对象将执行的操作。

RowSet 对象有三种可能的事件：

1. 光标移动
2. 更改了个别行（更新、删除或插入）
3. 更改了整个 RowSet 对象的内容

用于通知的 BaseRowSet 方法指示已经发生事件的类型。例如，方法 notifyRowChanged 指示某行已经被更新、删除或插入。每种通知方法都创建 RowSetEvent 对象，将该对象提供给侦听器，从而标识发生事件的 RowSet 对象。侦听器如何使用此信息（可能不执行任何操作）取决于它的实现方式。

6.0 默认行为

默认的 BaseRowSet 对象是用很多起始值初始化的。 扩展 BaseRowSet 类的默认 RowSet 实例具有以下特点：

• 具有可滚动的指针并且不显示其他对象所做的更改。
• 是可更新的。
• 不显示已删除的行。
• 对于驱动程序要多长时间才执行 RowSet 对象的命令没有限制。
• 对于可以包含的行数没有限制。
• 对于一列可以包含的字节数没有限制。注：此限制仅适用于包含以下类型值的列：BINARY、VARBINARY、LONGVARBINARY、CHAR、VARCHAR 和 LONGVARCHAR。
• 无法看到未提交的数据（进行“脏”读）。
• 已开启转义处理。
• 已将其连接的类型映射设置为 null。
• 具有空的 Vector 对象，用于存储为 RowSet 对象命令中的占位符参数设置的值。

如果需要其他值，则应用程序必须显式设置该属性值。例如，以下代码行将 CachedRowSet 对象 crs 的最大行数设置为 500。

    crs.setMaxRows(500);
 

对于任何违反已定义断言的情况，扩展此 BaseRowSet 类的方法实现必须抛出 SQLException 对象。此外，如果扩展的类重写和重新实现了任何 BaseRowSet 方法，并且遇到了连接性或底层数据源问题，则方法可以为此另外抛出 SQLException 对象。

另请参见：

序列化表格

---

字段摘要
static int	ASCII_STREAM_PARAM           该常量向 RowSetReaderImpl 对象指示给定的参数是一个 ASCII 流。
protected  InputStream	asciiStream           将由方法 getAsciiStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。
static int	BINARY_STREAM_PARAM           该常量向 RowSetReaderImpl 对象指示给定的参数是一个二进制流。
protected  InputStream	binaryStream           将由方法 getBinaryStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。
protected  Reader	charStream           将由方法 getCharacterStream 返回的 Reader 对象，该方法在 ResultSet 接口中指定。
static int	UNICODE_STREAM_PARAM           该常量向 RowSetReaderImpl 对象指示给定的参数是一个 Unicode 流。
protected  InputStream	unicodeStream           将由方法 getUnicodeStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。

 

构造方法摘要
BaseRowSet()           构造一个新的 BaseRowSet 对象，使用默认的 Vector 对象初始化其 listeners 字段。

 

方法摘要
void	addRowSetListener(RowSetListener listener)           只要在此 RowSet 对象上发生事件，就将通知该侦听器。
void	clearParameters()           清除所有此 RowSet 对象的内部参数表示形式的当前参数值，这些参数值将在执行此 RowSet 对象的命令时在其中设置这些参数。
String	getCommand()           检索作为此 RowSet 对象的命令的 SQL 查询。
int	getConcurrency()           返回此 RowSet 对象的并发性。
String	getDataSourceName()           返回向使用 Java Naming and Directory Interface (JNDI) API 的命名服务所提供的逻辑名，这将检索 javax.sql.DataSource 对象。
boolean	getEscapeProcessing()           确定是否为此 RowSet 对象启用了转义处理。
int	getFetchDirection()           检索此 RowSet 对象的当前有关获取方向的设置。
int	getFetchSize()           返回此 RowSet 对象的获取大小。
int	getMaxFieldSize()           检索可用于此 RowSet 对象列值的最大字节数。
int	getMaxRows()           检索此 RowSet 对象可以包含的最大行数。
Object[]	getParams()           检索一个数组，其中包含为此 RowSet 对象命令设置的参数值（包括 Object 和基本类型），如果尚未设置任何参数，则抛出 SQLException 对象。
String	getPassword()           返回用于创建此 RowSet 对象的数据库连接的密码。
int	getQueryTimeout()           检索驱动程序等待查询执行的最大秒数。
boolean	getShowDeleted()           检索一个 boolean 值，该值指示标记为删除的行是否会出现在当前行集合中。
int	getTransactionIsolation()           返回此 RowSet 对象连接的事务隔离属性。
int	getType()           返回此 RowSet 对象的类型。
Map<String,Class<?>>	getTypeMap()           检索与此 RowSet 对象的 Connection 对象关联的类型映射表。
String	getUrl()           检索此 RowSet 对象的 javax.sql.Reader 对象用来建立与关系数据库连接（使用启用 JDBC 技术的驱动程序）的 JDBC URL。
String	getUsername()           返回用于创建数据库连接的用户名。
protected  void	initParams()           执行必需的内部配置和初始化，从而允许所有 JDBC RowSet 实现开始使用 BaseRowSet 实例提供的标准设施。
boolean	isReadOnly()           返回一个指示此 RowSet 对象是否为只读的 boolean 值。
protected  void	notifyCursorMoved()           通知向此 RowSet 对象注册的所有侦听器其光标已移动。
protected  void	notifyRowChanged()           通知向此 RowSet 对象注册的所有侦听器其行已更改。
protected  void	notifyRowSetChanged()           通知向此 RowSet 对象注册的所有侦听器其整个内容已更改。
void	removeRowSetListener(RowSetListener listener)           从此 RowSet 对象的侦听器列表中移除指定的对象。
void	setArray(int parameterIndex, Array array)           将指定参数设置为 Java 编程语言中的 Array 对象。
void	setAsciiStream(int parameterIndex, InputStream x, int length)           将指定参数设置为给定的 java.io.InputStream 对象，该对象将具有指定的字节数。
void	setBigDecimal(int parameterIndex, BigDecimal x)           将指定参数设置为给定的 java.lang.BigDecimal 值。
void	setBinaryStream(int parameterIndex, InputStream x, int length)           将指定参数设置为给定的 java.io.InputStream 对象，该对象具有指定的字节数。
void	setBlob(int parameterIndex, Blob x)           将指定参数设置为 Java 编程语言中的给定 Blob 对象。
void	setBoolean(int parameterIndex, boolean x)           将指定参数设置为 Java 编程语言中的给定 boolean 值。
void	setByte(int parameterIndex, byte x)           将指定参数设置为 Java 编程语言中的给定 byte 值。
void	setBytes(int parameterIndex, byte[] x)           将指定参数设置为给定的 byte 数组。
void	setCharacterStream(int parameterIndex, Reader reader, int length)           将指定参数设置为给定的 java.io.Reader 对象，该对象具有指定的字符数。
void	setClob(int parameterIndex, Clob x)           将指定参数设置为 Java 编程语言中的给定 Clob 对象。
void	setCommand(String cmd)           将此 RowSet 对象的 command 属性设置为给定的 String 对象，并清除为前一个命令设置的参数（如果有）。
void	setConcurrency(int concurrency)           将此 RowSet 对象的并发性设置为指定的并发性。
void	setDataSourceName(String name)           将此 RowSet 对象的 DataSource 名称属性设置为给定的逻辑名，并将此 RowSet 对象的 Url 属性设置为 null。
void	setDate(int parameterIndex, Date x)           将指定参数设置为给定的 java.sql.Date 值。
void	setDate(int parameterIndex, Date x, Calendar cal)           将指定参数设置为给定的 java.sql.Date 对象。
void	setDouble(int parameterIndex, double x)           将指定参数设置为 Java 编程语言中的给定 double 值。
void	setEscapeProcessing(boolean enable)           设置为给定的 boolean 值，指示将 SQL 语句发送到数据库之前，驱动程序是否扫描转义语法并进行转义替换。
void	setFetchDirection(int direction)           为驱动程序提供一个性能提示，该提示指示处理此 RowSet 对象中各行时使用的方向。
void	setFetchSize(int rows)           将此 RowSet 对象的获取大小设置为给定的行数。
void	setFloat(int parameterIndex, float x)           将指定参数设置为 Java 编程语言中的给定 float 值。
void	setInt(int parameterIndex, int x)           将指定参数设置为 Java 编程语言中的 int 值。
void	setLong(int parameterIndex, long x)           将指定参数设置为 Java 编程语言中的给定 long 值。
void	setMaxFieldSize(int max)           将可用于此 RowSet 对象列值的最大字节数设置为给定数。
void	setMaxRows(int max)           将此 RowSet 对象可以包含的最大行数设置为给定数。
void	setNull(int parameterIndex, int sqlType)           将指定参数设置为 SQL NULL。
void	setNull(int parameterIndex, int sqlType, String typeName)           将指定参数设置为 SQL NULL。
void	setObject(int parameterIndex, Object x)           将指定参数设置为 Java 编程语言中的 Object。
void	setObject(int parameterIndex, Object x, int targetSqlType)           使用给定 Object 值设置指定参数的值。
void	setObject(int parameterIndex, Object x, int targetSqlType, int scale)           将指定参数设置为 Java 编程语言中的 Object。
void	setPassword(String pass)           将用于创建此 RowSet 对象的数据库连接的密码设置为给定的 String 对象。
void	setQueryTimeout(int seconds)           将驱动程序等待查询执行的最大秒数设置为给定的数。
void	setReadOnly(boolean value)           将此 RowSet 对象的 readOnly 属性设置为给定的 boolean 值。
void	setRef(int parameterIndex, Ref ref)           将指定参数设置为 Java 编程语言中的给定 Ref 对象。
void	setShort(int parameterIndex, short x)           将指定参数设置为 Java 编程语言中的给定 short 值。
void	setShowDeleted(boolean value)           将属性 showDeleted 设置为给定的 boolean 值，该值指示标记为删除的行是否会出现在当前行集合中。
void	setString(int parameterIndex, String x)           将指定参数设置为给定的 String 值。
void	setTime(int parameterIndex, Time x)           将指定参数设置为给定的 java.sql.Time 值。
void	setTime(int parameterIndex, Time x, Calendar cal)           将指定参数设置为给定的 java.sql.Time 对象。
void	setTimestamp(int parameterIndex, Timestamp x)           将指定参数设置为给定的 java.sql.Timestamp 值。
void	setTimestamp(int parameterIndex, Timestamp x, Calendar cal)           将指定参数设置为给定的 java.sql.Timestamp 对象。
void	setTransactionIsolation(int level)           将此 JDBC RowSet 对象的事务隔离属性设置为给定的常量。
void	setType(int type)           将此 RowSet 对象的类型设置为指定类型。
void	setTypeMap(Map<String,Class<?>> map)           将给定的 java.util.Map 对象安装为与此 RowSet 对象的 Connection 对象关联的类型映射表。
void	setUnicodeStream(int parameterIndex, InputStream x, int length)           已过时。 应该使用 getCharacterStream 替代它
void	setUrl(String url)           将此 RowSet 对象的 Url 属性设置为给定的 String 对象，并将 dataSource 名称属性设置为 null。
void	setUsername(String name)           将此 RowSet 对象的 username 属性设置为给定的用户名。

 

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

字段详细信息

UNICODE_STREAM_PARAM

public static final int UNICODE_STREAM_PARAM

该常量向 RowSetReaderImpl 对象指示给定的参数是一个 Unicode 流。此 RowSetReaderImpl 对象作为 SyncProvider 抽象类的扩展来提供，该抽象类在 SyncFactory 静态工厂 SPI 机制中定义。

另请参见：

常量字段值

---

BINARY_STREAM_PARAM

public static final int BINARY_STREAM_PARAM

该常量向 RowSetReaderImpl 对象指示给定的参数是一个二进制流。此 RowSetReaderImpl 对象作为 SyncProvider 抽象类的扩展来提供，该抽象类在 SyncFactory 静态工厂 SPI 机制中定义。

另请参见：

常量字段值

---

ASCII_STREAM_PARAM

public static final int ASCII_STREAM_PARAM

该常量向 RowSetReaderImpl 对象指示给定的参数是一个 ASCII 流。此 RowSetReaderImpl 对象作为 SyncProvider 抽象类的扩展来提供，该抽象类在 SyncFactory 静态工厂 SPI 机制中定义。

另请参见：

常量字段值

---

binaryStream

protected InputStream binaryStream

将由方法 getBinaryStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。

---

unicodeStream

protected InputStream unicodeStream

将由方法 getUnicodeStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。

---

asciiStream

protected InputStream asciiStream

将由方法 getAsciiStream 返回的 InputStream 对象，该方法在 ResultSet 接口中指定。

---

charStream

protected Reader charStream

将由方法 getCharacterStream 返回的 Reader 对象，该方法在 ResultSet 接口中指定。

构造方法详细信息

BaseRowSet

public BaseRowSet()

构造一个新的 BaseRowSet 对象，使用默认的 Vector 对象初始化其 listeners 字段。初始化时使用的其他默认值列在此类类注释的 6.0 部分。

方法详细信息

initParams

protected void initParams()

执行必需的内部配置和初始化，从而允许所有 JDBC RowSet 实现开始使用 BaseRowSet 实例提供的标准设施。应该在实例化 RowSet 对象后再调用此方法，以正确地初始化所有参数。此方法永远不应该由应用程序调用，而应从具有扩展此类的 RowSet 实现的对象中调用。