javax.sql.rowset
介面 Joinable

所有已知子介面：

CachedRowSet, FilteredRowSet, JdbcRowSet, JoinRowSet, WebRowSet

public interface Joinable

1.0 背景

Joinable 介面提供了用於獲取和設置比對列的各種方法，比對列是形成通過將 RowSet 物件添加到 JoinRowSet 物件所形成的 SQL JOIN 的基礎。

任何標準 RowSet 實作都可以實作 Joinable 介面，以便能夠被添加到 JoinRowSet 物件中。實作此介面使 RowSet 物件能夠使用各種 Joinable 方法，這些方法可設置、檢索和獲取有關比對列的資訊。應用程序可以將尚未實作 Joinable 介面的 RowSet 物件添加到 JoinRowSet 物件中，但是這樣做必須使用一個同時帶有 RowSet 物件和比對列（或者 RowSet 物件陣列和比對列陣列）的 JoinRowSet.addRowSet 方法。

要獲取存取 Joinable 介面中的方法，RowSet 物件至少要實作 5 個標準 RowSet 介面中的一個並且要實作 Joinable 介面。另外，多數 RowSet 物件擴展了 BaseRowSet 類別。例如：

     class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable {
         :
         :
     }
 

2.0 使用指南

Joinable 介面中的方法允許 RowSet 物件設置比對列、獲取比對列或取消設置比對列，比對列是 SQL JOIN 的基礎。可將實作這些方法的類別的實例添加到 JoinRowSet 物件，以便允許建立 SQL JOIN 關係。

     CachedRowSet crs = new MyRowSetImpl();
     crs.populate((ResultSet)rs);
     (Joinable)crs.setMatchColumnIndex(1);

     JoinRowSet jrs = new JoinRowSetImpl();
     jrs.addRowSet(crs);
 

在上例中，crs 是一個已經實作了 Joinable 介面的 CachedRowSet 物件。在下例中，crs2 沒有實作 Joinable 介面，所以它必須將比對列作為參數提供給 addRowSet 方法。此範例假定列 1 是比對列。

     CachedRowSet crs2 = new MyRowSetImpl();
     crs2.populate((ResultSet)rs);
     
     JoinRowSet jrs2 = new JoinRowSetImpl();
     jrs2.addRowSet(crs2, 1);
 

JoinRowSet 介面使它能夠從已合併為一個表的一個或多個 RowSet 物件獲取資料，從而避免了創建資料庫連接的開銷。因此理論上它非常適合於非連接 RowSet 物件使用。儘管如此，任何 RowSet 物件都可以實作此介面，無論它是連接的還是非連接的。注意，始終連接到其資料源的 JdbcRowSet 物件可以直接成為 SQL JOIN 的一部分，而不必先成為 JoinRowSet 物件的一部分。

3.0 管理多個比對列

傳遞到 setMatchColumn 方法中的索引陣列除了指示將用於比對的列外，還指示要設置的比對列數（陣列的長度）。例如：

     int[] i = {1, 2, 4, 7}; // indicates four match columns, with column
                             // indexes 1, 2, 4, 7 participating in the JOIN.
     Joinable.setMatchColumn(i);
 

可按以下方式將後續比對列添加到不同 Joinable 物件（已經實作 Joinable 介面的 RowSet 物件）。

     int[] w = {3, 2, 5, 3};
     Joinable2.setMatchColumn(w);
 

當應用程序向 JoinRowSet 物件添加兩個或更多 RowSet 物件時，陣列中索引的順序特別重要。每個陣列索引都直接映射到以前添加的 RowSet 物件的相應索引。如果出現重疊或間隙，則比對列資料將被保留在添加了附加 Joinable RowSet 並需要關聯比對列資料的事件中。因此，應用程序可以以任意順序設置多個比對列，但是此順序對 SQL JOIN 的結果有直接的影響。

此斷言在使用列名而不是列索引來指示比對列時也同樣適用。

另請參見：

JoinRowSet

方法摘要

int[]	getMatchColumnIndexes() 獲取使用方法 setMatchColumn(int[] columnIdxes) 為此 RowSet 物件設置的比對列的索引。
String[]	getMatchColumnNames() 獲取使用方法 setMatchColumn(String [] columnNames) 為此 RowSet 物件設置的比對列的名稱。
void	setMatchColumn(int columnIdx) 將指定的列設置為此 RowSet 物件的比對列。
void	setMatchColumn(int[] columnIdxes) 將指定的列設置為此 RowSet 物件的比對列。
void	setMatchColumn(String columnName) 將指定的列設置為此 RowSet 物件的比對列。
void	setMatchColumn(String[] columnNames) 將指定的列設置為此 RowSet 物件的比對列。
void	unsetMatchColumn(int columnIdx) 取消將指定的列設置為此 RowSet 物件的比對列。
void	unsetMatchColumn(int[] columnIdxes) 取消將指定的列設置為此 RowSet 物件的比對列。
void	unsetMatchColumn(String columnName) 取消將指定的列設置為此 RowSet 物件的比對列。
void	unsetMatchColumn(String[] columnName) 取消將指定的列設置為此 RowSet 物件的比對列。

