軟體套件 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 物件。因此，換句話說，如果沒有指定任何映射，則預設情況下可以使用連接的型別映射。