Java example source code file (FilteredRowSet.java)

This example Java source code file (FilteredRowSet.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

filteredrowset, jdbc, math, naming, predicate, sql, sqlexception, webrowset

The FilteredRowSet.java Java example source code

/*
 * Copyright (c) 2003, 2013, 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 java.sql.*;
import javax.sql.*;
import javax.naming.*;
import java.io.*;
import java.math.*;

/**
 * The standard interface that all standard implementations of
 * <code>FilteredRowSet must implement. The FilteredRowSetImpl class
 * provides the reference implementation which may be extended if required.
 * Alternatively, a vendor is free to implement its own version
 * by implementing this interface.
 *
 * <h3>1.0 Background
 *
 * There are occasions when a <code>RowSet object has a need to provide a degree
 * of filtering to its contents. One possible solution is to provide
 * a query language for all standard <code>RowSet implementations; however,
 * this is an impractical approach for lightweight components such as disconnected
 * <code>RowSet
 * objects. The <code>FilteredRowSet interface seeks to address this need
 * without supplying a heavyweight query language along with the processing that
 * such a query language would require.
 * <p>
 * A JDBC <code>FilteredRowSet standard implementation implements the
 * <code>RowSet interfaces and extends the
 * <code>CachedRowSet™ class. The
 * <code>CachedRowSet class provides a set of protected cursor manipulation
 * methods, which a <code>FilteredRowSet implementation can override
 * to supply filtering support.
 *
 * <h3>2.0 Predicate Sharing
 *
 * If a <code>FilteredRowSet implementation is shared using the
 * inherited <code>createShared method in parent interfaces, the
 * <code>Predicate should be shared without modification by all
 * <code>FilteredRowSet instance clones.
 *
 * <h3>3.0 Usage
 * <p>
 * By implementing a <code>Predicate (see example in Predicate
 * class JavaDoc), a <code>FilteredRowSet could then be used as described
 * below.
 *
 * <pre>
 * {@code
 *     FilteredRowSet frs = new FilteredRowSetImpl();
 *     frs.populate(rs);
 *
 *     Range name = new Range("Alpha", "Bravo", "columnName");
 *     frs.setFilter(name);
 *
 *     frs.next() // only names from "Alpha" to "Bravo" will be returned
 * }
 * </pre>
 * In the example above, we initialize a <code>Range object which
 * implements the <code>Predicate interface. This object expresses
 * the following constraints: All rows outputted or modified from this
 * <code>FilteredRowSet object must fall between the values 'Alpha' and
 * 'Bravo' both values inclusive, in the column 'columnName'. If a filter is
 * applied to a <code>FilteredRowSet object that contains no data that
 * falls within the range of the filter, no rows are returned.
 * <p>
 * This framework allows multiple classes implementing predicates to be
 * used in combination to achieved the required filtering result with
 * out the need for query language processing.
 *
 * <h3>4.0 Updating a FilteredRowSet Object
 * The predicate set on a <code>FilteredRowSet object
 * applies a criterion on all rows in a
 * <code>RowSet object to manage a subset of rows in a RowSet
 * object. This criterion governs the subset of rows that are visible and also
 * defines which rows can be modified, deleted or inserted.
 * <p>
 * Therefore, the predicate set on a <code>FilteredRowSet object must be
 * considered as bi-directional and the set criterion as the gating mechanism
 * for all views and updates to the <code>FilteredRowSet object. Any attempt
 * to update the <code>FilteredRowSet that violates the criterion will
 * result in a <code>SQLException object being thrown.
 * <p>
 * The <code>FilteredRowSet range criterion can be modified by applying
 * a new <code>Predicate object to the FilteredRowSet
 * instance at any time. This is  possible if no additional references to the
 * <code>FilteredRowSet object are detected. A new filter has has an
 * immediate effect on criterion enforcement within the
 * <code>FilteredRowSet object, and all subsequent views and updates will be
 * subject to similar enforcement.
 *
 * <h3>5.0 Behavior of Rows Outside the Filter
 * Rows that fall outside of the filter set on a <code>FilteredRowSet
 * object cannot be modified until the filter is removed or a
 * new filter is applied.
 * <p>
 * Furthermore, only rows that fall within the bounds of a filter will be
 * synchronized with the data source.
 *
 * @author Jonathan Bruce
 */

public interface FilteredRowSet extends WebRowSet {

   /**
    * Applies the given <code>Predicate object to this
    * <code>FilteredRowSet
    * object. The filter applies controls both to inbound and outbound views,
    * constraining which rows are visible and which
    * rows can be manipulated.
    * <p>
    * A new <code>Predicate object may be set at any time. This has the
    * effect of changing constraints on the <code>RowSet object's data.
    * In addition, modifying the filter at runtime presents issues whereby
    * multiple components may be operating on one <code>FilteredRowSet object.
    * Application developers must take responsibility for managing multiple handles
    * to <code>FilteredRowSet objects when their underling Predicate
    * objects change.
    *
    * @param p a <code>Predicate object defining the filter for this
    * <code>FilteredRowSet object. Setting a null value
    * will clear the predicate, allowing all rows to become visible.
    *
    * @throws SQLException if an error occurs when setting the
    *     <code>Predicate object
    */
    public void setFilter(Predicate p) throws SQLException;

   /**
    * Retrieves the active filter for this <code>FilteredRowSet object.
    *
    * @return p the <code>Predicate for this FilteredRowSet
    * object; <code>null if no filter has been set.
    */
    public Predicate getFilter() ;
}