Module java.sql.rowset
Package javax.sql.rowset

Interface JoinRowSet

所有超接口:
AutoCloseable, CachedRowSet, Joinable, ResultSet, RowSet, WebRowSet, Wrapper
public interface JoinRowSet extends WebRowSet
JoinRowSet接口提供了一种机制，将来自不同RowSet对象的相关数据合并到一个JoinRowSet对象中，该对象表示一个SQL JOIN。换句话说，JoinRowSet对象充当了来自形成SQL JOIN关系的RowSet对象的数据的容器。

Joinable接口提供了设置、检索和取消匹配列的方法，这是建立SQL JOIN关系的基础。也可以通过将其提供给适当版本的JointRowSet方法addRowSet来设置匹配列。

1.0 概述

断开连接的RowSet对象（CachedRowSet对象和扩展CachedRowSet接口的实现）没有一种标准方法可以在不重新连接到数据源的情况下建立RowSet对象之间的SQL JOIN。JoinRowSet接口专门设计用于解决这个需求。

任何RowSet对象都可以添加到一个JoinRowSet对象中，成为SQL JOIN关系的一部分。这意味着连接和断开连接的RowSet对象都可以成为JOIN的一部分。在连接环境中操作的RowSet对象（JdbcRowSet对象）被鼓励使用它们已连接到的数据库直接建立表之间的SQL JOIN关系。但是，如果必要，也可以将JdbcRowSet对象添加到JoinRowSet对象中。

可以将任意数量的RowSet对象添加到JoinRowSet的实例中，前提是它们可以在SQL JOIN中相关联。根据定义，SQL JOIN语句用于基于共同属性合并两个或多个关系数据库表中包含的数据。Joinable接口提供了建立共同属性的方法，这是通过设置一个匹配列来完成的。匹配列通常与主键相符，但不要求匹配列与主键相同。通过建立并强制执行列匹配，JoinRowSet对象在没有可用关系数据库的情况下建立JOIN关系。

要建立的JOIN类型是通过使用方法setJoinType设置JoinRowSet常量之一来确定的。可以设置以下SQL JOIN类型：

  • CROSS_JOIN
  • FULL_JOIN
  • INNER_JOIN - 如果未设置任何JOIN类型，则默认为内部连接
  • LEFT_OUTER_JOIN
  • RIGHT_OUTER_JOIN
请注意，如果未设置类型，则JOIN将自动成为内部连接。JoinRowSet接口中字段的注释解释了这些JOIN类型，这些类型是标准的SQL JOIN类型。

2.0 使用JoinRowSet对象创建JOIN

创建JoinRowSet对象时，它是空的。要添加的第一个RowSet对象成为JOIN关系的基础。应用程序必须确定要添加到JoinRowSet对象的每个RowSet对象中的哪一列应该是匹配列。所有的RowSet对象必须包含一个匹配列，并且每个匹配列中的值必须是可以与其他匹配列中的值进行比较的值。这些列不必具有相同的名称，尽管它们通常是，它们也不必存储完全相同的数据类型，只要数据类型可以进行比较即可。

可以通过两种方式设置匹配列：

  • 通过调用Joinable方法setMatchColumn
    这是在将RowSet对象添加到JoinRowSet对象之前设置匹配列的唯一方法。RowSet对象必须实现Joinable接口才能使用方法setMatchColumn。一旦设置了匹配列值，可以随时使用此方法重置匹配列。
  • 通过调用JoinRowSet方法addRowSet的版本之一，该方法接受列名或编号（或列名或编号数组）
    五个addRowSet方法中的四个方法将匹配列作为参数。这四个方法在将RowSet对象添加到JoinRowSet对象时设置或重置匹配列。

3.0 示例用法

以下代码片段将两个CachedRowSet对象添加到一个JoinRowSet对象中。请注意，在此示例中，未设置任何SQL JOIN类型，因此建立了默认的JOIN类型，即INNER_JOIN。

