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

# Interface Joinable

All Known Subinterfaces:
  `CachedRowSet`, `FilteredRowSet`, `JdbcRowSet`, `JoinRowSet`, `WebRowSet`

public interface Joinable

## 1.0 Background

The `Joinable` interface provides the methods for getting and setting a match column, which is the basis for forming the SQL `JOIN` formed by adding `RowSet` objects to a `JoinRowSet` object.

Any standard `RowSet` implementation may implement the `Joinable` interface in order to be added to a `JoinRowSet` object. Implementing this interface gives a `RowSet` object the ability to use `Joinable` methods, which set, retrieve, and get information about match columns. An application may add a `RowSet` object that has not implemented the `Joinable` interface to a `JoinRowSet` object, but to do so it must use one of the `JoinRowSet.addRowSet` methods that takes both a `RowSet` object and a match column or an array of `RowSet` objects and an array of match columns.

To get access to the methods in the `Joinable` interface, a `RowSet` object implements at least one of the five standard `RowSet` interfaces and also implements the `Joinable` interface. In addition, most `RowSet` objects extend the `BaseRowSet` class. For example:

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

## 2.0 Usage Guidelines

The methods in the `Joinable` interface allow a `RowSet` object to set a match column, retrieve a match column, or unset a match column, which is the column upon which an SQL `JOIN` can be based. An instance of a class that implements these methods can be added to a `JoinRowSet` object to allow an SQL `JOIN` relationship to be established.

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

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

In the previous example, crs is a `CachedRowSet` object that has implemented the `Joinable` interface. In the following example, crs2 has not, so it must supply the match column as an argument to the `addRowSet` method. This example assumes that column 1 is the match column.

         CachedRowSet crs2 = new MyRowSetImpl();
         crs2.populate((ResultSet)rs);

         JoinRowSet jrs2 = new JoinRowSetImpl();
         jrs2.addRowSet(crs2, 1);

The `JoinRowSet` interface makes it possible to get data from one or more `RowSet` objects consolidated into one table without having to incur the expense of creating a connection to a database. It is therefore ideally suited for use by disconnected `RowSet` objects. Nevertheless, any `RowSet` object may implement this interface regardless of whether it is connected or disconnected. Note that a `JdbcRowSet` object, being always connected to its data source, can become part of an SQL `JOIN` directly without having to become part of a `JoinRowSet` object.

## 3.0 Managing Multiple Match Columns

The index array passed into the `setMatchColumn` methods indicates how many match columns are being set (the length of the array) in addition to which columns will be used for the match. For example:

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

Subsequent match columns may be added as follows to a different `Joinable` object (a `RowSet` object that has implemented the `Joinable` interface).

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

When an application adds two or more `RowSet` objects to a `JoinRowSet` object, the order of the indexes in the array is particularly important. Each index of the array maps directly to the corresponding index of the previously added `RowSet` object. If overlap or underlap occurs, the match column data is maintained in the event an additional `Joinable` RowSet is added and needs to relate to the match column data. Therefore, applications can set multiple match columns in any order, but this order has a direct effect on the outcome of the `SQL` JOIN.

This assertion applies in exactly the same manner when column names are used rather than column indexes to indicate match columns.

Since:
  1.5
