TopBlend: Here is the first difference. There are 8 differences. is old. is new.

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

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).
  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 ( 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 column for this RowSet object.
 

Method Detail

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 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:
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 ofint 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.

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:
SQLException - if in invalid column name is set; if the column name is a null or an empty string set
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 in invalid column name is set; if the column name is a null or an empty string set
See Also:
unsetMatchColumn(int) , setMatchColumn(int[])

getMatchColumnIndexes


int[] getMatchColumnIndexes()
                            throws 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:
SQLException - if no match column has been set
See Also:
setMatchColumn(int) , unsetMatchColumn(int)

getMatchColumnNames


String[] getMatchColumnNames()
                             throws 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:
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 arrary of int that identifies the indexes of the column that are 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(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 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:
SQLException - if an invalid column name is designated or the designated column was not previously set as a match column
See Also:
setMatchColumn(int)