javax.sql.rowset
Interface Joinable

All Known Subinterfaces:

CachedRowSet, CachedRowSetX, FilteredRowSet, JdbcRowSet, JdbcRowSetX, JoinRowSet, WebRowSet

All Known Implementing Classes:

CachedRowSetImpl, CachedRowSetXImpl, FilteredRowSetImpl, JdbcRowSetImpl, JdbcRowSetXImpl, JoinRowSetImpl, WebRowSetImpl

public interface Joinable

1.0 Background

The Joinable interface provides the methods any standard RowSet implementation must implement in order to be added to a JoinRowSet object. Therefore, in order for a RowSet implementation to become 'joinable', it will implement this interface in addition to extending the BaseRowSet class and implementing any of the other standard RowSet interfaces described in this package. For example:

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

NOTE: It is not mandatory requirement for all standard RowSet objects to implement the Joinable interface. This is only necessary when an RowSet object wishes to be consumed by a JoinRowSet to participate in a SQL JOIN.

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);
 

Any RowSet object may implement this interface regardless of whether it is connected or disconnected. 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. However, both connected and disconnected RowSet objects have to implement the Joinable interface to be eligible for becoming part of an SQL JOIN through being added to a JoinRowSet object.

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.

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

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

When adding the two Joinable RowSets to a JoinRowSet, the order of the array index plays particular importance here. Each index of the array maps directly to the corresponding index of the previously added Joinable RowSet. If over-lap or under-lap 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 affect on the outcome of the SQL JOIN.

Ths assertion applies in exactly the same manner when column names are used rather than column indexes.

Author:

Jonathan Bruce

See Also:

JoinRowSet

Method Summary

int[]	getMatchColumnIndexes() Retrieves the index of the match column that was set for this RowSet object with the method setMatchColumn(int columnIdx).
java.lang.String[]	getMatchColumnNames() Retrieves the name of the match column that was set for this RowSet object with the method setMatchColumn(String columnName).
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(java.lang.String columnName) Sets the designated column as the match column for this RowSet object.
void	setMatchColumn(java.lang.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(java.lang.String columnName) Unsets the designated column as the match column for this RowSet object.
void	unsetMatchColumn(java.lang.String[] columnName) Unsets the designated columns as the match column for this RowSet object.

Method Detail

setMatchColumn

public void setMatchColumn(int columnIdx)
                    throws java.sql.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^TM 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:

java.sql.SQLException - if an invalid column index is set

See Also:

setMatchColumn(int[]), unsetMatchColumn(int)

setMatchColumn

public void setMatchColumn(int[] columnIdxes)
                    throws java.sql.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:

java.sql.SQLException - if an invalid column index is set

See Also:

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

setMatchColumn

public void setMatchColumn(java.lang.String columnName)
                    throws java.sql.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(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:

java.sql.SQLException - if in invalid column name is set; if the column name is a null or an empty string

See Also:

unsetMatchColumn(int), setMatchColumn(int[])

setMatchColumn

public void setMatchColumn(java.lang.String[] columnNames)
                    throws java.sql.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:

java.sql.SQLException - if in invalid column name is set; if the column name is a null or an empty string

See Also:

unsetMatchColumn(int), setMatchColumn(int[])

getMatchColumnIndexes

public int[] getMatchColumnIndexes()
                            throws java.sql.SQLException

Retrieves the index of the match column that was set for this RowSet object with the method setMatchColumn(int columnIdx).

Returns:

an int identifying the index of the column that was set as the match column for this RowSet object

Throws:

java.sql.SQLException - if no match column has been set

See Also:

setMatchColumn(int), unsetMatchColumn(int)

getMatchColumnNames

public java.lang.String[] getMatchColumnNames()
                                       throws java.sql.SQLException

Retrieves the name of the match column that was set for this RowSet object with the method setMatchColumn(String columnName).

Returns:

columnName the String object giving the name of the column set as the match column for this RowSet object

Throws:

java.sql.SQLException - if no match column has been set

See Also:

setMatchColumn(int), unsetMatchColumn(int)

unsetMatchColumn

public void unsetMatchColumn(int columnIdx)
                      throws java.sql.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:

java.sql.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

public void unsetMatchColumn(int[] columnIdxes)
                      throws java.sql.SQLException

Unsets the designated columns as the match column for this RowSet object.

Parameters:

columnIdxes - an arrary of int that identifies the indexes of the column that are to be unset as a match column

Throws:

java.sql.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

public void unsetMatchColumn(java.lang.String columnName)
                      throws java.sql.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:

java.sql.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

public void unsetMatchColumn(java.lang.String[] columnName)
                      throws java.sql.SQLException

Unsets the designated columns as the match column for this RowSet object.

Parameters:

columnName - a array String objects giving the name of the columns that are to be unset as a match columns

Throws:

java.sql.SQLException - if an invalid column name is designated or the designated column was not previously set as a match column

See Also:

setMatchColumn(int)