RowSetimplementations. This package contains interfaces and classes that a standard
RowSetimplementation 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
RowSetinterfaces. All five extend the RowSet interface described in the JDBC 3.0 specification. It is anticipated that additional definitions of more specialized JDBC
RowSettypes 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.
JdbcRowSet- A wrapper around a
ResultSetobject that makes it possible to use the result set as a JavaBeans™ component. Thus, a
JdbcRowSetobject can be a Bean that any tool makes available for assembling an application as part of a component based architecture. A
JdbcRowSetobject is a connected
RowSetobject, that is, it must continually maintain its connection to its data source using a JDBC technology-enabled driver ("JDBC driver"). In addition, a
JdbcRowSetobject provides a fully updatable and scrollable tabular data structure as defined in the JDBC 3.0 specification.
CachedRowSet™ - A
CachedRowSetobject is a JavaBeans™ component that is scrollable, updatable, serializable, and generally disconnected from the source of its data. A
CachedRowSetobject typically contains rows from a result set, but it can also contain rows from any file with a tabular format, such as a spreadsheet.
CachedRowSetimplementations must use the
SyncFactoryto manage and obtain pluggable
SyncProviderobjects to provide synchronization between the disconnected
RowSetobject and the originating data source. Typically a
SyncProviderimplementation relies upon a JDBC driver to obtain connectivity to a particular data source. Further details on this mechanism are discussed in the
WebRowSetobject is an extension of
CachedRowSetthat can read and write a
RowSetobject in a well formed XML format. This class calls an
XmlReaderobject (an extension of the
RowSetReaderinterface) to read a rowset in XML format. It calls an
XmlWriterobject (an extension of the
RowSetWriterinterface) to write a rowset in XML format. The reader and writer required by
WebRowSetobjects are provided by the
SyncFactoryin the form of
SyncProviderimplementations. In order to ensure well formed XML usage, a standard generic XML Schema is defined and published at
FilteredRowSetobject provides filtering functionality in a programmatic and extensible way. There are many instances when a
objecthas 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. A
FilteredRowSetobject consumes an implementation of the
Predicateinterface, which may define a filter at run time. In turn, a
FilteredRowSetobject 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.
JoinRowSetinterface describes a mechanism by which relationships can be established between two or more standard
RowSetimplementations. Any number of
RowSetobjects can be added to a
JoinRowSetobject provided the
RowSetobjects can be related in a SQL
JOINlike fashion. By definition, the SQL
JOINstatement 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, a
JoinRowSetobject establishes relationships between
RowSetinstances without the need to touch the originating data source.
RowSetImplementations 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
RowSetdefinitions. Implementers should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines on
RowSetimplementations must provide a no-argument constructor.
3.2 Role of the
A compliant JDBC
RowSetimplementation must implement one or more standard interfaces specified in this package and may extend the
BaseRowSetabstract class. For example, a
CachedRowSetimplementation must implement the
CachedRowSetinterface and extend the
BaseRowSetabstract class. The
BaseRowSetclass provides the standard architecture on which all
RowSetimplementations should be built, regardless of whether the
RowSetobjects exist in a connected or disconnected environment. The
BaseRowSetabstract class provides any
RowSetimplementation 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
com.sun.rowsetpackage) use the
BaseRowSetclass as a basis for their implementations.
The following table illustrates the features that the
BaseRowSetabstract class provides.
Feature Details Properties Provides standard JavaBeans property manipulation mechanisms to allow applications to get and set
RowSetcommand and property values. Refer to the documentation of the
javax.sql.RowSetinterface (available in the JDBC 3.0 specification) for more details on the standard
Event notification Provides standard JavaBeans event notifications to registered event listeners. Refer to the documentation of
javax.sql.RowSetEventinterface (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
RowSetobject that must always be connected to the originating data source. Implementations of the
JdbcRowSetshould ensure that this connection is provided solely by a JDBC driver. Furthermore,
RowSetobjects that are implementations of the
JdbcRowSetinterface and are therefore operating in a connected environment do not use the
SyncFactoryto obtain a
RowSetReaderobject or a
RowSetWriterobject. They can safely rely on the JDBC driver to supply their needs by virtue of the presence of an underlying updatable and scrollable
3.4 Disconnected RowSet Requirements
RowSetobject, such as a
CachedRowSetobject, should delegate connection management to a
SyncProviderobject provided by the
SyncFactory. To ensure fully disconnected semantics, all disconnected
RowSetobjects must ensure that the original connection made to the data source to populate the
RowSetobject is closed to permit the garbage collector to recover and release resources. The
SyncProviderobject 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
RowSetobject should therefore ensure that no extraneous references remain on the
3.5 Role of RowSetMetaDataImpl
RowsetMetaDataImplclass is a utility class that provides an implementation of the RowSetMetaData interface, supplying standard setter method implementations for metadata for both connected and disconnected
RowSetobjects. All implementations are free to use this standard implementation but are not required to do so.
3.6 RowSetWarning Class
RowSetWarningclass provides warnings that can be set on
RowSetimplementations. Similar to SQLWarning objects,
RowSetWarningobjects are silently chained to the object whose method caused the warning to be thrown. All
RowSetimplementations should ensure that this chaining occurs if a warning is generated and also ensure that the warnings are available via the
getRowSetWarningsmethod defined in either the
JdbcRowSetinterface or the
CachedRowSetinterface. After a warning has been retrieved with one of the
getNextWarningcan be called on it to retrieve any warnings that might be chained on it. If a warning is returned,
getNextWarningcan be called on it, and so on until there are no more warnings.
3.7 The Joinable Interface
Joinableinterface provides both connected and disconnected
RowSetobjects with the capability to be added to a
JoinRowSetobject in an SQL
RowSetobject that has implemented the
Joinableinterface can set a match column, retrieve a match column, or unset a match column. A
JoinRowSetobject can then use the
RowSetobject's match column as a basis for adding the
3.8 The RowSetFactory Interface
RowSetFactoryimplementation must be provided.
Interface Summary Interface Description CachedRowSetThe interface that all standard implementations of
FilteredRowSetThe standard interface that all standard implementations of
JdbcRowSetThe standard interface that all standard implementations of
Joinable1.0 Background JoinRowSetThe
JoinRowSetinterface provides a mechanism for combining related data from different
RowSetobjects into one
JoinRowSetobject, which represents an SQL
PredicateThe standard interface that provides the framework for all
FilteredRowSetobjects to describe their filters.
RowSetFactoryAn interface that defines the implementation of a factory that is used to obtain different types of
WebRowSetThe standard interface that all implementations of a
Class Summary Class Description BaseRowSetAn abstract class providing a
RowSetobject with its basic functionality.
RowSetMetaDataImplProvides implementations for the methods that set and get metadata information about a
RowSetProviderA factory API that enables applications to obtain a
RowSetFactoryimplementation that can be used to create different types of
Exception Summary Exception Description RowSetWarningAn extension of
SQLExceptionthat provides information about database warnings set on