/*
* Copyright (c) 2003, 2004, 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.
*
*
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: *
*
* public class Range implements Predicate {
*
* private Object lo[];
* private Object hi[];
* private int idx[];
*
* public Range(Object[] lo, Object[] hi, int[] idx) {
* this.lo = lo;
* this.hi = hi;
* this.idx = idx;
* }
*
* public boolean evaluate(RowSet rs) {
* CachedRowSet crs = (CachedRowSet)rs;
* boolean bool1,bool2;
*
* // Check the present row determine if it lies
* // within the filtering criteria.
*
* for (int i = 0; i < idx.length; i++) {
*
* if ((rs.getObject(idx[i]) >= lo[i]) &&
* (rs.getObject(idx[i]) >= hi[i]) {
* bool1 = true; // within filter constraints
* } else {
* bool2 = true; // outside of filter constraints
* }
* }
*
* if (bool2) {
* return false;
* } else {
* return true;
* }
* }
*
*
*
* The example above implements a simple range predicate. Note, that
* implementations should but are not required to provider String
* and integer index based constructors to provide for JDBC RowSet Implementation
* applications that use both column identification conventions.
*
* @author Jonathan Bruce, Amit Handa
*
*/
//
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.
*
* @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
ifrow 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;
}