KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sql > rowset > Predicate


1 /*
2  * @(#)Predicate.java 1.5 04/03/11
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sql.rowset;
9
10 import javax.sql.*;
11 import java.sql.*;
12
13 /**
14  * The standard interface that provides the framework for all
15  * <code>FilteredRowSet</code> objects to describe their filters.
16  * <p>
17  * <h3>1.0 Background</h3>
18  * The <code>Predicate</code> interface is a standard interface that
19  * applications can implement to define the filter they wish to apply to a
20  * a <code>FilteredRowSet</code> object. A <code>FilteredRowSet</code>
21  * object consumes implementations of this interface and enforces the
22  * constraints defined in the implementation of the method <code>evaluate</code>.
23  * A <code>FilteredRowSet</code> object enforces the filter constraints in a
24  * bi-directional manner: It outputs only rows that are within
25  * the constraints of the filter; and conversely, it inserts, modifies, or updates
26  * only rows that are within the constraints of the filter.
27  *
28  * <h3>2.0 Implementation Guidelines</h3>
29  * In order to supply a predicate for the <code>FilteredRowSet</code>.
30  * this interface must be implemented. At this time, the JDBC RowSet
31  * Implementations (JSR-114) does not specify any standard filters definitions.
32  * By specifying a standard means and mechanism for a range of filters to be
33  * defined and deployed with both the reference and vendor implementations
34  * of the <code>FilteredRowSet</code> interface, this allows for a flexible
35  * and application motivated implementations of <code>Predicate</code> to emerge.
36  * <p>
37  * A sample implementation would look something like this:
38  * <pre>
39  * <code>
40  * public class Range implements Predicate {
41  *
42  * private Object lo[];
43  * private Object hi[];
44  * private int idx[];
45  *
46  * public Range(Object[] lo, Object[] hi, int[] idx) {
47  * this.lo = lo;
48  * this.hi = hi;
49  * this.idx = idx;
50  * }
51  *
52  * public boolean evaluate(RowSet rs) {
53  * CachedRowSet crs = (CachedRowSet)rs;
54  * boolean bool1,bool2;
55  *
56  * // Check the present row determine if it lies
57  * // within the filtering criteria.
58  *
59  * for (int i = 0; i < idx.length; i++) {
60  *
61  * if ((rs.getObject(idx[i]) >= lo[i]) &&
62  * (rs.getObject(idx[i]) >= hi[i]) {
63  * bool1 = true; // within filter constraints
64  * } else {
65  * bool2 = true; // outside of filter constraints
66  * }
67  * }
68  *
69  * if (bool2) {
70  * return false;
71  * } else {
72  * return true;
73  * }
74  * }
75  * </code>
76  * </pre>
77  * <P>
78  * The example above implements a simple range predicate. Note, that
79  * implementations should but are not required to provider <code>String</code>
80  * and integer index based constructors to provide for JDBC RowSet Implementation
81  * applications that use both column identification conventions.
82  *
83  * @author Jonathan Bruce, Amit Handa
84  *
85  */
86
87  // <h3>3.0 FilteredRowSet Internals</h3>
88 // internalNext, Frist, Last. Discuss guidelines on how to approach this
89 // and cite examples in reference implementations.
90 public interface Predicate {
91     /**
92      * This method is typically called a <code>FilteredRowSet</code> object
93      * internal methods (not public) that control the <code>RowSet</code> object's
94      * cursor moving from row to the next. In addition, if this internal method
95      * moves the cursor onto a row that has been deleted, the internal method will
96      * continue to ove the cursor until a valid row is found.
97      *
98      * @return <code>true</code> if there are more rows in the filter;
99      * <code>false</code> otherwise
100      */
101     public boolean evaluate(RowSet rs);
102     
103     
104     /**
105      * This method is called by a <code>FilteredRowSet</code> object
106      * to check whether the value lies between the filtering criterion (or criteria
107      * if multiple constraints exist) set using the <code>setFilter()</code> method.
108      * <P>
109      * The <code>FilteredRowSet</code> object will use this method internally
110      * while inserting new rows to a <code>FilteredRowSet</code> instance.
111      *
112      * @param value An <code>Object</code> value which needs to be checked,
113      * whether it can be part of this <code>FilterRowSet</code> object.
114      * @param column a <code>int</code> object that must match the
115      * SQL index of a column in this <code>RowSet</code> object. This must
116      * have been passed to <code>Predicate</code> as one of the columns
117      * for filtering while initializing a <code>Predicate</code>
118      * @return <code>true</code> ifrow value lies within the filter;
119      * <code>false</code> otherwise
120      * @throws SQLException if the column is not part of filtering criteria
121      */
122     public boolean evaluate(Object JavaDoc value, int column) throws SQLException;
123
124     /**
125      * This method is called by the <code>FilteredRowSet</code> object
126      * to check whether the value lies between the filtering criteria set
127      * using the setFilter method.
128      * <P>
129      * The <code>FilteredRowSet</code> object will use this method internally
130      * while inserting new rows to a <code>FilteredRowSet</code> instance.
131      *
132      * @param value An <code>Object</code> value which needs to be checked,
133      * whether it can be part of this <code>FilterRowSet</code>.
134      *
135      * @param columnName a <code>String</code> object that must match the
136      * SQL name of a column in this <code>RowSet</code>, ignoring case. This must
137      * have been passed to <code>Predicate</code> as one of the columns for filtering
138      * while initializing a <code>Predicate</code>
139      *
140      * @return <code>true</code> if value lies within the filter; <code>false</code> otherwise
141      *
142      * @throws SQLException if the column is not part of filtering criteria
143      */
144     public boolean evaluate(Object JavaDoc value, String JavaDoc columnName) throws SQLException;
145     
146 }
147
Popular Tags