-
- All Known Subinterfaces:
CachedRowSet,FilteredRowSet,JdbcRowSet,JoinRowSet,WebRowSet
public interface Joinable1.0 Background
TheJoinableinterface provides the methods for getting and setting a match column, which is the basis for forming the SQLJOINformed by addingRowSetobjects to aJoinRowSetobject.Any standard
RowSetimplementation may implement theJoinableinterface in order to be added to aJoinRowSetobject. Implementing this interface gives aRowSetobject the ability to useJoinablemethods, which set, retrieve, and get information about match columns. An application may add aRowSetobject that has not implemented theJoinableinterface to aJoinRowSetobject, but to do so it must use one of theJoinRowSet.addRowSetmethods that takes both aRowSetobject and a match column or an array ofRowSetobjects and an array of match columns.To get access to the methods in the
Joinableinterface, aRowSetobject implements at least one of the five standardRowSetinterfaces and also implements theJoinableinterface. In addition, mostRowSetobjects extend theBaseRowSetclass. For example:class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable { : : }2.0 Usage Guidelines
The methods in the
Joinableinterface allow aRowSetobject to set a match column, retrieve a match column, or unset a match column, which is the column upon which an SQLJOINcan be based. An instance of a class that implements these methods can be added to aJoinRowSetobject to allow an SQLJOINrelationship 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 aCachedRowSetobject that has implemented theJoinableinterface. In the following example, crs2 has not, so it must supply the match column as an argument to theaddRowSetmethod. 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
JoinRowSetinterface makes it possible to get data from one or moreRowSetobjects 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 disconnectedRowSetobjects. Nevertheless, anyRowSetobject may implement this interface regardless of whether it is connected or disconnected. Note that aJdbcRowSetobject, being always connected to its data source, can become part of an SQLJOINdirectly without having to become part of aJoinRowSetobject.3.0 Managing Multiple Match Columns
The index array passed into thesetMatchColumnmethods 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 differentJoinableobject (aRowSetobject that has implemented theJoinableinterface).int[] w = {3, 2, 5, 3}; Joinable2.setMatchColumn(w);When an application adds two or moreRowSetobjects to aJoinRowSetobject, 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 addedRowSetobject. If overlap or underlap occurs, the match column data is maintained in the event an additionalJoinableRowSet 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 theSQLJOIN.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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description int[]getMatchColumnIndexes()Retrieves the indexes of the match columns that were set for thisRowSetobject with the methodsetMatchColumn(int[] columnIdxes).String[]getMatchColumnNames()Retrieves the names of the match columns that were set for thisRowSetobject with the methodsetMatchColumn(String [] columnNames).voidsetMatchColumn(int columnIdx)Sets the designated column as the match column for thisRowSetobject.voidsetMatchColumn(int[] columnIdxes)Sets the designated columns as the match column for thisRowSetobject.voidsetMatchColumn(String columnName)Sets the designated column as the match column for thisRowSetobject.voidsetMatchColumn(String[] columnNames)Sets the designated columns as the match column for thisRowSetobject.voidunsetMatchColumn(int columnIdx)Unsets the designated column as the match column for thisRowSetobject.voidunsetMatchColumn(int[] columnIdxes)Unsets the designated columns as the match column for thisRowSetobject.voidunsetMatchColumn(String columnName)Unsets the designated column as the match column for thisRowSetobject.voidunsetMatchColumn(String[] columnName)Unsets the designated columns as the match columns for thisRowSetobject.
-
-
-
Method Detail
-
setMatchColumn
void setMatchColumn(int columnIdx) throws SQLExceptionSets the designated column as the match column for thisRowSetobject. AJoinRowSetobject can now add thisRowSetobject based on the match column.Sub-interfaces such as the
CachedRowSet™ interface define the methodCachedRowSet.setKeyColumns, which allows primary key semantics to be enforced on specific columns. Implementations of thesetMatchColumn(int columnIdx)method should ensure that the constraints on the key columns are maintained when aCachedRowSetobject sets a primary key column as a match column.- Parameters:
columnIdx- anintidentifying 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 SQLExceptionSets the designated columns as the match column for thisRowSetobject. AJoinRowSetobject can now add thisRowSetobject based on the match column.- Parameters:
columnIdxes- an array ofintidentifying 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 thisRowSetobject. AJoinRowSetobject can now add thisRowSetobject based on the match column.Subinterfaces such as the
CachedRowSetinterface define the methodCachedRowSet.setKeyColumns, which allows primary key semantics to be enforced on specific columns. Implementations of thesetMatchColumn(String columnIdx)method should ensure that the constraints on the key columns are maintained when aCachedRowSetobject sets a primary key column as a match column.- Parameters:
columnName- aStringobject 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 thisRowSetobject. AJoinRowSetobject can now add thisRowSetobject based on the match column.- Parameters:
columnNames- an array ofStringobjects 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 SQLExceptionRetrieves the indexes of the match columns that were set for thisRowSetobject with the methodsetMatchColumn(int[] columnIdxes).- Returns:
- an
intarray identifying the indexes of the columns that were set as the match columns for thisRowSetobject - 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 thisRowSetobject with the methodsetMatchColumn(String [] columnNames).- Returns:
- an array of
Stringobjects giving the names of the columns set as the match columns for thisRowSetobject - Throws:
SQLException- if no match column has been set- See Also:
setMatchColumn(int),unsetMatchColumn(int)
-
unsetMatchColumn
void unsetMatchColumn(int columnIdx) throws SQLExceptionUnsets the designated column as the match column for thisRowSetobject.RowSetobjects that implement theJoinableinterface must ensure that a key-like constraint continues to be enforced until the methodCachedRowSet.unsetKeyColumnshas been called on the designated column.- Parameters:
columnIdx- anintthat 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 SQLExceptionUnsets the designated columns as the match column for thisRowSetobject.- Parameters:
columnIdxes- an array ofintthat 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 thisRowSetobject.RowSetobjects that implement theJoinableinterface must ensure that a key-like constraint continues to be enforced until the methodCachedRowSet.unsetKeyColumnshas been called on the designated column.- Parameters:
columnName- aStringobject 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 thisRowSetobject.- Parameters:
columnName- an array ofStringobjects 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)
-
-