Module java.sql.rowset

Package javax.sql.rowset.serial

package javax.sql.rowset.serial

提供了实用类，允许在Java编程语言中的SQL类型和数据类型之间进行可序列化映射。

标准的JDBC RowSet 实现可以使用这些实用类来帮助序列化断开连接的 RowSet 对象。当将断开连接的 RowSet 对象通过网络传输到不同的VM或应用程序的不同层时，这将非常有用。

1.0 SerialArray

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

SerialArray 类提供了一个构造函数，用于从Array对象创建一个 SerialArray 实例，以及用于获取基本类型和基本类型的SQL名称的方法，以及用于复制全部或部分 SerialArray 对象的方法。

2.0 SerialBlob

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

SerialBlob 类提供了一个从Blob对象创建实例的构造函数。请注意，在从Blob对象构造 SerialBlob 对象之前，Blob对象应该已经将SQL BLOB值的数据传输到客户端。SQL BLOB值的数据可以在客户端作为字节数组（使用方法 Blob.getBytes）或作为未解释字节流（使用方法 Blob.getBinaryStream）材料化。

SerialBlob 方法使得可以将 SerialBlob 对象作为字节数组或流进行复制。它们还使得可以在 SerialBlob 对象中定位给定的字节模式或 Blob 对象。

3.0 SerialClob

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

SerialClob 类提供了一个从 Clob 对象创建实例的构造函数。请注意，在从 Clob 对象构造 SerialClob 对象之前，Clob 对象应该已经将SQL CLOB值的数据传输到客户端。SQL CLOB值的数据可以在客户端作为Unicode字符流材料化。

SerialClob 方法使得可以从 SerialClob 对象获取子字符串或定位字符模式的起始位置。

5.0 SerialDatalink

在Java编程语言中对SQL DATALINK值的可序列化映射。DATALINK值引用了底层数据源之外的文件，该文件由起始数据源管理。

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

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

6.0 SerialJavaObject

在Java编程语言中对SQL JAVA_OBJECT值的可序列化映射。假设Java对象实例实现了Serializable接口，这只是简单地包装了序列化过程。

但是，如果在Java对象不是立即可序列化的情况下，序列化是不可能的，此类将尝试序列化所有非静态成员以允许序列化对象实例状态。静态或瞬态字段无法序列化，尝试这样做将导致抛出 SerialException。

7.0 SerialRef

在SQL REF类型和Java编程语言之间的可序列化映射。

SerialRef 类提供了一个从 Ref 类型创建 SerialRef 实例的构造函数，并提供了获取和设置 Ref 对象类型的方法。

8.0 SerialStruct

在Java编程语言中对SQL结构化类型的可序列化映射。每个尚未可序列化的属性都映射到可序列化形式，如果属性本身是结构化类型，则将其每个尚未可序列化的属性映射到可序列化形式。

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

9.0 SQLInputImpl

用于自定义映射用户定义类型（UDTs）的输入流。一个 SQLInputImpl 对象是一个输入流，其中包含作为UDT属性的值流。当在具有自定义映射的SQL结构化或DISTINCT类型上调用方法 getObject 时，驱动程序在幕后使用此类；程序员永远不会直接调用 SQLInputImpl 方法。

SQLInputImpl 类提供了一组类似于 ResultSet getter 方法的读取器方法。这些方法使得可以读取 SQLInputImpl 对象中的值。方法 wasNull 用于确定上次读取的值是否为SQL NULL。

当调用一个接受 Map 对象的构造函数或getter方法时，JDBC驱动程序会调用方法 SQLData.getSQLType 来确定正在自定义映射的UDT的SQL类型。驱动程序创建一个 SQLInputImpl 实例，并用UDT的属性填充它。然后，驱动程序将输入流传递给方法 SQLData.readSQL，后者又调用 SQLInputImpl 方法从输入流中读取属性。

10.0 SQLOutputImpl

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

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

自定义映射

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 对象。因此，换句话说，如果未指定映射，则默认情况下可以使用连接的类型映射。

Related Packages

Package	Description
javax.sql.rowset	JDBC RowSet 实现的标准接口和基类。
javax.sql.rowset.spi	第三方供应商在实现同步提供程序时必须使用的标准类和接口。

Class	Description
SerialArray	Array 对象的序列化版本，它是Java编程语言中SQL ARRAY 值的映射。
SerialBlob	Java编程语言中SQL BLOB 值的序列化映射。
SerialClob	Java编程语言中SQL CLOB 值的序列化映射。
SerialDatalink	SQL DATALINK 值在Java编程语言中的序列化映射。
SerialException	指示SQL类型（如 BLOB、CLOB、STRUCT 或 ARRAY）以及SQL类型（如 DATALINK 和 JAVAOBJECT）的序列化或反序列化出现错误。
SerialJavaObject	Java编程语言中SQL JAVA_OBJECT 值的序列化映射。
SerialRef	Ref 对象的序列化映射，它是Java编程语言中SQL REF 值的映射。
SerialStruct	Java编程语言中SQL结构化类型的序列化映射。
SQLInputImpl	用于自定义映射用户定义类型（UDTs）的输入流。
SQLOutputImpl	用于将自定义映射的用户定义类型（UDT）的属性写回数据库的输出流。