FilteredRowSet objects to describe their filters.
*
* Predicate interface is a standard interface that
* applications can implement to define the filter they wish to apply to a
* a FilteredRowSet object. A FilteredRowSet
* object consumes implementations of this interface and enforces the
* constraints defined in the implementation of the method evaluate.
* A FilteredRowSet object enforces the filter constraints in a
* bi-directional manner: It outputs only rows that are within
* the constraints of the filter; and conversely, it inserts, modifies, or updates
* only rows that are within the constraints of the filter.
*
* FilteredRowSet.
* this interface must be implemented. At this time, the JDBC RowSet
* Implementations (JSR-114) does not specify any standard filters definitions.
* By specifying a standard means and mechanism for a range of filters to be
* defined and deployed with both the reference and vendor implementations
* of the FilteredRowSet interface, this allows for a flexible
* and application motivated implementations of Predicate to emerge.
* * A sample implementation would look something like this: *
{@code
* public class Range implements Predicate {
*
* private int[] lo;
* private int[] hi;
* private int[] idx;
*
* public Range(int[] lo, int[] hi, int[] idx) {
* this.lo = lo;
* this.hi = hi;
* this.idx = idx;
* }
*
* public boolean evaluate(RowSet rs) {
*
* // Check the present row determine if it lies
* // within the filtering criteria.
*
* for (int i = 0; i < idx.length; i++) {
* int value;
* try {
* value = (Integer) rs.getObject(idx[i]);
* } catch (SQLException ex) {
* Logger.getLogger(Range.class.getName()).log(Level.SEVERE, null, ex);
* return false;
* }
*
* if (value < lo[i] && value > hi[i]) {
* // outside of filter constraints
* return false;
* }
* }
* // Within filter constraints
* return true;
* }
* }
* }
*
* The example above implements a simple range predicate. Note, that
* implementations should but are not required to provide String
* and integer index based constructors to provide for JDBC RowSet Implementation
* applications that use both column identification conventions.
*
* @author Jonathan Bruce, Amit Handa
* @since 1.5
*
*/
//
FilteredRowSet object
* internal methods (not public) that control the RowSet object's
* cursor moving from row to the next. In addition, if this internal method
* moves the cursor onto a row that has been deleted, the internal method will
* continue to ove the cursor until a valid row is found.
* @param rs The {@code RowSet} to be evaluated
* @return true if there are more rows in the filter;
* false otherwise
*/
public boolean evaluate(RowSet rs);
/**
* This method is called by a FilteredRowSet object
* to check whether the value lies between the filtering criterion (or criteria
* if multiple constraints exist) set using the setFilter() method.
*
* The FilteredRowSet object will use this method internally
* while inserting new rows to a FilteredRowSet instance.
*
* @param value An Object value which needs to be checked,
* whether it can be part of this FilterRowSet object.
* @param column a int object that must match the
* SQL index of a column in this RowSet object. This must
* have been passed to Predicate as one of the columns
* for filtering while initializing a Predicate
* @return true if row value lies within the filter;
* false otherwise
* @throws SQLException if the column is not part of filtering criteria
*/
public boolean evaluate(Object value, int column) throws SQLException;
/**
* This method is called by the FilteredRowSet object
* to check whether the value lies between the filtering criteria set
* using the setFilter method.
*
* The FilteredRowSet object will use this method internally
* while inserting new rows to a FilteredRowSet instance.
*
* @param value An Object value which needs to be checked,
* whether it can be part of this FilterRowSet.
*
* @param columnName a String object that must match the
* SQL name of a column in this RowSet, ignoring case. This must
* have been passed to Predicate as one of the columns for filtering
* while initializing a Predicate
*
* @return true if value lies within the filter; false otherwise
*
* @throws SQLException if the column is not part of filtering criteria
*/
public boolean evaluate(Object value, String columnName) throws SQLException;
}