AutoCloseable
, CachedRowSet
, Joinable
, ResultSet
, RowSet
, WebRowSet
, Wrapper
public interface JoinRowSet extends WebRowSet
JoinRowSet
interface provides a mechanism for combining related data from different RowSet
objects into one JoinRowSet
object, which represents an SQL JOIN
. In other words, a JoinRowSet
object acts as a container for the data from RowSet
objects that form an SQL JOIN
relationship. The Joinable
interface provides the methods for setting, retrieving, and unsetting a match column, the basis for establishing an SQL JOIN
relationship. The match column may alternatively be set by supplying it to the appropriate version of the JointRowSet
method addRowSet
.
RowSet
objects (CachedRowSet
objects and implementations extending the CachedRowSet
interface) do not have a standard way to establish an SQL JOIN
between RowSet
objects without the expensive operation of reconnecting to the data source. The JoinRowSet
interface is specifically designed to address this need. Any RowSet
object can be added to a JoinRowSet
object to become part of an SQL JOIN
relationship. This means that both connected and disconnected RowSet
objects can be part of a JOIN
. RowSet
objects operating in a connected environment (JdbcRowSet
objects) are encouraged to use the database to which they are already connected to establish SQL JOIN
relationships between tables directly. However, it is possible for a JdbcRowSet
object to be added to a JoinRowSet
object if necessary.
Any number of RowSet
objects can be added to an instance of JoinRowSet
provided that they can be related in an SQL JOIN
. By definition, the SQL JOIN
statement is used to combine the data contained in two or more relational database tables based upon a common attribute. The Joinable
interface provides the methods for establishing a common attribute, which is done by setting a match column. The match column commonly coincides with the primary key, but there is no requirement that the match column be the same as the primary key. By establishing and then enforcing column matches, a JoinRowSet
object establishes JOIN
relationships between RowSet
objects without the assistance of an available relational database.
The type of JOIN
to be established is determined by setting one of the JoinRowSet
constants using the method setJoinType
. The following SQL JOIN
types can be set:
CROSS_JOIN
FULL_JOIN
INNER_JOIN
- the default if no JOIN
type has been set LEFT_OUTER_JOIN
RIGHT_OUTER_JOIN
JOIN
will automatically be an inner join. The comments for the fields in the JoinRowSet
interface explain these JOIN
types, which are standard SQL JOIN
types. JoinRowSet
Object for Creating a JOIN
JoinRowSet
object is created, it is empty. The first RowSet
object to be added becomes the basis for the JOIN
relationship. Applications must determine which column in each of the RowSet
objects to be added to the JoinRowSet
object should be the match column. All of the RowSet
objects must contain a match column, and the values in each match column must be ones that can be compared to values in the other match columns. The columns do not have to have the same name, though they often do, and they do not have to store the exact same data type as long as the data types can be compared. A match column can be set in two ways:
Joinable
method setMatchColumn
RowSet
object is added to a JoinRowSet
object. The RowSet
object must have implemented the Joinable
interface in order to use the method setMatchColumn
. Once the match column value has been set, this method can be used to reset the match column at any time. JoinRowSet
method addRowSet
that takes a column name or number (or an array of column names or numbers)addRowSet
methods take a match column as a parameter. These four methods set or reset the match column at the time a RowSet
object is being added to a JoinRowSet
object. The following code fragment adds two CachedRowSet
objects to a JoinRowSet
object. Note that in this example, no SQL JOIN
type is set, so the default JOIN
type, which is INNER_JOIN, is established.
In the following code fragment, the table EMPLOYEES
, whose match column is set to the first column (EMP_ID
), is added to the JoinRowSet
object jrs. Then the table ESSP_BONUS_PLAN
, whose match column is likewise the EMP_ID
column, is added. When this second table is added to jrs, only the rows in ESSP_BONUS_PLAN
whose EMP_ID
value matches an EMP_ID
value in the EMPLOYEES
table are added. In this case, everyone in the bonus plan is an employee, so all of the rows in the table ESSP_BONUS_PLAN
are added to the JoinRowSet
object. In this example, both CachedRowSet
objects being added have implemented the Joinable
interface and can therefore call the Joinable
method 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);
At this point, jrs is an inside JOIN of the two RowSet
objects based on their EMP_ID
columns. The application can now browse the combined data as if it were browsing one single RowSet
object. Because jrs is itself a RowSet
object, an application can navigate or modify it using RowSet
methods.
jrs.first(); int employeeID = jrs.getInt(1); String employeeName = jrs.getString(2);
Note that because the SQL JOIN
must be enforced when an application adds a second or subsequent RowSet
object, there may be an initial degradation in performance while the JOIN
is being performed.
The following code fragment adds an additional CachedRowSet
object. In this case, the match column (EMP_ID
) is set when the CachedRowSet
object is added to the JoinRowSet
object.
ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB"); CachedRowSet fourO1k = new CachedRowSetImpl(); four01k.populate(rs3); jrs.addRowSet(four01k, 1);
The JoinRowSet
object jrs now contains values from all three tables. The data in each row in four01k in which the value for the EMP_ID
column matches a value for the EMP_ID
column in jrs has been added to jrs.
JoinRowSet
MethodsJoinRowSet
interface supplies several methods for adding RowSet
objects and for getting information about the JoinRowSet
object. RowSet
objectsRowSet
object at a time or to add multiple RowSet
objects at one time. In either case, the methods may specify the match column for each RowSet
object being added. RowSet
objects in the JoinRowSet
object, and another method retrieves the RowSet
names. A third method retrieves either the SQL WHERE
clause used behind the scenes to form the JOIN
or a text description of what the WHERE
clause does. JOIN
JOIN
type, and five methods find out whether the JoinRowSet
object supports a given type. JoinRowSet
objectModifier and Type | Field | Description |
---|---|---|
static final int |
CROSS_JOIN |
An ANSI-style JOIN providing a cross product of two tables |
static final int |
FULL_JOIN |
An ANSI-style JOIN providing a full JOIN. |
static final int |
INNER_JOIN |
An ANSI-style JOIN providing a inner join between two tables. |
static final int |
LEFT_OUTER_JOIN |
An ANSI-style JOIN providing a left outer join between two tables. |
static final int |
RIGHT_OUTER_JOIN |
An ANSI-style JOIN providing a right outer join between two tables. |
COMMIT_ON_ACCEPT_CHANGES
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
PUBLIC_XML_SCHEMA, SCHEMA_SYSTEM_ID
Modifier and Type | Method | Description |
---|---|---|
void |
addRowSet |
Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column indexes. |
void |
addRowSet |
Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column names. |
void |
addRowSet |
Adds the given RowSet object to this JoinRowSet object. |
void |
addRowSet |
Adds the given RowSet object to this JoinRowSet object and sets the designated column as the match column for the RowSet object. |
void |
addRowSet |
Adds rowset to this JoinRowSet object and sets the designated column as the match column. |
int |
getJoinType() |
Returns a int describing the set SQL JOIN type governing this JoinRowSet instance. |
String[] |
getRowSetNames() |
Returns a String array containing the names of the RowSet objects added to this JoinRowSet object. |
Collection |
getRowSets() |
Returns a Collection object containing the RowSet objects that have been added to this JoinRowSet object. |
String |
getWhereClause() |
Return a SQL-like description of the WHERE clause being used in a JoinRowSet object. |
void |
setJoinType |
Allow the application to adjust the type of JOIN imposed on tables contained within the JoinRowSet object instance. |
boolean |
supportsCrossJoin() |
Indicates if CROSS_JOIN is supported by a JoinRowSet implementation |
boolean |
supportsFullJoin() |
Indicates if FULL_JOIN is supported by a JoinRowSet implementation |
boolean |
supportsInnerJoin() |
Indicates if INNER_JOIN is supported by a JoinRowSet implementation |
boolean |
supportsLeftOuterJoin() |
Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet implementation |
boolean |
supportsRightOuterJoin() |
Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet implementation |
CachedRowSet |
toCachedRowSet() |
Creates a new CachedRowSet object containing the data in this JoinRowSet object, which can be saved to a data source using the SyncProvider object for the CachedRowSet object. |
acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setUrl, setURL, setUsername
readXml, readXml, writeXml, writeXml, writeXml, writeXml
isWrapperFor, unwrap
static final int CROSS_JOIN
JOIN
providing a cross product of two tablesstatic final int INNER_JOIN
JOIN
providing a inner join between two tables. Any unmatched rows in either table of the join should be discarded.static final int LEFT_OUTER_JOIN
JOIN
providing a left outer join between two tables. In SQL, this is described where all records should be returned from the left side of the JOIN statement.static final int RIGHT_OUTER_JOIN
JOIN
providing a right outer join between two tables. In SQL, this is described where all records from the table on the right side of the JOIN statement even if the table on the left has no matching record.static final int FULL_JOIN
JOIN
providing a full JOIN. Specifies that all rows from either table be returned regardless of matching records on the other table.void addRowSet(Joinable rowset) throws SQLException
RowSet
object to this JoinRowSet
object. If the RowSet
object is the first to be added to this JoinRowSet
object, it forms the basis of the JOIN
relationship to be established. This method should be used only when the given RowSet
object already has a match column that was set with the Joinable
method setMatchColumn
.
Note: A Joinable
object is any RowSet
object that has implemented the Joinable
interface.
rowset
- the RowSet
object that is to be added to this JoinRowSet
object; it must implement the Joinable
interface and have a match column setSQLException
- if (1) an empty rowset is added to the to this JoinRowSet
object, (2) a match column has not been set for rowset, or (3) rowset violates the active JOIN
void addRowSet(RowSet rowset, int columnIdx) throws SQLException
RowSet
object to this JoinRowSet
object and sets the designated column as the match column for the RowSet
object. If the RowSet
object is the first to be added to this JoinRowSet
object, it forms the basis of the JOIN
relationship to be established. This method should be used when RowSet does not already have a match column set.
rowset
- the RowSet
object that is to be added to this JoinRowSet
object; it may implement the Joinable
interfacecolumnIdx
- an int
that identifies the column to become the match columnSQLException
- if (1) rowset is an empty rowset or (2) rowset violates the active JOIN
void addRowSet(RowSet rowset, String columnName) throws SQLException
JoinRowSet
object and sets the designated column as the match column. If rowset is the first to be added to this JoinRowSet
object, it forms the basis for the JOIN
relationship to be established. This method should be used when the given RowSet
object does not already have a match column.
rowset
- the RowSet
object that is to be added to this JoinRowSet
object; it may implement the Joinable
interfacecolumnName
- the String
object giving the name of the column to be set as the match columnSQLException
- if (1) rowset is an empty rowset or (2) the match column for rowset does not satisfy the conditions of the JOIN
void addRowSet(RowSet[] rowset, int[] columnIdx) throws SQLException
RowSet
objects contained in the given array of RowSet
objects to this JoinRowSet
object and sets the match column for each of the RowSet
objects to the match columns in the given array of column indexes. The first element in columnIdx is set as the match column for the first RowSet
object in rowset, the second element of columnIdx is set as the match column for the second element in rowset, and so on. The first RowSet
object added to this JoinRowSet
object forms the basis for the JOIN
relationship.
This method should be used when the given RowSet
object does not already have a match column.
rowset
- an array of one or more RowSet
objects to be added to the JOIN
; it may implement the Joinable
interfacecolumnIdx
- an array of int
values indicating the index(es) of the columns to be set as the match columns for the RowSet
objects in rowset
SQLException
- if (1) an empty rowset is added to this JoinRowSet
object, (2) a match column is not set for a RowSet
object in rowset, or (3) a RowSet
object being added violates the active JOIN
void addRowSet(RowSet[] rowset, String[] columnName) throws SQLException
RowSet
objects contained in the given array of RowSet
objects to this JoinRowSet
object and sets the match column for each of the RowSet
objects to the match columns in the given array of column names. The first element in columnName is set as the match column for the first RowSet
object in rowset, the second element of columnName is set as the match column for the second element in rowset, and so on. The first RowSet
object added to this JoinRowSet
object forms the basis for the JOIN
relationship.
This method should be used when the given RowSet
object(s) does not already have a match column.
rowset
- an array of one or more RowSet
objects to be added to the JOIN
; it may implement the Joinable
interfacecolumnName
- an array of String
values indicating the names of the columns to be set as the match columns for the RowSet
objects in rowset
SQLException
- if (1) an empty rowset is added to this JoinRowSet
object, (2) a match column is not set for a RowSet
object in rowset, or (3) a RowSet
object being added violates the active JOIN
Collection<?> getRowSets() throws SQLException
Collection
object containing the RowSet
objects that have been added to this JoinRowSet
object. This should return the 'n' number of RowSet contained within the JOIN
and maintain any updates that have occurred while in this union.Collection
object consisting of the RowSet
objects added to this JoinRowSet
objectSQLException
- if an error occurs generating the Collection
object to be returnedString[] getRowSetNames() throws SQLException
String
array containing the names of the RowSet
objects added to this JoinRowSet
object.String
array of the names of the RowSet
objects in this JoinRowSet
objectSQLException
- if an error occurs retrieving the names of the RowSet
objectsCachedRowSet toCachedRowSet() throws SQLException
CachedRowSet
object containing the data in this JoinRowSet
object, which can be saved to a data source using the SyncProvider
object for the CachedRowSet
object. If any updates or modifications have been applied to the JoinRowSet the CachedRowSet returned by the method will not be able to persist it's changes back to the originating rows and tables in the in the datasource. The CachedRowSet instance returned should not contain modification data and it should clear all properties of it's originating SQL statement. An application should reset the SQL statement using the RowSet.setCommand
method.
In order to allow changes to be persisted back to the datasource to the originating tables, the acceptChanges
method should be used and called on a JoinRowSet object instance. Implementations can leverage the internal data and update tracking in their implementations to interact with the SyncProvider to persist any changes.
SQLException
- if an error occurs assembling the CachedRowSet objectboolean supportsCrossJoin()
boolean supportsInnerJoin()
boolean supportsLeftOuterJoin()
boolean supportsRightOuterJoin()
boolean supportsFullJoin()
void setJoinType(int joinType) throws SQLException
JOIN
imposed on tables contained within the JoinRowSet object instance. Implementations should throw a SQLException if they do not support a given JOIN
type.joinType
- the standard JoinRowSet.XXX static field definition of a SQL JOIN
to re-configure a JoinRowSet instance on the fly.SQLException
- if an unsupported JOIN
type is setString getWhereClause() throws SQLException
JOIN
by supplying a SQL strings description of JOIN
or provide a textual description to assist applications using a JoinRowSet
SQLException
- if an error occurs in generating a representation of the WHERE clause.int getJoinType() throws SQLException
int
describing the set SQL JOIN
type governing this JoinRowSet instance. The returned type will be one of standard JoinRowSet types: CROSS_JOIN
, INNER_JOIN
, LEFT_OUTER_JOIN
, RIGHT_OUTER_JOIN
or FULL_JOIN
.JOIN
. JoinRowSet.INNER_JOIN
is returned as the default JOIN
type is no type has been explicitly set.SQLException
- if an error occurs determining the SQL JOIN
type supported by the JoinRowSet instance.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.sql.rowset/javax/sql/rowset/JoinRowSet.html