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 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- ACachedRowSetobject is a JavaBeans component that is scrollable, updatable, serializable, and generally disconnected from the source of its data. ACachedRowSetobject 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 theSyncFactoryto manage and obtain pluggableSyncProviderobjects to provide synchronization between the disconnectedRowSetobject and the originating data source. Typically aSyncProviderimplementation relies upon a JDBC driver to obtain connectivity to a particular data source. Further details on this mechanism are discussed in thejavax.sql.rowset.spipackage specification.
- WebRowSet- A- 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- http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd.
- FilteredRowSet- A- FilteredRowSetobject provides filtering functionality in a programmatic and extensible way. There are many instances when a- RowSet- 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.
- JoinRowSet- The- 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.
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 RowSetimplementations must provide a no-argument constructor.
- 3.2 Role of the BaseRowSetClassA compliant JDBC RowSetimplementation must implement one or more standard interfaces specified in this package and may extend theBaseRowSetabstract class. For example, aCachedRowSetimplementation must implement theCachedRowSetinterface and extend theBaseRowSetabstract class. TheBaseRowSetclass provides the standard architecture on which allRowSetimplementations should be built, regardless of whether theRowSetobjects exist in a connected or disconnected environment. TheBaseRowSetabstract class provides anyRowSetimplementation 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.rowsetpackage) use theBaseRowSetclass as a basis for their implementations.The following table illustrates the features that the BaseRowSetabstract class provides.Features in BaseRowSetFeature Details Properties Provides standard JavaBeans property manipulation mechanisms to allow applications to get and set RowSetcommand and property values. Refer to the documentation of thejavax.sql.RowSetinterface (available in the JDBC 3.0 specification) for more details on the standardRowSetproperties.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
 The JdbcRowSetdescribes aRowSetobject that must always be connected to the originating data source. Implementations of theJdbcRowSetshould ensure that this connection is provided solely by a JDBC driver. Furthermore,RowSetobjects that are implementations of theJdbcRowSetinterface and are therefore operating in a connected environment do not use theSyncFactoryto obtain aRowSetReaderobject or aRowSetWriterobject. They can safely rely on the JDBC driver to supply their needs by virtue of the presence of an underlying updatable and scrollableResultSetimplementation.
- 
 3.4 Disconnected RowSet Requirements
 A disconnected RowSetobject, such as aCachedRowSetobject, should delegate connection management to aSyncProviderobject provided by theSyncFactory. To ensure fully disconnected semantics, all disconnectedRowSetobjects must ensure that the original connection made to the data source to populate theRowSetobject is closed to permit the garbage collector to recover and release resources. TheSyncProviderobject 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 disconnectedRowSetobject should therefore ensure that no extraneous references remain on theConnectionobject.
- 3.5 Role of RowSetMetaDataImpl
 The RowsetMetaDataImplclass is a utility class that provides an implementation of theRowSetMetaDatainterface, supplying standard setter method implementations for metadata for both connected and disconnectedRowSetobjects. All implementations are free to use this standard implementation but are not required to do so.
- 3.6 RowSetWarning Class
 The RowSetWarningclass provides warnings that can be set onRowSetimplementations. Similar toSQLWarningobjects,RowSetWarningobjects are silently chained to the object whose method caused the warning to be thrown. AllRowSetimplementations should ensure that this chaining occurs if a warning is generated and also ensure that the warnings are available via thegetRowSetWarningsmethod defined in either theJdbcRowSetinterface or theCachedRowSetinterface. After a warning has been retrieved with one of thegetRowSetWarningsmethods, theRowSetWarningmethodgetNextWarningcan 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
 The Joinableinterface provides both connected and disconnectedRowSetobjects with the capability to be added to aJoinRowSetobject in an SQLJOINoperation. ARowSetobject that has implemented theJoinableinterface can set a match column, retrieve a match column, or unset a match column. AJoinRowSetobject can then use theRowSetobject's match column as a basis for adding theRowSetobject.
- 3.8 The RowSetFactory Interface
   A RowSetFactoryimplementation must be provided.
4.0 Related Specifications
5.0 Related Documentation
- 
ClassDescriptionAn abstract class providing aRowSetobject with its basic functionality.The interface that all standard implementations ofCachedRowSetmust implement.The standard interface that all standard implementations ofFilteredRowSetmust implement.The standard interface that all standard implementations ofJdbcRowSetmust implement.1.0 BackgroundTheJoinRowSetinterface provides a mechanism for combining related data from differentRowSetobjects into oneJoinRowSetobject, which represents an SQLJOIN.The standard interface that provides the framework for allFilteredRowSetobjects to describe their filters.An interface that defines the implementation of a factory that is used to obtain different types ofRowSetimplementations.Provides implementations for the methods that set and get metadata information about aRowSetobject's columns.A factory API that enables applications to obtain aRowSetFactoryimplementation that can be used to create different types ofRowSetimplementations.An extension ofSQLExceptionthat provides information about database warnings set onRowSetobjects.The standard interface that all implementations of aWebRowSetmust implement.