javax.sql.rowset

接口
异常
java.lang.Object
  继承者 javax.sql.rowset.BaseRowSet
所有已实现的接口:
Serializable, Cloneable

public abstract class BaseRowSet
     
extends Object
implements Serializable, Cloneable

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

1.0 概述

BaseRowSet 类为所有 RowSet 实现提供核心功能,所有标准实现 可以结合使用此类和一个或多个 RowSet 接口来提供标准特定于供应商的实现。更详细地说,即所有实现必须至少实现一个 RowSet 接口( JdbcRowSetCachedRowSetJoinRowSetFilteredRowSetWebRowSet)。这意味着所有扩展 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 InterfaceTM (JNDI) API 的命名服务注册。通常由具有系统管理员资格的人员完成此注册。

3.0 设置命令及其参数

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

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

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

在此示例中,CREDIT_LIMITREGION 的值是占位符参数,用一个问号 (?) 指示。第一个问号是占位符参数编号 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'"
 
注:将 ArrayClobBlobRef 对象设置为命令参数,将这些值分别存储为 SerialArraySerialClobSerialBlobSerialRef 对象。

4.0 在后台处理参数

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

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

大多数设置占位符参数的方法采用两个参数,第一个参数指示要设置的占位符参数,第二个参数给出要设置的值。getIntgetStringgetBooleangetLong 之类的方法属于此类。调用这些方法后,调用方法 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 返回的数组中的第二个元素将是一个两元素或三元素数组。

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

