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)