javax.sql.rowset
Interface FilteredRowSet

All Superinterfaces:

CachedRowSet, Joinable, java.sql.ResultSet, javax.sql.RowSet, WebRowSet

All Known Implementing Classes:

FilteredRowSetImpl

public interface FilteredRowSet

extends WebRowSet

The standard interface that all standard implementations of FilteredRowSet must implement. The FilteredRowSetImpl class provides the reference implementation which may be extended if required. Alternatively, a vendor is free to implement its own version of by just implementing this interface.

1.0 Background

There are occasions when a RowSet object has a need to provide a degree of filtering to its contents. One possible solution is to provide a query language for all standard RowSet object implementations, however this is an impractical approach for light weight components such as RowSet object. The FilteredRowSet interface seeks to address this need without supplying a heavy weight query language along with the processing required.

A JDBC FilteredRowSet standard implementation implements the RowSet interfaces and extends the CachedRowSet^TM class. The CachedRowSet class provides a set of protected cursor manipulation methods, which a FilteredRowSet implementation can override to supply filtering support.

2.0 Predicate Sharing

If a FilteredRowSet implementation is shared using the inherited createShared method in parent interfaces, the Predicate should be shared without modification by all FilteredRowSet instance clones.

3.0 Usage

By implementing a Predicate (see example in Predicate class JavaDoc), a FilteredRowSet could then be used as described below.

     FilteredRowSet frs = new FilteredRowSet();
     frs.populate(rs);
 
     Range name = new Range("Alpha", "Bravo", "columnName");
     frs.setFilter(name);
 
     frs.next() // only names from "Alpha" to "Bravo" will be returned
 

In the example above, we initialize a Range object which implements the Predicate interface. This object expresses the following constraints: All rows outputted or modified from this FilteredRowSet must fall between the values 'Alpha' and 'Bravo' both values inclusive, in the column 'columnName'. If a filtered is applied to a FilteredRowSet object that contains out range criteria, no rows are returned.

This framework allows multiple classes implementing predicates to be used in combination to achieved the required filtering result with out the need for query language processing.

4.0 Updating FilteredRowSet

The predicate set on a FilteredRowSet applies a criteria on all rows in a RowSet object to manage a subset of a rows in a RowSet object. This criteria governs both the subset of rows that are visible but also defines the criteria in which rows can be modified, deleted or inserted.

Therefore, the predicate set on a FilteredRowSet must be considered as bi-directional and the set criteria as the gating mechanism for all views and updates to the FilteredRowSet. Any attempt to update the FilteredRowSet that violates the criteria will result in a SQLException being thrown.

The FilteredRowSet range criteria can be modified by applying a new Predicate object to the FilteredRowSet instance at any time. This is possible if no addition references to the FilteredRowSet object are detected. A new filter has has an immediate affect on criteria enforcement within the FilteredRowSet and all subsequent views and updates will be similarly enforced.

5.0 Behavior of Rows Outside the Filter

Rows that fall outside of the filter set on a FilteredRowSet object cannot be modified until such a time, as the filter is removed, or a new filter is applied.

Furthermore, only rows that fall within the bounds of a filter will be synchronized with the data source if an attempt is made to persist a FilteredRowSet object with a relational datastore using the SPI mechanism.

Author:

Jonathan Bruce

Field Summary

Fields inherited from interface javax.sql.rowset.WebRowSet

PUBLIC_XML_SCHEMA, SCHEMA_SYSTEM_ID

Fields inherited from interface javax.sql.rowset.CachedRowSet

COMMIT_ON_ACCEPT_CHANGES

Fields inherited from interface java.sql.ResultSet

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

Method Summary

Predicate	getFilter() Retrieve the active filter for this FilteredRowSet object.
void	setFilter(Predicate p) Apply Predicate object to a FilteredRowSet object.

Methods inherited from interface javax.sql.rowset.WebRowSet

readXml, readXml, writeXml, writeXml, writeXml, writeXml

Methods inherited from interface javax.sql.rowset.CachedRowSet

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

Methods inherited from interface javax.sql.RowSet

addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setBigDecimal, setBinaryStream, setBlob, setBoolean, setByte, setBytes, setCharacterStream, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDouble, setEscapeProcessing, setFloat, setInt, setLong, setMaxFieldSize, setMaxRows, setNull, setNull, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setShort, setString, setTime, setTime, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setUrl, setUsername

Methods inherited from interface java.sql.ResultSet

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, getInt, getInt, getLong, getLong, getMetaData, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getShort, getShort, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateShort, updateShort, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull

Methods inherited from interface javax.sql.rowset.Joinable

getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

Method Detail

setFilter

public void setFilter(Predicate p)
               throws java.sql.SQLException

Apply Predicate object to a FilteredRowSet object. The filter applies controls both to inbound and outbound views. That is; the filter constrains what rows are visible in addition to what rows can be manipulated.

A new Predicate object may be set at any time. This has the effect of changing constraints on the RowSet object data. In addition, modifying the filter at run-time presents issues where by multiple components may be operating on one FilteredRowSet. Application developers must take responsibility in managing multiple handles to FilteredRowSet objects when their underling Predicate objects change.

Parameters:

p - a Predicate object defining the filter for a FilteredRowSet implementation. Setting a null value will clear the predicate allowing all rows to become visible.

Throws:

java.sql.SQLException - if an error occurs when setting the Predicate object

getFilter

public Predicate getFilter()

Retrieve the active filter for this FilteredRowSet object.

Returns:

p the Predicate for this FilteredRowSet object; null if no filter has been set.