方法 setAsciiStreamsetBinaryStreamsetCharacterStreamsetUnicodeStream(该方法已废弃,所以应用程序应该使用 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 对象的命令没有限制。
  • 对于可以包含的行数没有限制。
  • 对于一列可以包含的字节数没有限制。注:此限制仅适用于包含以下类型值的列:BINARYVARBINARYLONGVARBINARYCHARVARCHARLONGVARCHAR
  • 无法看到未提交的数据(进行“脏”读)。
  • 已开启转义处理。
  • 已将其连接的类型映射设置为 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)
          将此 RowSet 对象命令中的指定参数设置为给定输入流。
 void setAsciiStream(int parameterIndex, InputStream x, int length)
          将指定参数设置为给定的 java.io.InputStream 对象,该对象将具有指定的字节数。
 void setAsciiStream(String parameterName, InputStream x)
          将指定参数设置为给定的输入流。
 void setAsciiStream(String parameterName, InputStream x, int length)
          将指定参数设置为给定输入流,该输入流将拥有指定字节数。
 void setBigDecimal(int parameterIndex, BigDecimal x)
          将指定参数设置为给定的 java.lang.BigDecimal 值。
 void setBigDecimal(String parameterName, BigDecimal x)
          将指定参数设置为给定的 java.math.BigDecimal 值。
 void setBinaryStream(int parameterIndex, InputStream x)
          将此 RowSet 对象命令中的指定参数设置为给定输入流。
 void setBinaryStream(int parameterIndex, InputStream x, int length)
          将指定参数设置为给定的 java.io.InputStream 对象,该对象具有指定的字节数。
 void setBinaryStream(String parameterName, InputStream x)
          将指定参数设置为给定输入流。
 void setBinaryStream(String parameterName, InputStream x, int length)
          将指定参数设置为给定的输入流,该输入流将拥有指定的字节数。
 void setBlob(int parameterIndex, Blob x)
          将指定参数设置为 Java 编程语言中的给定 Blob 对象。
 void setBlob(int parameterIndex, InputStream inputStream)
          将指定参数设置为 InputStream 对象。
 void setBlob(int parameterIndex, InputStream inputStream, long length)
          将指定参数设置为 InputStream 对象。
 void setBlob(String parameterName, Blob x)
          将指定参数设置为给定的 java.sql.Blob 对象。
 void setBlob(String parameterName, InputStream inputStream)
          将指定参数设置为 InputStream 对象。
 void setBlob(String parameterName, InputStream inputStream, long length)
          将指定参数设置为 InputStream 对象。
 void setBoolean(int parameterIndex, boolean x)
          将指定参数设置为 Java 编程语言中的给定 boolean 值。
 void setBoolean(String parameterName, boolean x)
          将指定参数设置为给定的 Java boolean 值。
 void setByte(int parameterIndex, byte x)
          将指定参数设置为 Java 编程语言中的给定 byte 值。
 void setByte(String parameterName, byte x)
          将指定参数设置为给定的 Java byte 值。
 void setBytes(int parameterIndex, byte[] x)
          将指定参数设置为给定的 byte 数组。
 void setBytes(String parameterName, byte[] x)
          将指定参数设置为给定的 Java byte 数组。
 void setCharacterStream(int parameterIndex, Reader reader)
          将此 RowSet 对象命令中的指定参数设置为给定的 Reader 对象。
 void setCharacterStream(int parameterIndex, Reader reader, int length)
          将指定参数设置为给定的 java.io.Reader 对象,该对象具有指定的字符数。
 void setCharacterStream(String parameterName, Reader reader)
          将指定参数设置为给定 Reader 对象。
 void setCharacterStream(String parameterName, Reader reader, int length)
          将指定参数设置为给定的 Reader 对象,该对象是给定的字符长度数目。
 void setClob(int parameterIndex, Clob x)
          将指定参数设置为 Java 编程语言中的给定 Clob 对象。
 void setClob(int parameterIndex, Reader reader)
          将指定参数设置为 Reader 对象。
 void setClob(int parameterIndex, Reader reader, long length)
          将指定参数设置为 Reader 对象。
 void setClob(String parameterName, Clob x)
          将指定参数设置为给定的 java.sql.Clob 对象。
 void setClob(String parameterName, Reader reader)
          将指定参数设置为 Reader 对象。
 void setClob(String parameterName, Reader reader, long length)
          将指定参数设置为 Reader 对象。
 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 setDate(String parameterName, Date x)
          使用运行应用程序的虚拟机所在的默认时区将指定参数设置为给定的 java.sql.Date 值。
 void setDate(String parameterName, Date x, Calendar cal)
          使用给定 Calendar 对象将指定参数设置为给定的 java.sql.Date 值。
 void setDouble(int parameterIndex, double x)
          将指定参数设置为 Java 编程语言中的给定 double 值。
 void setDouble(String parameterName, 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 setFloat(String parameterName, float x)
          将指定参数设置为给定的 Java float 值。
 void setInt(int parameterIndex, int x)
          将指定参数设置为 Java 编程语言中的 int 值。
 void setInt(String parameterName, int x)
          将指定参数设置为给定的 Java int 值。
 void setLong(int parameterIndex, long x)
          将指定参数设置为 Java 编程语言中的给定 long 值。
 void setLong(String parameterName, long x)
          将指定参数设置为给定的 Java long 值。
 void setMaxFieldSize(int max)
          将可用于此 RowSet 对象列值的最大字节数设置为给定数。
 void setMaxRows(int max)
          将此 RowSet 对象可以包含的最大行数设置为给定数。
 void setNCharacterStream(int parameterIndex, Reader value)
          将此 RowSet 对象命令中的指定参数设置为 Reader 对象。
 void setNCharacterStream(int parameterIndex, Reader value, long length)
          将指定参数设置为 Reader 对象。
 void setNCharacterStream(String parameterName, Reader value)
          将指定参数设置为 Reader 对象。
 void setNCharacterStream(String parameterName, Reader value, long length)
          将指定参数设置为 Reader 对象。
 void setNClob(int parameterIndex, NClob value)
          将指定参数设置为 java.sql.NClob 对象。
 void setNClob(int parameterIndex, Reader reader)
          将指定参数设置为 Reader 对象。
 void setNClob(int parameterIndex,

JDK 1.6 中文手册