软件包 javax.sql.rowset.serial

提供实用工具类，允许 SQL 类型与 Java 编程语言数据类型之间的可序列化映射关系。

请参见：
          描述

类摘要
SerialArray	序列化的 Array 对象，它是 SQL ARRAY 值在 Java 编程语言中的映射关系。
SerialBlob	SQL BLOB 值在 Java 编程语言中的序列化映射关系。
SerialClob	SQL CLOB 值在 Java 编程语言中的序列化映射关系。
SerialDatalink	SQL DATALINK 值在 Java 编程语言中的序列化映射关系。
SerialJavaObject	SQL JAVA_OBJECT 值在 Java 编程语言中的可序列化映射关系。
SerialRef	Ref 对象的序列化映射关系，它是 SQL REF 值在 Java 编码语言中的映射关系。
SerialStruct	SQL 结构类型在 Java 编程语言中的序列化映射关系。
SQLInputImpl	用于自定义映射用户定义类型 (UDT) 的输入流。
SQLOutputImpl	用于将自定义映射的用户定义类型 (UDT) 的属性写回数据库的输出流。

 

异常摘要
SerialException	指示对 SQL 类型 BLOB、CLOB、STRUCT 或 ARRAY 以及 SQL 类型 DATALINK 和 JAVAOBJECT 进行序列化或反序列化时发生的错误。

 

软件包 javax.sql.rowset.serial 的描述

提供实用工具类，允许 SQL 类型与 Java 编程语言数据类型之间的可序列化映射关系。

标准的 JDBC RowSet 实现可以使用这些实用工具类协助序列化非连接 RowSet 对象。这一点有助于将非连接 RowSet 对象通过导线传输到另一个 VM 或者在应用程序中跨层传输。

1.0 SerialArray

SQL ARRAY 值在 Java 编程语言中的可序列化映射关系。

SerialArray 类提供一个根据 Array 对象创建 SerialArray 实例的构造方法，提供获取基本类型及其 SQL 名称的各种方法，以及复制全部或部分 SerialArray 对象的各种方法。

2.0 SerialBlob

SQL BLOB 值在 Java 编程语言中的可序列化映射关系。

SerialBlob 类提供一个根据 Blob 对象创建实例的构造方法。注意，在根据 Blob 对象构造 SerialBlob 对象之前，Blob 对象应该已经将 SQL BLOB 值的数据置于客户端上。SQL BLOB 值的数据可以在客户端上以字节数组（使用 Blob.getBytes 方法）或未解释字节流的形式（使用 Blob.getBinaryStream 方法）实现。

SerialBlob 方法能够以字节数组或流的形式复制 SerialBlob 对象。这些方法还可以在 SerialBlob 对象中查找给定模式的字节或 Blob 对象。

3.0 SerialClob

SQL CLOB 值在 Java 编程语言中的可序列化映射关系。

SerialClob 类提供一个根据 Clob 对象创建实例的构造方法。注意，在根据 Clob 对象构造 SerialClob 对象之前， Clob 对象应该已经将 SQL CLOB 值的数据置于客户端上。SQL CLOB 值的数据可以在客户端上以 Unicode 字符流的形式实现。

SerialClob 方法可以从 SerialClob 对象获取子字符串或者查找某种模式的字符的开头。

5.0 SerialDatalink

SQL DATALINK 值在 Java 编程语言中的可序列化映射关系。DATALINK 值引用原始数据源管理的底层数据源之外的文件。

RowSet 实现可以使用 RowSet.getURL() 方法来获取 java.net.URL 对象，该对象可用于操作外部数据。

       java.net.URL url = rowset.getURL(1);

6.0 SerialJavaObject

SQL JAVA_OBJECT 值在 Java 编程语言中的可序列化映射关系。假定 Java 对象实例实现 Serializable 接口，则此类仅包装序列化进程。

但是如果序列化不能进行（即 Java 对象不是立即可序列化的），则此类将尝试序列化所有非静态成员，以允许序列化对象实例状态。静态或瞬态字段不可序列化，尝试执行此操作将导致抛出 SerialException。

7.0 SerialRef

SQL REF 类型与 Java 编程语言之间的可序列化映射关系。

SerialRef 类提供一个根据 Ref 类型创建 SerialRef 实例的构造方法，并且提供用于获取和设置 Ref 对象类型的各种方法。

8.0 SerialStruct

SQL 结构类型在 Java 编程语言中的可序列化映射关系。每个不可序列化的属性将被映射为可序列化形式；如果属性本身是结构类型，则其每个不可序列化的属性将被映射为可序列化形式。

