/*
* Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sql.rowset;
import javax.sql.*;
import java.sql.*;
The standard interface that provides the framework for all
FilteredRowSet objects to describe their filters.
1.0 Background
The 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.
2.0 Implementation Guidelines
In order to supply a predicate for the 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:
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
/**
* The standard interface that provides the framework for all
* <code>FilteredRowSet</code> objects to describe their filters.
*
* <h3>1.0 Background</h3>
* The <code>Predicate</code> interface is a standard interface that
* applications can implement to define the filter they wish to apply to a
* a <code>FilteredRowSet</code> object. A <code>FilteredRowSet</code>
* object consumes implementations of this interface and enforces the
* constraints defined in the implementation of the method <code>evaluate</code>.
* A <code>FilteredRowSet</code> 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.
*
* <h3>2.0 Implementation Guidelines</h3>
* In order to supply a predicate for the <code>FilteredRowSet</code>.
* 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 <code>FilteredRowSet</code> interface, this allows for a flexible
* and application motivated implementations of <code>Predicate</code> to emerge.
* <p>
* A sample implementation would look something like this:
* <pre>{@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;
* }
* }
* }</pre>
* <P>
* The example above implements a simple range predicate. Note, that
* implementations should but are not required to provide <code>String</code>
* 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
*
*/
// <h3>3.0 FilteredRowSet Internals</h3>
// internalNext, First, Last. Discuss guidelines on how to approach this
// and cite examples in reference implementations.
public interface Predicate {
This method is typically called a 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.
Params: - rs – The
RowSet to be evaluated
Returns: true if there are more rows in the filter;
false otherwise
/**
* This method is typically called a <code>FilteredRowSet</code> object
* internal methods (not public) that control the <code>RowSet</code> 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 <code>true</code> if there are more rows in the filter;
* <code>false</code> 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.
Params: - value – An
Object value which needs to be checked,
whether it can be part of this FilterRowSet object. - 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
Throws: - SQLException – if the column is not part of filtering criteria
Returns: true if row value lies within the filter;
false otherwise
/**
* This method is called by a <code>FilteredRowSet</code> object
* to check whether the value lies between the filtering criterion (or criteria
* if multiple constraints exist) set using the <code>setFilter()</code> method.
* <P>
* The <code>FilteredRowSet</code> object will use this method internally
* while inserting new rows to a <code>FilteredRowSet</code> instance.
*
* @param value An <code>Object</code> value which needs to be checked,
* whether it can be part of this <code>FilterRowSet</code> object.
* @param column a <code>int</code> object that must match the
* SQL index of a column in this <code>RowSet</code> object. This must
* have been passed to <code>Predicate</code> as one of the columns
* for filtering while initializing a <code>Predicate</code>
* @return <code>true</code> if row value lies within the filter;
* <code>false</code> 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.
Params: - value – An
Object value which needs to be checked,
whether it can be part of this FilterRowSet. - 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
Throws: - SQLException – if the column is not part of filtering criteria
Returns: true if value lies within the filter; false otherwise
/**
* This method is called by the <code>FilteredRowSet</code> object
* to check whether the value lies between the filtering criteria set
* using the setFilter method.
* <P>
* The <code>FilteredRowSet</code> object will use this method internally
* while inserting new rows to a <code>FilteredRowSet</code> instance.
*
* @param value An <code>Object</code> value which needs to be checked,
* whether it can be part of this <code>FilterRowSet</code>.
*
* @param columnName a <code>String</code> object that must match the
* SQL name of a column in this <code>RowSet</code>, ignoring case. This must
* have been passed to <code>Predicate</code> as one of the columns for filtering
* while initializing a <code>Predicate</code>
*
* @return <code>true</code> if value lies within the filter; <code>false</code> otherwise
*
* @throws SQLException if the column is not part of filtering criteria
*/
public boolean evaluate(Object value, String columnName) throws SQLException;
}