1/* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.sql.rowset; 27 28import java.sql.*; 29import javax.sql.*; 30import javax.naming.*; 31import java.io.*; 32import java.math.*; 33 34/** 35 * The standard interface that all standard implementations of 36 * <code>FilteredRowSet</code> must implement. The <code>FilteredRowSetImpl</code> class 37 * provides the reference implementation which may be extended if required. 38 * Alternatively, a vendor is free to implement its own version 39 * by implementing this interface. 40 * 41 * <h3>1.0 Background</h3> 42 * 43 * There are occasions when a <code>RowSet</code> object has a need to provide a degree 44 * of filtering to its contents. One possible solution is to provide 45 * a query language for all standard <code>RowSet</code> implementations; however, 46 * this is an impractical approach for lightweight components such as disconnected 47 * <code>RowSet</code> 48 * objects. The <code>FilteredRowSet</code> interface seeks to address this need 49 * without supplying a heavyweight query language along with the processing that 50 * such a query language would require. 51 * <p> 52 * A JDBC <code>FilteredRowSet</code> standard implementation implements the 53 * <code>RowSet</code> interfaces and extends the 54 * <code>CachedRowSet</code>™ class. The 55 * <code>CachedRowSet</code> class provides a set of protected cursor manipulation 56 * methods, which a <code>FilteredRowSet</code> implementation can override 57 * to supply filtering support. 58 * 59 * <h3>2.0 Predicate Sharing</h3> 60 * 61 * If a <code>FilteredRowSet</code> implementation is shared using the 62 * inherited <code>createShared</code> method in parent interfaces, the 63 * <code>Predicate</code> should be shared without modification by all 64 * <code>FilteredRowSet</code> instance clones. 65 * 66 * <h3>3.0 Usage</h3> 67 * <p> 68 * By implementing a <code>Predicate</code> (see example in <a href="Predicate.html">Predicate</a> 69 * class JavaDoc), a <code>FilteredRowSet</code> could then be used as described 70 * below. 71 * 72 * <pre> 73 * {@code 74 * FilteredRowSet frs = new FilteredRowSetImpl(); 75 * frs.populate(rs); 76 * 77 * Range name = new Range("Alpha", "Bravo", "columnName"); 78 * frs.setFilter(name); 79 * 80 * frs.next() // only names from "Alpha" to "Bravo" will be returned 81 * } 82 * </pre> 83 * In the example above, we initialize a <code>Range</code> object which 84 * implements the <code>Predicate</code> interface. This object expresses 85 * the following constraints: All rows outputted or modified from this 86 * <code>FilteredRowSet</code> object must fall between the values 'Alpha' and 87 * 'Bravo' both values inclusive, in the column 'columnName'. If a filter is 88 * applied to a <code>FilteredRowSet</code> object that contains no data that 89 * falls within the range of the filter, no rows are returned. 90 * <p> 91 * This framework allows multiple classes implementing predicates to be 92 * used in combination to achieved the required filtering result with 93 * out the need for query language processing. 94 * 95 * <h3>4.0 Updating a <code>FilteredRowSet</code> Object</h3> 96 * The predicate set on a <code>FilteredRowSet</code> object 97 * applies a criterion on all rows in a 98 * <code>RowSet</code> object to manage a subset of rows in a <code>RowSet</code> 99 * object. This criterion governs the subset of rows that are visible and also 100 * defines which rows can be modified, deleted or inserted. 101 * <p> 102 * Therefore, the predicate set on a <code>FilteredRowSet</code> object must be 103 * considered as bi-directional and the set criterion as the gating mechanism 104 * for all views and updates to the <code>FilteredRowSet</code> object. Any attempt 105 * to update the <code>FilteredRowSet</code> that violates the criterion will 106 * result in a <code>SQLException</code> object being thrown. 107 * <p> 108 * The <code>FilteredRowSet</code> range criterion can be modified by applying 109 * a new <code>Predicate</code> object to the <code>FilteredRowSet</code> 110 * instance at any time. This is possible if no additional references to the 111 * <code>FilteredRowSet</code> object are detected. A new filter has an 112 * immediate effect on criterion enforcement within the 113 * <code>FilteredRowSet</code> object, and all subsequent views and updates will be 114 * subject to similar enforcement. 115 * 116 * <h3>5.0 Behavior of Rows Outside the Filter</h3> 117 * Rows that fall outside of the filter set on a <code>FilteredRowSet</code> 118 * object cannot be modified until the filter is removed or a 119 * new filter is applied. 120 * <p> 121 * Furthermore, only rows that fall within the bounds of a filter will be 122 * synchronized with the data source. 123 * 124 * @author Jonathan Bruce 125 * @since 1.5 126 */ 127 128public interface FilteredRowSet extends WebRowSet { 129 130 /** 131 * Applies the given <code>Predicate</code> object to this 132 * <code>FilteredRowSet</code> 133 * object. The filter applies controls both to inbound and outbound views, 134 * constraining which rows are visible and which 135 * rows can be manipulated. 136 * <p> 137 * A new <code>Predicate</code> object may be set at any time. This has the 138 * effect of changing constraints on the <code>RowSet</code> object's data. 139 * In addition, modifying the filter at runtime presents issues whereby 140 * multiple components may be operating on one <code>FilteredRowSet</code> object. 141 * Application developers must take responsibility for managing multiple handles 142 * to <code>FilteredRowSet</code> objects when their underling <code>Predicate</code> 143 * objects change. 144 * 145 * @param p a <code>Predicate</code> object defining the filter for this 146 * <code>FilteredRowSet</code> object. Setting a <b>null</b> value 147 * will clear the predicate, allowing all rows to become visible. 148 * 149 * @throws SQLException if an error occurs when setting the 150 * <code>Predicate</code> object 151 */ 152 public void setFilter(Predicate p) throws SQLException; 153 154 /** 155 * Retrieves the active filter for this <code>FilteredRowSet</code> object. 156 * 157 * @return p the <code>Predicate</code> for this <code>FilteredRowSet</code> 158 * object; <code>null</code> if no filter has been set. 159 */ 160 public Predicate getFilter() ; 161} 162