此外，如果将 Map 对象传递给其中一个构造方法或 getAttributes 方法，则根据在 Map 对象中指定的映射关系对结构类型进行自定义映射。
SerialStruct 类提供一个根据 Struct 对象创建实例的构造方法，提供一个用于在数据库中获取 SQL 结构类型的 SQL 类型名称的方法，以及用于获取其属性值的各种方法。

9.0 SQLInputImpl

用于自定义映射用户定义类型 (UDT) 的输入流。 SQLInputImpl 对象是一个包含值流的输入流，这些值是 UDT 的属性。在对具有自定义映射关系的 SQL 结构类型或 distinct 类型调用 getObject 方法时，驱动程序在后台使用此类；程序员决不能直接调用 SQLInputImpl 方法。

SQLInputImpl 类提供一组类似于 ResultSet 获取方法的读取方法。这些方法可以在 SQLInputImpl 对象中读取值。方法 wasNull 用于确定读取的最后一个值是否是 SQL NULL。

在调用带有 Map 对象的构造方法或获取方法时，JDBC 驱动程序调用 SQLData.getSQLType 方法来确定将自定义映射的 UDT SQL 类型。驱动程序创建一个 SQLInputImpl 实例，并用 UDT 的属性填充它。然后，驱动程序将输入流传递给 SQLData.readSQL 方法，该方法依次调用 SQLInputImpl 方法从输入流读取属性。

10.0 SQLOutputImpl

用于将自定义映射的用户定义类型 (UDT) 的属性写回数据库的输出流。驱动程序在内部使用此接口，应用程序员决不能直接调用其方法。

当应用程序调用 PreparedStatement.setObject 方法时，驱动程序将检查要写入的值是否是具有自定义映射关系的 UDT。如果是，则在类型映射中将存在一个条目，该条目包含 Class 对象，用于为此 UDT 实现 SQLData 的类。如果要写入的值是 SQLData 的实例，则驱动程序将创建 SQLOutputImpl 的实例并将其传递给 SQLData.writeSQL 方法。 writeSQL 方法依次调用适当的 SQLOutputImpl 写入方法，从 SQLData 对象以 SQL 用户定义类型的表示形式将数据写入 SQLOutputImpl 输出流。

自定义映射关系

JDBC API 提供用于将 SQL 结构类型或 DISTINCT 类型映射为 Java 编程语言的机制。通常，结构类型被映射为类，其属性被映射为类中的字段。（DISTINCT 类型可视为具有一个属性。）但是，也存在其他可能性和多种不同的映射关系。

程序员通过实现 SQLData 接口定义映射关系。例如，如果名为 AUTHORS 的 SQL 结构类型具有属性 NAME、TITLE 和 PUBLISHER，则其可以被映射为名为 Authors 的 Java 类。Authors 类可以具有字段 name、title 和 publisher，AUTHORS 的属性将被映射到这些字段。在这种情况下，SQLData 的实现可能如下所示：

   public class Authors implements SQLData {
       public String name;
       public String title;
       public String publisher;

       private String sql_type;
       public String getSQLTypeName() {
           return sql_type;
       }

       public void readSQL(SQLInput stream, String type)
                                  throws SQLException  {
           sql_type = type;
           name = stream.readString();
title = stream.readString();
           publisher = stream.readString();
       }

       public void writeSQL(SQLOutput stream) throws SQLException {
           stream.writeString(name);
           stream.writeString(title);
           stream.writeString(publisher);
       }
   } 

java.util.Map 对象用于将 SQL 结构类型与其到 Authors 类的映射关系相关联。以下代码片段展示了一种创建 Map 对象并为其提供一个关联 AUTHORS 和 Authors 的条目的方式。

    java.util.Map map = new java.util.HashMap();
    map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");

Map 对象 map 现在包含一个具有 SQL 结构类型的完全限定名的条目和 Authors 类的 Class 对象。可以将其传递给某个方法，以告知驱动程序将 AUTHORS 映射到 Authors 的方式。

对于未连接 RowSet 对象，仅在将 Map 对象传递给将执行自定义映射的方法或构造方法时，才可以完成自定义映射。对于连接 RowSet 对象，情况则不同，因为它们维持着与数据源的连接。执行自定义映射并由未连接 RowSet 对象调用的方法可能使用与正在使用的 Connection 对象关联的 Map 对象。因此，换句话说，如果没有指定任何映射，则默认情况下可以使用连接的类型映射。