See Also:
  - `JoinRowSet`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int[]`
  `getMatchColumnIndexes()`
  Retrieves the indexes of the match columns that were set for this `RowSet` object with the method `setMatchColumn(int[] columnIdxes)`.
  `String[]`
  `getMatchColumnNames()`
  Retrieves the names of the match columns that were set for this `RowSet` object with the method `setMatchColumn(String [] columnNames)`.
  `void`
  `setMatchColumn(int columnIdx)`
  Sets the designated column as the match column for this `RowSet` object.
  `void`
  `setMatchColumn(int[] columnIdxes)`
  Sets the designated columns as the match column for this `RowSet` object.
  `void`
  `setMatchColumn(String columnName)`
  Sets the designated column as the match column for this `RowSet` object.
  `void`
  `setMatchColumn(String[] columnNames)`
  Sets the designated columns as the match column for this `RowSet` object.
  `void`
  `unsetMatchColumn(int columnIdx)`
  Unsets the designated column as the match column for this `RowSet` object.
  `void`
  `unsetMatchColumn(int[] columnIdxes)`
  Unsets the designated columns as the match column for this `RowSet` object.
  `void`
  `unsetMatchColumn(String columnName)`
  Unsets the designated column as the match column for this `RowSet` object.
  `void`
  `unsetMatchColumn(String[] columnName)`
  Unsets the designated columns as the match columns for this `RowSet` object.

- ## Method Details

  - ### setMatchColumn

    void setMatchColumn(int columnIdx) throws SQLException
    Sets the designated column as the match column for this `RowSet` object. A `JoinRowSet` object can now add this `RowSet` object based on the match column.

    Sub-interfaces such as the `CachedRowSet` interface define the method `CachedRowSet.setKeyColumns`, which allows primary key semantics to be enforced on specific columns. Implementations of the `setMatchColumn(int columnIdx)` method should ensure that the constraints on the key columns are maintained when a `CachedRowSet` object sets a primary key column as a match column.

    Parameters:
      `columnIdx` - an `int` identifying the index of the column to be set as the match column
    Throws:
      `SQLException` - if an invalid column index is set
    See Also:
      - `setMatchColumn(int[])`
      - `unsetMatchColumn(int)`

  - ### setMatchColumn

    void setMatchColumn(int[] columnIdxes) throws SQLException
    Sets the designated columns as the match column for this `RowSet` object. A `JoinRowSet` object can now add this `RowSet` object based on the match column.
    Parameters:
      `columnIdxes` - an array of `int` identifying the indexes of the columns to be set as the match columns
    Throws:
      `SQLException` - if an invalid column index is set
    See Also:
      - `setMatchColumn(int[])`
      - `unsetMatchColumn(int[])`

  - ### setMatchColumn

    void setMatchColumn(String columnName) throws SQLException
    Sets the designated column as the match column for this `RowSet` object. A `JoinRowSet` object can now add this `RowSet` object based on the match column.

    Subinterfaces such as the `CachedRowSet` interface define the method `CachedRowSet.setKeyColumns`, which allows primary key semantics to be enforced on specific columns. Implementations of the `setMatchColumn(String columnIdx)` method should ensure that the constraints on the key columns are maintained when a `CachedRowSet` object sets a primary key column as a match column.

    Parameters:
      `columnName` - a `String` object giving the name of the column to be set as the match column
    Throws:
      `SQLException` - if an invalid column name is set, the column name is a null, or the column name is an empty string
    See Also:
      - `unsetMatchColumn(int)`
      - `setMatchColumn(int[])`

  - ### setMatchColumn

    void setMatchColumn(String[] columnNames) throws SQLException
    Sets the designated columns as the match column for this `RowSet` object. A `JoinRowSet` object can now add this `RowSet` object based on the match column.
    Parameters:
      `columnNames` - an array of `String` objects giving the names of the column to be set as the match columns
    Throws:
      `SQLException` - if an invalid column name is set, the column name is a null, or the column name is an empty string
    See Also:
      - `unsetMatchColumn(int)`
      - `setMatchColumn(int[])`

  - ### getMatchColumnIndexes

    int[] getMatchColumnIndexes() throws SQLException
    Retrieves the indexes of the match columns that were set for this `RowSet` object with the method `setMatchColumn(int[] columnIdxes)`.
    Returns:
      an `int` array identifying the indexes of the columns that were set as the match columns for this `RowSet` object
    Throws:
      `SQLException` - if no match column has been set
    See Also:
      - `setMatchColumn(int)`
      - `unsetMatchColumn(int)`

  - ### getMatchColumnNames

    String[] getMatchColumnNames() throws SQLException
    Retrieves the names of the match columns that were set for this `RowSet` object with the method `setMatchColumn(String [] columnNames)`.
    Returns:
      an array of `String` objects giving the names of the columns set as the match columns for this `RowSet` object
    Throws:
      `SQLException` - if no match column has been set
    See Also:
      - `setMatchColumn(int)`
      - `unsetMatchColumn(int)`

  - ### unsetMatchColumn

    void unsetMatchColumn(int columnIdx) throws SQLException
    Unsets the designated column as the match column for this `RowSet` object.

    `RowSet` objects that implement the `Joinable` interface must ensure that a key-like constraint continues to be enforced until the method `CachedRowSet.unsetKeyColumns` has been called on the designated column.

    Parameters:
      `columnIdx` - an `int` that identifies the index of the column that is to be unset as a match column
    Throws:
      `SQLException` - if an invalid column index is designated or if the designated column was not previously set as a match column
    See Also:
      - `setMatchColumn(int)`

  - ### unsetMatchColumn

    void unsetMatchColumn(int[] columnIdxes) throws SQLException
    Unsets the designated columns as the match column for this `RowSet` object.
    Parameters:
      `columnIdxes` - an array of `int` that identifies the indexes of the columns that are to be unset as match columns
    Throws:
      `SQLException` - if an invalid column index is designated or if the designated column was not previously set as a match column
    See Also:
      - `setMatchColumn(int)`

  - ### unsetMatchColumn

    void unsetMatchColumn(String columnName) throws SQLException
    Unsets the designated column as the match column for this `RowSet` object.

    `RowSet` objects that implement the `Joinable` interface must ensure that a key-like constraint continues to be enforced until the method `CachedRowSet.unsetKeyColumns` has been called on the designated column.

    Parameters:
      `columnName` - a `String` object giving the name of the column that is to be unset as a match column
    Throws:
      `SQLException` - if an invalid column name is designated or the designated column was not previously set as a match column
    See Also:
      - `setMatchColumn(int)`

  - ### unsetMatchColumn

    void unsetMatchColumn(String[] columnName) throws SQLException
    Unsets the designated columns as the match columns for this `RowSet` object.
    Parameters:
      `columnName` - an array of `String` objects giving the names of the columns that are to be unset as the match columns
    Throws:
      `SQLException` - if an invalid column name is designated or the designated column was not previously set as a match column
    See Also:
      - `setMatchColumn(int)`