1 /* 2 * @(#)FilteredRowSet.java 1.7 04/05/29 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 java.sql.*; 11 import javax.sql.*; 12 import javax.naming.*; 13 import java.io.*; 14 import java.math.*; 15 16 /** 17 * The standard interface that all standard implementations of 18 * <code>FilteredRowSet</code> must implement. The <code>FilteredRowSetImpl</code> class 19 * provides the reference implementation which may be extended if required. 20 * Alternatively, a vendor is free to implement its own version 21 * by implementing this interface. 22 * 23 * <h3>1.0 Background</h3> 24 * 25 * There are occasions when a <code>RowSet</code> object has a need to provide a degree 26 * of filtering to its contents. One possible solution is to provide 27 * a query language for all standard <code>RowSet</code> implementations; however, 28 * this is an impractical approach for lightweight components such as disconnected 29 * <code>RowSet</code> 30 * objects. The <code>FilteredRowSet</code> interface seeks to address this need 31 * without supplying a heavyweight query language along with the processing that 32 * such a query language would require. 33 * <p> 34 * A JDBC <code>FilteredRowSet</code> standard implementation implements the 35 * <code>RowSet</code> interfaces and extends the 36 * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> class. The 37 * <code>CachedRowSet</code> class provides a set of protected cursor manipulation 38 * methods, which a <code>FilteredRowSet</code> implementation can override 39 * to supply filtering support. 40 * 41 * <h3>2.0 Predicate Sharing</h3> 42 * 43 * If a <code>FilteredRowSet</code> implementation is shared using the 44 * inherited <code>createShared</code> method in parent interfaces, the 45 * <code>Predicate</code> should be shared without modification by all 46 * <code>FilteredRowSet</code> instance clones. 47 * 48 * <h3>3.0 Usage</h3> 49 * <p> 50 * By implementing a <code>Predicate</code> (see example in <a HREF="Predicate.html">Predicate</a> 51 * class JavaDoc), a <code>FilteredRowSet</code> could then be used as described 52 * below. 53 * <P> 54 * <code> 55 * <pre> 56 * FilteredRowSet frs = new FilteredRowSetImpl(); 57 * frs.populate(rs); 58 * 59 * Range name = new Range("Alpha", "Bravo", "columnName"); 60 * frs.setFilter(name); 61 * 62 * frs.next() // only names from "Alpha" to "Bravo" will be returned 63 * </pre> 64 * </code> 65 * In the example above, we initialize a <code>Range</code> object which 66 * implements the <code>Predicate</code> interface. This object expresses 67 * the following constraints: All rows outputted or modified from this 68 * <code>FilteredRowSet</code> object must fall between the values 'Alpha' and 69 * 'Bravo' both values inclusive, in the column 'columnName'. If a filter is 70 * applied to a <code>FilteredRowSet</code> object that contains no data that 71 * falls within the range of the filter, no rows are returned. 72 * <p> 73 * This framework allows multiple classes implementing predicates to be 74 * used in combination to achieved the required filtering result with 75 * out the need for query language processing. 76 * <p> 77 * <h3>4.0 Updating a <code>FilteredRowSet</code> Object</h3> 78 * The predicate set on a <code>FilteredRowSet</code> object 79 * applies a criterion on all rows in a 80 * <code>RowSet</code> object to manage a subset of rows in a <code>RowSet</code> 81 * object. This criterion governs the subset of rows that are visible and also 82 * defines which rows can be modified, deleted or inserted. 83 * <p> 84 * Therefore, the predicate set on a <code>FilteredRowSet</code> object must be 85 * considered as bi-directional and the set criterion as the gating mechanism 86 * for all views and updates to the <code>FilteredRowSet</code> object. Any attempt 87 * to update the <code>FilteredRowSet</code> that violates the criterion will 88 * result in a <code>SQLException</code> object being thrown. 89 * <p> 90 * The <code>FilteredRowSet</code> range criterion can be modified by applying 91 * a new <code>Predicate</code> object to the <code>FilteredRowSet</code> 92 * instance at any time. This is possible if no additional references to the 93 * <code>FilteredRowSet</code> object are detected. A new filter has has an 94 * immediate effect on criterion enforcement within the 95 * <code>FilteredRowSet</code> object, and all subsequent views and updates will be 96 * subject to similar enforcement. 97 * <p> 98 * <h3>5.0 Behavior of Rows Outside the Filter</h3> 99 * Rows that fall outside of the filter set on a <code>FilteredRowSet</code> 100 * object cannot be modified until the filter is removed or a 101 * new filter is applied. 102 * <p> 103 * Furthermore, only rows that fall within the bounds of a filter will be 104 * synchronized with the data source. 105 * 106 * @author Jonathan Bruce 107 */ 108 109 public interface FilteredRowSet extends WebRowSet { 110 111 /** 112 * Applies the given <code>Predicate</code> object to this 113 * <code>FilteredRowSet</code> 114 * object. The filter applies controls both to inbound and outbound views, 115 * constraining which rows are visible and which 116 * rows can be manipulated. 117 * <p> 118 * A new <code>Predicate</code> object may be set at any time. This has the 119 * effect of changing constraints on the <code>RowSet</code> object's data. 120 * In addition, modifying the filter at runtime presents issues whereby 121 * multiple components may be operating on one <code>FilteredRowSet</code> object. 122 * Application developers must take responsibility for managing multiple handles 123 * to <code>FilteredRowSet</code> objects when their underling <code>Predicate</code> 124 * objects change. 125 * 126 * @param p a <code>Predicate</code> object defining the filter for this 127 * <code>FilteredRowSet</code> object. Setting a <b>null</b> value 128 * will clear the predicate, allowing all rows to become visible. 129 * 130 * @throws SQLException if an error occurs when setting the 131 * <code>Predicate</code> object 132 */ 133 public void setFilter(Predicate p) throws SQLException; 134 135 /** 136 * Retrieves the active filter for this <code>FilteredRowSet</code> object. 137 * 138 * @return p the <code>Predicate</code> for this <code>FilteredRowSet</code> 139 * object; <code>null</code> if no filter has been set. 140 */ 141 public Predicate getFilter() ; 142 } 143 144