RowSet
-implementations. This package contains interfaces and classes
-that a standard RowSet implementation either implements or extends.
-
-
-RowSet 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.
-
-
JdbcRowSet - A wrapper around
-a ResultSet object that makes it possible to use the result set as a
-JavaBeans™ component. Thus,
-a JdbcRowSet object can be a Bean that any tool
-makes available for assembling an application as part of a component based
-architecture. A JdbcRowSet object is a connected RowSet
-object, that is, it
-must continually maintain its connection to its data source using a JDBC
-technology-enabled driver ("JDBC driver"). In addition, a JdbcRowSet
-object provides a fully updatable and scrollable tabular
-data structure as defined in the JDBC 3.0 specification.
-
-CachedRowSet™
- - A CachedRowSet object is a JavaBeans™
- component that is scrollable, updatable, serializable, and generally disconnected from
- the source of its data. A CachedRowSet 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 the SyncFactory to manage and obtain pluggable
-SyncProvider objects to provide synchronization between the
-disconnected RowSet object and the originating data source.
-Typically a SyncProvider implementation relies upon a JDBC
-driver to obtain connectivity to a particular data source.
-Further details on this mechanism are discussed in the javax.sql.rowset.spi package
-specification.
-
-WebRowSet - A
-WebRowSet object is an extension of CachedRowSet
-that can read and write a RowSet object in a well formed XML format.
-This class calls an XmlReader object
-(an extension of the RowSetReader
-interface) to read a rowset in XML format. It calls an
-XmlWriter object (an extension of the
-RowSetWriter interface)
-to write a rowset in XML format. The reader and writer required by
-WebRowSet objects are provided by the
-SyncFactory in the form of SyncProvider
-implementations. In order to ensure well formed XML usage, a standard generic XML
-Schema is defined and published at
-
-http://java.sun.com/xml/ns/jdbc/webrowset.xsd.
-
-FilteredRowSet - A
-FilteredRowSet object provides filtering functionality in a programmatic
-and extensible way. There are many instances when a RowSet 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. A FilteredRowSet object consumes
-an implementation of the Predicate
-interface, which may define a filter at run time. In turn, a
-FilteredRowSet 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 - The JoinRowSet
-interface describes a mechanism by which relationships can be established between
-two or more standard RowSet implementations. Any number of RowSet
- objects can be added to a JoinRowSet object provided the RowSetobjects
-can be related in a SQL JOIN like fashion. By definition, the SQL JOIN
-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, a JoinRowSet object establishes relationships between
-RowSet instances without the need to touch the originating data source.
-RowSet 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.
-
-
- All RowSet implementations must provide a
-no-argument constructor.
-
BaseRowSet Class
-
-A compliant JDBC RowSet implementation must implement one or more
-standard interfaces specified in this package and may extend the
-BaseRowSet abstract class. For example, a
-CachedRowSet implementation must implement the CachedRowSet
-interface and extend the BaseRowSet abstract class. The
-BaseRowSet class provides the standard architecture on which all
-RowSet implementations should be built, regardless of whether the
-RowSet objects exist in a connected or disconnected environment.
-The BaseRowSet abstract class provides any 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 com.sun.rowset package) use
-the BaseRowSet 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 -RowSetcommand and -property values. Refer to the documentation of thejavax.sql.RowSet-interface (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.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 JdbcRowSet describes a RowSet object that must always
-be connected to the originating data source. Implementations of the JdbcRowSet
-should ensure that this connection is provided solely by a JDBC driver.
-Furthermore, RowSet objects that are implementations of the
-JdbcRowSet interface and are therefore operating in a connected environment
-do not use the SyncFactory to obtain a RowSetReader object
-or a 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
-ResultSet implementation.
-
-
-A disconnected RowSet object, such as a CachedRowSet object,
-should delegate
-connection management to a SyncProvider object provided by the
-SyncFactory. To ensure fully disconnected semantics, all
-disconnected RowSet objects must ensure
-that the original connection made to the data source to populate the RowSet
-object is closed to permit the garbage collector to recover and release resources. The
-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 RowSet object should
-therefore ensure that no
-extraneous references remain on the Connection object.
-
-
-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 disconnected
-RowSet objects. All implementations are free to use this standard
-implementation but are not required to do so.
-
-
-The RowSetWarning class provides warnings that can be set
-on RowSet implementations.
-Similar to SQLWarning objects,
-RowSetWarning objects are silently chained to the object whose method
-caused the warning to be thrown. All RowSet implementations should
-ensure that this chaining occurs if a warning is generated and also ensure that the
-warnings are available via the getRowSetWarnings method defined in either
-the JdbcRowSet interface or the CachedRowSet interface.
-After a warning has been retrieved with one of the
-getRowSetWarnings methods, the RowSetWarning method
-getNextWarning 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.
-
-
-The Joinable interface provides both connected and disconnected
-RowSet objects with the capability to be added to a
-JoinRowSet object in an SQL JOIN operation.
-A RowSet object that has implemented the Joinable
-interface can set a match column, retrieve a match column, or unset a match column.
-A JoinRowSet object can then use the RowSet object's
-match column as a basis for adding the RowSet object.
-
- A RowSetFactory implementation must
- be provided.
-