/*
* Copyright (c) 2003, 2018, 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.
*/
/**
*
* Repository for the RowSet
reference implementations of the
* SyncProvider
abstract class. These implementations provide a
* disconnected RowSet
* object with the ability to synchronize the data in the underlying data
* source with its data. These implementations are provided as
* the default SyncProvider
implementations and are accessible via the
* SyncProvider
SPI managed by the SyncFactory
.
*
*
SyncProvider
Reference ImplementationsSyncProvider
implementation is to manage
* the reader and writer mechanisms.
* The SyncProvider
SPI, as specified in the javax.sql.rowset.spi
* package, provides a pluggable mechanism by which javax.sql.RowSetReader
* and javax.sql.RowSetWriter
implementations can be supplied to a disconnected
* RowSet
object.
*
* A reader, a javax.sql.RowSetReader
* object, does the work necessary to populate a RowSet
object with data.
* A writer, a javax.sql.RowSetWriter
object, does the work necessary for
* synchronizing a RowSet
object's data with the data in the originating
* source of data. Put another way, a writer writes a RowSet
* object's data back to the data source.
*
* Generally speaking, the course of events is this. The reader makes a connection to
* the data source and reads the data from a ResultSet
object into its
* RowSet
object. Then it closes the connection. While
* the RowSet
object is disconnected, an application makes some modifications
* to the data and calls the method acceptChanges
. At this point, the
* writer is called to write the changes back to the database table or view
* from which the original data came. This is called synchronization.
*
* If the data in the originating data source has not changed, there is no problem
* with just writing the RowSet
object's new data to the data source.
* If it has changed, however, there is a conflict that needs to be resolved. One
* way to solve the problem is not to let the data in the data source be changed in
* the first place, which can be done by setting locks on a row, a table, or the
* whole data source. Setting locks is a way to avoid conflicts, but it can be
* very expensive. Another approach, which is at the other end of the spectrum,
* is simply to assume that no conflicts will occur and thus do nothing to avoid
* conflicts.
* Different SyncProvider
implementations may handle synchronization in
* any of these ways, varying from doing no checking for
* conflicts, to doing various levels of checking, to guaranteeing that there are no
* conflicts.
*
* The SyncProvider
class offers methods to help a RowSet
* object discover and manage how a provider handles synchronization.
* The method getProviderGrade
returns the
* grade of synchronization a provider offers. An application can
* direct the provider to use a particular level of locking by calling
* the method setDataSourceLock
and specifying the level of locking desired.
* If a RowSet
object's data came from an SQL VIEW
, an
* application may call the method supportsUpdatableView
to
* find out whether the VIEW
can be updated.
*
* Synchronization is done completely behind the scenes, so it is third party vendors of * synchronization provider implementations who have to take care of this complex task. * Application programmers can decide which provider to use and the level of locking to * be done, but they are free from having to worry about the implementation details. *
* The JDBC RowSet
Implementations reference implementation provides two
* implementations of the SyncProvider
class:
*
*
RIOptimisticProvider
- provides the javax.sql.RowSetReader
* and javax.sql.RowSetWriter
interface implementations and provides
* an optimistic concurrency model for synchronization. This model assumes that there
* will be few conflicts and therefore uses a relatively low grade of synchronization.
* If no other provider is available, this is the default provider that the
* SyncFactory
will supply to a RowSet
object.
* RIXMLProvider
- provides the XmlReader
(an extension
* of the javax.sql.RowSetReader
interface) and the XmlWriter
* (an extension of the javax.sql.RowSetWriter
interface) to enable
* WebRowSet
objects to write their state to a
* well formed XML document according to the WebRowSet
XML schema
* definition.command
property contains the query that determines what
* data a RowSet
will contain. Rowsets have methods for setting a query's
* parameter(s), which means that a query can be executed multiple times with
* different parameters to produce different result sets. Or the query can be
* changed to something completely new to get a new result set.
* Once a rowset contains the rows from a ResultSet
object or some
* other data source, its column values can be updated, and its rows can be
* inserted or deleted. Any method that causes a change in the rowset's values
* or cursor position also notifies any object that has been registered as
* a listener with the rowset. So, for example, a table that displays the rowset's
* data in an applet can be notified of changes and make updates as they
* occur.
*
* The changes made to a rowset can be propagated back to the original data
* source to keep the rowset and its data source synchronized. Although this
* involves many operations behind the scenes, it is completely transparent
* to the application programmer and remains the concern of the RowSet provider
* developer. All an application has to do is invoke the method acceptChanges
,
* and the data source backing the rowset will be updated to match the current
* values in the rowset.
A disconnected rowset, such as a CachedRowSet
or WebRowSet
* object, establishes a connection to populate itself with data from a database
* and then closes the connection. The RowSet
object will remain
* disconnected until it wants to propagate changes back to its database table,
* which is optional. To write its changes back to the database (synchronize with
* the database), the rowset establishes a connection, write the changes, and then
* once again disconnects itself.
*
SyncProvider
abstract
* class. One possibility is to employ a more robust synchronization model, which
* would give a RowSet
object increased trust in the provider's
* ability to get any updates back to the original data source. Another possibility
* is a more formal synchronization mechanism such as SyncML
* (http://www.syncml.org/)