Package javax.sql.rowset
RowSet
implementations. This package contains interfaces and classes
that a standard RowSet
implementation either implements or extends.
Table of Contents
- 1.0 Package Specification
- 2.0 Standard RowSet Definitions
- 3.0 Implementer's Guide
- 4.0 Related Specifications
- 5.0 Related Documentation
1.0 Package Specification
This package specifies five standard JDBCRowSet
interfaces.
All five extend the
RowSet interface described in the JDBC 3.0
specification. It is anticipated that additional definitions
of more specialized JDBC RowSet
types will emerge as this technology
matures. Future definitions should be specified as subinterfaces using
inheritance similar to the way it is used in this specification.
Note: The interface definitions provided in this package form the basis for
all compliant JDBC RowSet
implementations. Vendors and more advanced
developers who intend to provide their own compliant RowSet
implementations
should pay particular attention to the assertions detailed in specification
interfaces.
2.0 Standard RowSet Definitions
JdbcRowSet
- A wrapper around aResultSet
object that makes it possible to use the result set as a JavaBeans component. Thus, aJdbcRowSet
object can be a Bean that any tool makes available for assembling an application as part of a component based architecture. AJdbcRowSet
object is a connectedRowSet
object, that is, it must continually maintain its connection to its data source using a JDBC technology-enabled driver ("JDBC driver"). In addition, aJdbcRowSet
object provides a fully updatable and scrollable tabular data structure as defined in the JDBC 3.0 specification.-
CachedRowSet
- ACachedRowSet
object is a JavaBeans component that is scrollable, updatable, serializable, and generally disconnected from the source of its data. ACachedRowSet
object typically contains rows from a result set, but it can also contain rows from any file with a tabular format, such as a spreadsheet.CachedRowSet
implementations must use theSyncFactory
to manage and obtain pluggableSyncProvider
objects to provide synchronization between the disconnectedRowSet
object and the originating data source. Typically aSyncProvider
implementation relies upon a JDBC driver to obtain connectivity to a particular data source. Further details on this mechanism are discussed in thejavax.sql.rowset.spi
package specification. WebRowSet
- AWebRowSet
object is an extension ofCachedRowSet
that can read and write aRowSet
object in a well formed XML format. This class calls anXmlReader
object (an extension of theRowSetReader
interface) to read a rowset in XML format. It calls anXmlWriter
object (an extension of theRowSetWriter
interface) to write a rowset in XML format. The reader and writer required byWebRowSet
objects are provided by theSyncFactory
in the form ofSyncProvider
implementations. In order to ensure well formed XML usage, a standard generic XML Schema is defined and published athttp://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd
.FilteredRowSet
- AFilteredRowSet
object provides filtering functionality in a programmatic and extensible way. There are many instances when aRowSet
object
has a need to provide filtering in its contents without sacrificing the disconnected environment, thus saving the expense of having to create a connection to the data source. Solutions to this need vary from providing heavyweight full scale SQL query abilities, to portable components, to more lightweight approaches. AFilteredRowSet
object consumes an implementation of thePredicate
interface, which may define a filter at run time. In turn, aFilteredRowSet
object is tasked with enforcing the set filter for both inbound and outbound read and write operations. That is, all filters can be considered as bi-directional. No standard filters are defined; however, sufficient mechanics are specified to permit any required filter to be implemented.JoinRowSet
- TheJoinRowSet
interface describes a mechanism by which relationships can be established between two or more standardRowSet
implementations. Any number ofRowSet
objects can be added to aJoinRowSet
object provided theRowSet
objects can be related in a SQLJOIN
like fashion. By definition, the SQLJOIN
statement is used to combine the data contained in two (or more) relational database tables based upon a common attribute. By establishing and then enforcing column matches, aJoinRowSet
object establishes relationships betweenRowSet
instances without the need to touch the originating data source.
3.0 Implementer's Guide
Compliant implementations of JDBCRowSet
Implementations
must follow the assertions described in this specification. In accordance
with the terms of the Java Community Process, a
Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
specification. The following paragraphs outline a number of starting points for
implementers of the standard JDBC RowSet
definitions. Implementers
should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines
on SyncProvider
implementations.
- 3.1 Constructor
All
RowSet
implementations must provide a no-argument constructor. - 3.2 Role of the
BaseRowSet
ClassA compliant JDBC
RowSet
implementation must implement one or more standard interfaces specified in this package and may extend theBaseRowSet
abstract class. For example, aCachedRowSet
implementation must implement theCachedRowSet
interface and extend theBaseRowSet
abstract class. TheBaseRowSet
class provides the standard architecture on which allRowSet
implementations should be built, regardless of whether theRowSet
objects exist in a connected or disconnected environment. TheBaseRowSet
abstract class provides anyRowSet
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 thecom.sun.rowset
package) use theBaseRowSet
class as a basis for their implementations.The following table illustrates the features that the
BaseRowSet
abstract class provides.Features in BaseRowSet
Feature Details Properties Provides standard JavaBeans property manipulation mechanisms to allow applications to get and set RowSet
command and property values. Refer to the documentation of thejavax.sql.RowSet
interface (available in the JDBC 3.0 specification) for more details on the standardRowSet
properties.Event notification Provides standard JavaBeans event notifications to registered event listeners. Refer to the documentation of 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. - 3.3 Connected RowSet Requirements
The
JdbcRowSet
describes aRowSet
object that must always be connected to the originating data source. Implementations of theJdbcRowSet
should ensure that this connection is provided solely by a JDBC driver. Furthermore,RowSet
objects that are implementations of theJdbcRowSet
interface and are therefore operating in a connected environment do not use theSyncFactory
to obtain aRowSetReader
object or aRowSetWriter
object. They can safely rely on the JDBC driver to supply their needs by virtue of the presence of an underlying updatable and scrollableResultSet
implementation. -
3.4 Disconnected RowSet Requirements
A disconnected
RowSet
object, such as aCachedRowSet
object, should delegate connection management to aSyncProvider
object provided by theSyncFactory
. To ensure fully disconnected semantics, all disconnectedRowSet
objects must ensure that the original connection made to the data source to populate theRowSet
object is closed to permit the garbage collector to recover and release resources. TheSyncProvider
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 disconnectedRowSet
object should therefore ensure that no extraneous references remain on theConnection
object. - 3.5 Role of RowSetMetaDataImpl
The
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 disconnectedRowSet
objects. All implementations are free to use this standard implementation but are not required to do so. - 3.6 RowSetWarning Class
The
RowSetWarning
class provides warnings that can be set onRowSet
implementations. Similar to SQLWarning objects,RowSetWarning
objects are silently chained to the object whose method caused the warning to be thrown. AllRowSet
implementations should ensure that this chaining occurs if a warning is generated and also ensure that the warnings are available via thegetRowSetWarnings
method defined in either theJdbcRowSet
interface or theCachedRowSet
interface. After a warning has been retrieved with one of thegetRowSetWarnings
methods, theRowSetWarning
methodgetNextWarning
can be called on it to retrieve any warnings that might be chained on it. If a warning is returned,getNextWarning
can be called on it, and so on until there are no more warnings. - 3.7 The Joinable Interface
The
Joinable
interface provides both connected and disconnectedRowSet
objects with the capability to be added to aJoinRowSet
object in an SQLJOIN
operation. ARowSet
object that has implemented theJoinable
interface can set a match column, retrieve a match column, or unset a match column. AJoinRowSet
object can then use theRowSet
object's match column as a basis for adding theRowSet
object. - 3.8 The RowSetFactory Interface
A
RowSetFactory
implementation must be provided.
4.0 Related Specifications
5.0 Related Documentation
-
Interface Summary Interface Description CachedRowSet The interface that all standard implementations ofCachedRowSet
must implement.FilteredRowSet The standard interface that all standard implementations ofFilteredRowSet
must implement.JdbcRowSet The standard interface that all standard implementations ofJdbcRowSet
must implement.Joinable 1.0 BackgroundJoinRowSet TheJoinRowSet
interface provides a mechanism for combining related data from differentRowSet
objects into oneJoinRowSet
object, which represents an SQLJOIN
.Predicate The standard interface that provides the framework for allFilteredRowSet
objects to describe their filters.RowSetFactory An interface that defines the implementation of a factory that is used to obtain different types ofRowSet
implementations.WebRowSet The standard interface that all implementations of aWebRowSet
must implement. -
Class Summary Class Description BaseRowSet An abstract class providing aRowSet
object with its basic functionality.RowSetMetaDataImpl Provides implementations for the methods that set and get metadata information about aRowSet
object's columns.RowSetProvider A factory API that enables applications to obtain aRowSetFactory
implementation that can be used to create different types ofRowSet
implementations. -
Exception Summary Exception Description RowSetWarning An extension ofSQLException
that provides information about database warnings set onRowSet
objects.