在以下代码片段中，表EMPLOYEES的匹配列设置为第一列（EMP_ID），然后添加到JoinRowSet对象jrs中。然后，表ESSP_BONUS_PLAN，其匹配列同样是EMP_ID列，也被添加。当将第二个表添加到jrs时，只有ESSP_BONUS_PLAN中的行，其EMP_ID值与EMPLOYEES表中的EMP_ID值匹配的行才会被添加。在这种情况下，奖金计划中的每个人都是员工，因此表ESSP_BONUS_PLAN中的所有行都将添加到JoinRowSet对象中。在此示例中，被添加的两个CachedRowSet对象都实现了Joinable接口，因此可以调用Joinable方法setMatchColumn。

     JoinRowSet jrs = new JoinRowSetImpl();

     ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES");
     CachedRowSet empl = new CachedRowSetImpl();
     empl.populate(rs1);
     empl.setMatchColumn(1);
     jrs.addRowSet(empl);

     ResultSet rs2 = stmt.executeQuery("SELECT * FROM ESSP_BONUS_PLAN");
     CachedRowSet bonus = new CachedRowSetImpl();
     bonus.populate(rs2);
     bonus.setMatchColumn(1); // EMP_ID is the first column
     jrs.addRowSet(bonus);

此时，jrs是基于它们的EMP_ID列的两个RowSet对象的内部连接。应用程序现在可以浏览组合数据，就好像浏览单个RowSet对象一样。因为jrs本身是一个RowSet对象，所以应用程序可以使用RowSet方法导航或修改它。

     jrs.first();
     int employeeID = jrs.getInt(1);
     String employeeName = jrs.getString(2);

请注意，因为当应用程序添加第二个或后续RowSet对象时必须强制执行SQL JOIN，所以在执行JOIN时可能会有初始性能下降。

以下代码片段添加了另一个CachedRowSet对象。在这种情况下，当将CachedRowSet对象添加到JoinRowSet对象时，匹配列（EMP_ID）被设置。

     ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB");
     CachedRowSet fourO1k = new CachedRowSetImpl();
     four01k.populate(rs3);
     jrs.addRowSet(four01k, 1);

JoinRowSet对象jrs现在包含来自所有三个表的值。在four01k中的每一行中，EMP_ID列的值与jrs中的EMP_ID列的值匹配的数据都已添加到jrs中。

4.0 JoinRowSet方法

JoinRowSet接口提供了几种方法，用于添加RowSet对象和获取有关JoinRowSet对象的信息。
  • 添加一个或多个RowSet对象的方法
    这些方法允许应用程序一次添加一个RowSet对象，或一次添加多个RowSet对象。在任何情况下，这些方法都可以为每个被添加的RowSet对象指定匹配列。
  • 获取信息的方法
    一个方法检索JoinRowSet对象中的RowSet对象，另一个方法检索RowSet名称。第三个方法检索用于在幕后形成JOIN的SQL WHERE子句，或者检索WHERE子句的文本描述。
  • 与JOIN类型相关的方法
    一个方法设置JOIN类型，五个方法查找JoinRowSet对象是否支持给定类型。
  • 创建JoinRowSet对象的单独副本的方法
    此方法创建一个可以持久化到数据源的副本。