方法詳細資訊

setMatchColumn

void setMatchColumn(int columnIdx)
                    throws SQLException

將指定的列設置為此 RowSet 物件的比對列。現在 JoinRowSet 物件可以根據比對列添加此 RowSet 物件。

子介面（如 CachedRowSet^TM 介面）定義了方法 CachedRowSet.setKeyColumns，該方法允許在具體列上強制執行主鍵語義。當 CachedRowSet 物件將主鍵列設置為比對列時，setMatchColumn(int columnIdx) 方法的實作應該確保堅持關於鍵列的約束條件。

參數：

columnIdx - 一個 int 值，標識要設置為比對列的列索引

拋出：

SQLException - 如果設置了無效的列索引

另請參見：

setMatchColumn(int[]), unsetMatchColumn(int)

setMatchColumn

void setMatchColumn(int[] columnIdxes)
                    throws SQLException

將指定的列設置為此 RowSet 物件的比對列。現在 JoinRowSet 物件可以根據比對列添加此 RowSet 物件。

參數：

columnIdxes - 一個 int 陣列，標識要設置為比對列的列索引

拋出：

SQLException - 如果設置了無效的列索引

另請參見：

setMatchColumn(int[]), unsetMatchColumn(int[])

setMatchColumn

void setMatchColumn(String columnName)
                    throws SQLException

將指定的列設置為此 RowSet 物件的比對列。現在 JoinRowSet 物件可以根據比對列添加此 RowSet 物件。

子介面（如 CachedRowSet 介面）定義方法 CachedRowSet.setKeyColumns，該方法允許在具體列上強制執行主鍵語義。當 CachedRowSet 物件將主鍵列設置為比對列時，setMatchColumn(String columnIdx) 方法的實作應該確保堅持關於鍵列的約束條件。

參數：

columnName - String 物件，提供了要設置為比對列的列名

拋出：

SQLException - 如果設置了無效的列名、列名為 null 或列名是空字元串

另請參見：

unsetMatchColumn(int), setMatchColumn(int[])

setMatchColumn

void setMatchColumn(String[] columnNames)
                    throws SQLException

將指定的列設置為此 RowSet 物件的比對列。現在 JoinRowSet 物件可以根據比對列添加此 RowSet 物件。

參數：

columnNames - String 物件陣列，提供了要設置為比對列的列名

拋出：

SQLException - 如果設置了無效的列名、列名為 null 或列名是空字元串

另請參見：

unsetMatchColumn(int), setMatchColumn(int[])

getMatchColumnIndexes

int[] getMatchColumnIndexes()
                            throws SQLException

獲取使用方法 setMatchColumn(int[] columnIdxes) 為此 RowSet 物件設置的比對列的索引。

返回：

int 陣列，標識已設置為此 RowSet 物件比對列的列索引

拋出：

SQLException - 如果未設置任何比對列

另請參見：

setMatchColumn(int), unsetMatchColumn(int)

getMatchColumnNames

String[] getMatchColumnNames()
                             throws SQLException

獲取使用方法 setMatchColumn(String [] columnNames) 為此 RowSet 物件設置的比對列的名稱。

返回：

String 物件陣列，提供了已設置為此 RowSet 物件比對列的列名稱

拋出：

SQLException - 如果未設置任何比對列

另請參見：

setMatchColumn(int), unsetMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(int columnIdx)
                      throws SQLException

取消將指定的列設置為此 RowSet 物件的比對列。

在指定的列上調用方法 CachedRowSet.unsetKeyColumns 之前，實作了 Joinable 介面的 RowSet 物件必須確保可繼續強制執行與鍵有關的約束條件。

參數：

columnIdx - 一個 int 值，標識被取消設置為比對列的列索引

拋出：

SQLException - 如果指定了無效的列索引或者指定的列以前未被設置為比對列

另請參見：

setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(int[] columnIdxes)
                      throws SQLException

取消將指定的列設置為此 RowSet 物件的比對列。

參數：

columnIdxes - int 陣列，標識被取消設置為比對列的列索引

拋出：

SQLException - 如果指定了無效的列索引或者指定的列以前未被設置為比對列

另請參見：

setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(String columnName)
                      throws SQLException

取消將指定的列設置為此 RowSet 物件的比對列。

在指定的列上調用方法 CachedRowSet.unsetKeyColumns 之前，實作了 Joinable 介面的 RowSet 物件必須確保可繼續強制執行與鍵有關的約束條件。

參數：

columnName - String 物件，提供了被取消設置為比對列的列名

拋出：

SQLException - 如果指定了無效的列名或者指定的列以前未被設置為比對列

另請參見：

setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(String[] columnName)
                      throws SQLException

取消將指定的列設置為此 RowSet 物件的比對列。

參數：

columnName - String 物件陣列，提供了被取消設置為比對列的列名

拋出：

SQLException - 如果指定了無效的列名或者指定的列以前未被設置為比對列

另請參見：

setMatchColumn(int)