/* * Copyright (c) 2017, 2020, 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. */ /** * Standard interfaces and base classes for JDBC {@code RowSet} * implementations. This package contains interfaces and classes * that a standard {@code RowSet} implementation either implements or extends. * *
* Note: The interface definitions provided in this package form the basis for * all compliant JDBC {@code RowSet} implementations. Vendors and more advanced * developers who intend to provide their own compliant {@code RowSet} implementations * should pay particular attention to the assertions detailed in specification * interfaces. * *
* All {@code RowSet} implementations must provide a * no-argument constructor. *
* A compliant JDBC {@code RowSet} implementation must implement one or more * standard interfaces specified in this package and may extend the * {@code BaseRowSet} abstract class. For example, a * {@code CachedRowSet} implementation must implement the {@code CachedRowSet} * interface and extend the {@code BaseRowSet} abstract class. The * {@code BaseRowSet} class provides the standard architecture on which all * {@code RowSet} implementations should be built, regardless of whether the * {@code RowSet} objects exist in a connected or disconnected environment. * The {@code BaseRowSet} abstract class provides any {@code RowSet} implementation * with its base functionality, including property manipulation and event notification * that is fully compliant with * JavaBeans * component requirements. As an example, all implementations provided in the * reference implementations (contained in the {@code com.sun.rowset} package) use * the {@code BaseRowSet} class as a basis for their implementations. *
* The following table illustrates the features that the {@code BaseRowSet} * abstract class provides. *
** **
*Features in {@code BaseRowSet} * ** * * *Feature *Details ** *Properties *Provides standard JavaBeans property manipulation * mechanisms to allow applications to get and set {@code RowSet} command and * property values. Refer to the documentation of the {@code javax.sql.RowSet} * interface (available in the JDBC 3.0 specification) for more details on * the standard {@code RowSet} properties. ** *Event notification *Provides standard JavaBeans event notifications * to registered event listeners. Refer to the documentation of {@code javax.sql.RowSetEvent} * interface (available in the JDBC 3.0 specification) for * more details on how to register and handle standard RowSet events generated * by compliant implementations. ** *Setters for a RowSet object's command *Provides a complete set of setter methods * for setting RowSet command parameters. ** * *Streams *Provides fields for storing of stream instances * in addition to providing a set of constants for stream type designation. *
* The {@code JdbcRowSet} describes a {@code RowSet} object that must always * be connected to the originating data source. Implementations of the {@code JdbcRowSet} * should ensure that this connection is provided solely by a JDBC driver. * Furthermore, {@code RowSet} objects that are implementations of the * {@code JdbcRowSet} interface and are therefore operating in a connected environment * do not use the {@code SyncFactory} to obtain a {@code RowSetReader} object * or a {@code RowSetWriter} object. They can safely rely on the JDBC driver to * supply their needs by virtue of the presence of an underlying updatable and scrollable * {@code ResultSet} implementation. * *
* A disconnected {@code RowSet} object, such as a {@code CachedRowSet} object, * should delegate * connection management to a {@code SyncProvider} object provided by the * {@code SyncFactory}. To ensure fully disconnected semantics, all * disconnected {@code RowSet} objects must ensure * that the original connection made to the data source to populate the {@code RowSet} * object is closed to permit the garbage collector to recover and release resources. The * {@code SyncProvider} object ensures that the critical JDBC properties are * maintained in order to re-establish a connection to the data source when a * synchronization is required. A disconnected {@code RowSet} object should * therefore ensure that no * extraneous references remain on the {@code Connection} object. * *
* The {@code RowsetMetaDataImpl} class is a utility class that provides an implementation of the * RowSetMetaData interface, supplying standard setter * method implementations for metadata for both connected and disconnected * {@code RowSet} objects. All implementations are free to use this standard * implementation but are not required to do so. * *
* The {@code RowSetWarning} class provides warnings that can be set * on {@code RowSet} implementations. * Similar to SQLWarning objects, * {@code RowSetWarning} objects are silently chained to the object whose method * caused the warning to be thrown. All {@code RowSet} implementations should * ensure that this chaining occurs if a warning is generated and also ensure that the * warnings are available via the {@code getRowSetWarnings} method defined in either * the {@code JdbcRowSet} interface or the {@code CachedRowSet} interface. * After a warning has been retrieved with one of the * {@code getRowSetWarnings} methods, the {@code RowSetWarning} method * {@code getNextWarning} can be called on it to retrieve any warnings that might * be chained on it. If a warning is returned, {@code getNextWarning} can be called * on it, and so on until there are no more warnings. * *
* The {@code Joinable} interface provides both connected and disconnected * {@code RowSet} objects with the capability to be added to a * {@code JoinRowSet} object in an SQL {@code JOIN} operation. * A {@code RowSet} object that has implemented the {@code Joinable} * interface can set a match column, retrieve a match column, or unset a match column. * A {@code JoinRowSet} object can then use the {@code RowSet} object's * match column as a basis for adding the {@code RowSet} object. *
* A {@code RowSetFactory} implementation must * be provided. *