自从:
1.5

  • Field Details

    • CROSS_JOIN

      static final int CROSS_JOIN
      提供两个表的交叉乘积的ANSI风格JOIN。
      参见：

    • INNER_JOIN

      static final int INNER_JOIN
      提供两个表之间内部连接的ANSI风格JOIN。连接中任一表中未匹配的行应被丢弃。
      参见：

    • LEFT_OUTER_JOIN

      static final int LEFT_OUTER_JOIN
      提供两个表之间左外连接的ANSI风格JOIN。在SQL中，这是指应从JOIN语句的左侧返回所有记录。
      参见：

    • RIGHT_OUTER_JOIN

      static final int RIGHT_OUTER_JOIN
      提供两个表之间右外连接的ANSI风格JOIN。在SQL中，这是指即使左侧表没有匹配记录，也应从JOIN语句的右侧表返回所有记录。
      参见：

    • FULL_JOIN

      static final int FULL_JOIN
      提供全连接的ANSI风格JOIN。指定应返回来自任一表的所有行，而不考虑另一表上的匹配记录。
      参见：

  • Method Details

    • addRowSet

      void addRowSet(Joinable rowset) throws SQLException
      将给定的RowSet对象添加到此JoinRowSet对象。如果RowSet对象是添加到此JoinRowSet对象的第一个对象，则它将成为要建立的JOIN关系的基础。

      仅当给定的RowSet对象已经使用Joinable方法setMatchColumn设置了匹配列时，应使用此方法。

      注意：任何实现了Joinable接口的RowSet对象都是Joinable对象。

      参数：
      rowset - 要添加到此JoinRowSet对象的RowSet对象；它必须实现Joinable接口并设置匹配列
      抛出：
      SQLException - 如果：(1) 向此JoinRowSet对象添加了空行集，(2) 未为rowset设置匹配列，或(3) rowset违反了活动的JOIN
      参见：

    • addRowSet

      void addRowSet(RowSet rowset, int columnIdx) throws SQLException
      将给定的RowSet对象添加到此JoinRowSet对象，并为RowSet对象设置指定的列作为匹配列。如果RowSet对象是添加到此JoinRowSet对象的第一个对象，则它将成为要建立的JOIN关系的基础。

      当RowSet尚未设置匹配列时，应使用此方法。

      参数：
      rowset - 要添加到此JoinRowSet对象的RowSet对象；它可能实现Joinable接口
      columnIdx - 标识要成为匹配列的列的int
      抛出：
      SQLException - 如果：(1) rowset是空行集或(2) rowset违反了活动的JOIN
      参见：

    • addRowSet

      void addRowSet(RowSet rowset, String columnName) throws SQLException
      将rowset添加到此JoinRowSet对象，并将指定的列设置为匹配列。如果rowset是添加到此JoinRowSet对象的第一个对象，则它将成为要建立的JOIN关系的基础。

      当给定的RowSet对象尚未设置匹配列时，应使用此方法。

      参数：
      rowset - 要添加到此JoinRowSet对象的RowSet对象；它可能实现Joinable接口
      columnName - 给出要设置为匹配列的列的String对象的名称
      抛出：
      SQLException - 如果：(1) rowset是空行集或(2) rowset的匹配列不满足JOIN的条件

    • addRowSet

      void addRowSet(RowSet[] rowset, int[] columnIdx) throws SQLException
      将包含在给定的RowSet对象数组中的一个或多个RowSet对象添加到此JoinRowSet对象，并为每个RowSet对象设置匹配列为给定的列索引数组中的匹配列。在columnIdx中的第一个元素设置为rowset中的第一个RowSet对象的匹配列，columnIdx的第二个元素设置为rowset中的第二个元素的匹配列，依此类推。

      添加到此JoinRowSet对象的第一个RowSet对象将成为JOIN关系的基础。

      当给定的RowSet对象尚未设置匹配列时，应使用此方法。

      参数：
      rowset - 一个或多个要添加到JOIN的RowSet对象数组；它可能实现Joinable接口
      columnIdx - 一个int值数组，指示要为rowset中的RowSet对象设置为匹配列的索引
      抛出：
      SQLException - 如果：(1) 向此JoinRowSet对象添加了空行集，(2) 未为rowset中的RowSet对象设置匹配列，或(3) 正在添加的RowSet对象违反了活动的JOIN

    • addRowSet

      void addRowSet(RowSet[] rowset, String[] columnName) throws SQLException
      将包含在给定的RowSet对象数组中的一个或多个RowSet对象添加到此JoinRowSet对象，并为每个RowSet对象设置匹配列为给定的列名称数组中的匹配列。在columnName中的第一个元素设置为rowset中的第一个RowSet对象的匹配列，columnName的第二个元素设置为rowset中的第二个元素的匹配列，依此类推。

      添加到此JoinRowSet对象的第一个RowSet对象将成为JOIN关系的基础。

      当给定的RowSet对象尚未设置匹配列时，应使用此方法。

      参数：
      rowset - 一个或多个要添加到JOIN的RowSet对象数组；它可能实现Joinable接口
      columnName - 一个String值数组，指示要为rowset中的RowSet对象设置为匹配列的名称
      抛出：
      SQLException - 如果：(1) 向此JoinRowSet对象添加了空行集，(2) 未为rowset中的RowSet对象设置匹配列，或(3) 正在添加的RowSet对象违反了活动的JOIN

    • getRowSets

      Collection<?> getRowSets() throws SQLException
      返回一个包含已添加到此JoinRowSet对象的RowSet对象的Collection对象。这应返回包含在JOIN中的'n'个RowSet并保留在此联合中发生的任何更新。
      返回：
      由添加到此JoinRowSet对象的RowSet对象组成的Collection对象
      抛出：
      SQLException - 如果生成要返回的Collection对象时发生错误

    • getRowSetNames

      String[] getRowSetNames() throws SQLException
      返回一个包含已添加到此JoinRowSet对象的RowSet对象名称的String数组。
      返回:
      返回一个String数组，包含此JoinRowSet对象中RowSet对象的名称
      抛出:
      SQLException - 如果检索RowSet对象的名称时发生错误
      参见:

    • toCachedRowSet

      CachedRowSet toCachedRowSet() throws SQLException
      创建一个包含此JoinRowSet对象中数据的新CachedRowSet对象，可以使用CachedRowSet对象的SyncProvider对象将其保存到数据源中。

      如果对JoinRowSet应用了任何更新或修改，则该方法返回的CachedRowSet将无法将其更改持久化到数据源中的原始行和表中。返回的CachedRowSet实例不应包含修改数据，并且应清除其原始SQL语句的所有属性。应用程序应使用RowSet.setCommand方法重置SQL语句。

      为了允许更改持久化到数据源中的原始表中，应在JoinRowSet对象实例上使用acceptChanges方法并调用它。实现可以利用其实现中的内部数据和更新跟踪与SyncProvider交互，以持久化任何更改。

      返回:
      包含JoinRowSet内容的CachedRowSet
      抛出:
      SQLException - 如果在组装CachedRowSet对象时发生错误
      参见:

    • supportsCrossJoin

      boolean supportsCrossJoin()
      指示JoinRowSet实现是否支持CROSS_JOIN
      返回:
      如果支持CROSS_JOIN则返回true；否则返回false

    • supportsInnerJoin

      boolean supportsInnerJoin()
      指示JoinRowSet实现是否支持INNER_JOIN
      返回:
      如果支持INNER_JOIN则返回true；否则返回false

    • supportsLeftOuterJoin

      boolean supportsLeftOuterJoin()
      指示JoinRowSet实现是否支持LEFT_OUTER_JOIN
      返回:
      如果支持LEFT_OUTER_JOIN则返回true；否则返回false

    • supportsRightOuterJoin

      boolean supportsRightOuterJoin()
      指示JoinRowSet实现是否支持RIGHT_OUTER_JOIN
      返回:
      如果支持RIGHT_OUTER_JOIN则返回true；否则返回false

    • supportsFullJoin

      boolean supportsFullJoin()
      指示JoinRowSet实现是否支持FULL_JOIN
      返回:
      如果支持FULL_JOIN则返回true；否则返回false

    • setJoinType

      void setJoinType(int joinType) throws SQLException
      允许应用程序调整JoinRowSet对象实例中包含的表之间强加的JOIN类型。如果实现不支持给定的JOIN类型，则应抛出SQLException。
      参数:
      joinType - SQL JOIN的标准JoinRowSet.XXX静态字段定义，用于动态重新配置JoinRowSet实例的JOIN类型。
      抛出:
      SQLException - 如果设置了不支持的JOIN类型
      参见:

    • getWhereClause

      String getWhereClause() throws SQLException
      返回一个类似SQL的描述，描述JoinRowSet对象中使用的WHERE子句。实现可以通过提供SQL字符串描述JOIN的WHERE子句，或提供文本描述来帮助使用JoinRowSet的应用程序。
      返回:
      whereClause描述JoinRowSet实例中使用的逻辑WHERE子句的文本或SQL描述
      抛出:
      SQLException - 如果生成WHERE子句的表示发生错误

    • getJoinType

      int getJoinType() throws SQLException
      返回一个描述管理此JoinRowSet实例的SQL JOIN类型的int。返回的类型将是标准JoinRowSet类型之一：CROSS_JOIN、INNER_JOIN、LEFT_OUTER_JOIN、RIGHT_OUTER_JOIN或FULL_JOIN。
      返回:
      joinType一个SQL JOIN的标准JoinRowSet静态字段定义。如果未明确设置类型，则返回JoinRowSet.INNER_JOIN作为默认JOIN类型。
      抛出:
      SQLException - 如果确定JoinRowSet实例支持的SQL JOIN类型时发生错误
      参见: