KickJava   Java API By Example, From Geeks To Geeks.

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


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 JavaDoc {
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 JavaDoc 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 JavaDoc getFilter() ;
142 }
143
144
Popular Tags