|
Java™ Platform Standard Ed. 6 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.sql.rowset.spi.SyncProvider
public abstract class SyncProvider
The synchronization mechanism that provides reader/writer capabilities for
disconnected RowSet
objects.
A SyncProvider
implementation is a class that extends the
SyncProvider
abstract class.
A SyncProvider
implementation is
identified by a unique ID, which is its fully qualified class name.
This name must be registered with the
SyncFactory
SPI, thus making the implementation available to
all RowSet
implementations.
The factory mechanism in the reference implementation uses this name to instantiate
the implementation, which can then provide a RowSet
object with its
reader (a javax.sql.RowSetReader
object) and its writer (a
javax.sql.RowSetWriter
object).
The Jdbc RowSet
Implementations specification provides two
reference implementations of the SyncProvider
abstract class:
RIOptimisticProvider
and RIXMLProvider
.
The RIOptimisticProvider
can set any RowSet
implementation with a RowSetReader
object and a
RowSetWriter
object. However, only the RIXMLProvider
implementation can set an XmlReader
object and an
XmlWriter
object. A WebRowSet
object uses the
XmlReader
object to read data in XML format to populate itself with that
data. It uses the XmlWriter
object to write itself to a stream or
java.io.Writer
object in XML format.
SyncProvider
implementations, the following should be noted:
SyncProvider
implementation
is its fully qualified class name.
SyncProvider
implementation in a package named providers
.
For instance, if a vendor named Fred, Inc. offered a
SyncProvider
implementation, you could have the following:
Vendor name: Fred, Inc. Domain name of vendor: com.fred Package name: com.fred.providers SyncProvider implementation class name: HighAvailabilityProvider Fully qualified class name of SyncProvider implementation: com.fred.providers.HighAvailabilityProvider
The following line of code uses the fully qualified name to register
this implementation with the SyncFactory
static instance.
SyncFactory.registerProvider( "com.fred.providers.HighAvailabilityProvider");
The default SyncProvider
object provided with the reference
implementation uses the following name:
com.sun.rowset.providers.RIOptimisticProvider
A vendor can register a SyncProvider
implementation class name
with Sun Microsystems, Inc. by sending email to jdbc@sun.com.
Sun will maintain a database listing the
available SyncProvider
implementations for use with compliant
RowSet
implementations. This database will be similar to the
one already maintained to list available JDBC drivers.
Vendors should refer to the reference implementation synchronization
providers for additional guidance on how to implement a new
SyncProvider
implementation.
RowSet
Object Gets Its ProviderRowset
object may get access to a
SyncProvider
object in one of the following two ways:
CachedRowSet crs = new CachedRowSet( "com.fred.providers.HighAvailabilitySyncProvider");
setSyncProvider
method
CachedRowSet crs = new CachedRowSet(); crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");
By default, the reference implementations of the RowSet
synchronization
providers are always available to the Java platform.
If no other pluggable synchronization providers have been correctly
registered, the SyncFactory
will automatically generate
an instance of the default SyncProvider
reference implementation.
Thus, in the preceding code fragment, if no implementation named
com.fred.providers.HighAvailabilitySyncProvider
has been
registered with the SyncFactory
instance, crs will be
assigned the default provider in the reference implementation, which is
com.sun.rowset.providers.RIOptimisticProvider
.
RowSet
object
and a data source violates
the original query or the underlying data source constraints, this will
result in undefined behavior for all disconnected RowSet
implementations
and their designated SyncProvider
implementations.
Not defining the behavior when such violations occur offers greater flexibility
for a SyncProvider
implementation to determine its own best course of action.
A SyncProvider
implementation
may choose to implement a specific handler to
handle a subset of query violations.
However if an original query violation or a more general data source constraint
violation is not handled by the SyncProvider
implementation,
all SyncProvider
objects must throw a SyncProviderException
.
RowSet
object to be populated
from an SQL query that is formulated originally from an SQL VIEW
.
While in many cases it is possible for an update to be performed to an
underlying view, such an update requires additional metadata, which may vary.
The SyncProvider
class provides two constants to indicate whether
an implementation supports updating an SQL VIEW
.
NONUPDATABLE_VIEW_SYNC
- Indicates that a SyncProvider
implementation does not support synchronization with an SQL VIEW
as the
underlying source of data for the RowSet
object.
UPDATABLE_VIEW_SYNC
- Indicates that a
SyncProvider
implementation
supports synchronization with an SQL VIEW
as the underlying source
of data.
The default is for a RowSet
object not to be updatable if it was
populated with data from an SQL VIEW
.
SyncProvider
ConstantsSyncProvider
class provides three sets of constants that
are used as return values or parameters for SyncProvider
methods.
SyncProvider
objects may be implemented to perform synchronization
between a RowSet
object and its underlying data source with varying
degrees of of care. The first group of constants indicate how synchronization
is handled. For example, GRADE_NONE
indicates that a
SyncProvider
object will not take any care to see what data is
valid and will simply write the RowSet
data to the data source.
GRADE_MODIFIED_AT_COMMIT
indicates that the provider will check
only modified data for validity. Other grades check all data for validity
or set locks when data is modified or loaded.
SyncProvider
object
SyncProvider
object can
perform updates to an SQL VIEW
SyncFactory
,
SyncFactoryException
Field Summary | |
---|---|
static int |
DATASOURCE_DB_LOCK
Indicates that a lock is placed on the entire data source that is the source of data for the RowSet object
that is using this SyncProvider object. |
static int |
DATASOURCE_NO_LOCK
Indicates that no locks remain on the originating data source. |
static int |
DATASOURCE_ROW_LOCK
Indicates that a lock is placed on the rows that are touched by the original SQL statement used to populate the RowSet object
that is using this SyncProvider object. |
static int |
DATASOURCE_TABLE_LOCK
Indicates that a lock is placed on all tables that are touched by the original SQL statement used to populate the RowSet object
that is using this SyncProvider object. |
static int |
GRADE_CHECK_ALL_AT_COMMIT
Indicates a high level optimistic synchronization grade with respect to the originating data source. |
static int |
GRADE_CHECK_MODIFIED_AT_COMMIT
Indicates a low level optimistic synchronization grade with respect to the originating data source. |
static int |
GRADE_LOCK_WHEN_LOADED
Indicates the most pessimistic synchronization grade with respect to the originating data source. |
static int |
GRADE_LOCK_WHEN_MODIFIED
Indicates a pessimistic synchronization grade with respect to the originating data source. |
static int |
GRADE_NONE
Indicates that no synchronization with the originating data source is provided. |
static int |
NONUPDATABLE_VIEW_SYNC
Indicates that a SyncProvider implementation
does not support synchronization between a RowSet
object and the SQL VIEW used to populate it. |
static int |
UPDATABLE_VIEW_SYNC
Indicates that a SyncProvider implementation
supports synchronization between a RowSet object and
the SQL VIEW used to populate it. |
Constructor Summary | |
---|---|
SyncProvider()
Creates a default SyncProvider object. |
Method Summary | |
---|---|
abstract int |
getDataSourceLock()
Returns the current data source lock severity level active in this SyncProvider implementation. |
abstract int |
getProviderGrade()
Returns a constant indicating the grade of synchronization a RowSet object can expect from
this SyncProvider object. |
abstract String |
getProviderID()
Returns the unique identifier for this SyncProvider object. |
abstract RowSetReader |
getRowSetReader()
Returns a javax.sql.RowSetReader object, which can be used to
populate a RowSet object with data. |
abstract RowSetWriter |
getRowSetWriter()
Returns a javax.sql.RowSetWriter object, which can be
used to write a RowSet object's data back to the
underlying data source. |
abstract String |
getVendor()
Returns the vendor name of this SyncProvider instance |
abstract String |
getVersion()
Returns the release version of this SyncProvider instance. |
abstract void |
setDataSourceLock(int datasource_lock)
Sets a lock on the underlying data source at the level indicated by datasource_lock. |
abstract int |
supportsUpdatableView()
Returns whether this SyncProvider implementation
can perform synchronization between a RowSet object
and the SQL VIEW in the data source from which
the RowSet object got its data. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static int GRADE_NONE
SyncProvider
implementation returning this grade will simply attempt to write
updates in the RowSet
object to the underlying data
source without checking the validity of any data.
public static int GRADE_CHECK_MODIFIED_AT_COMMIT
SyncProvider
implementation
returning this grade will check only rows that have changed.
public static int GRADE_CHECK_ALL_AT_COMMIT
SyncProvider
implementation
returning this grade will check all rows, including rows that have not
changed.
public static int GRADE_LOCK_WHEN_MODIFIED
SyncProvider
implementation returning this grade will lock the row in the originating
data source.
public static int GRADE_LOCK_WHEN_LOADED
SyncProvider
implementation returning this grade will lock the entire view and/or
table affected by the original statement used to populate a
RowSet
object.
public static int DATASOURCE_NO_LOCK
SyncProvider
implementations unless
otherwise directed by a RowSet
object.
public static int DATASOURCE_ROW_LOCK
RowSet
object
that is using this SyncProvider
object.
public static int DATASOURCE_TABLE_LOCK
RowSet
object
that is using this SyncProvider
object.
public static int DATASOURCE_DB_LOCK
RowSet
object
that is using this SyncProvider
object.
public static int UPDATABLE_VIEW_SYNC
SyncProvider
implementation
supports synchronization between a RowSet
object and
the SQL VIEW
used to populate it.
public static int NONUPDATABLE_VIEW_SYNC
SyncProvider
implementation
does not support synchronization between a RowSet
object and the SQL VIEW
used to populate it.
Constructor Detail |
---|
public SyncProvider()
SyncProvider
object.
Method Detail |
---|
public abstract String getProviderID()
SyncProvider
object.
String
object with the fully qualified class name of
this SyncProvider
objectpublic abstract RowSetReader getRowSetReader()
javax.sql.RowSetReader
object, which can be used to
populate a RowSet
object with data.
javax.sql.RowSetReader
objectpublic abstract RowSetWriter getRowSetWriter()
javax.sql.RowSetWriter
object, which can be
used to write a RowSet
object's data back to the
underlying data source.
javax.sql.RowSetWriter
objectpublic abstract int getProviderGrade()
RowSet
object can expect from
this SyncProvider
object.
public abstract void setDataSourceLock(int datasource_lock) throws SyncProviderException
SyncProvider
to adjust its behavior by increasing or
decreasing the level of optimism it provides for a successful
synchronization.
datasource_lock
- one of the following constants indicating the severity
level of data source lock required:
SyncProvider.DATASOURCE_NO_LOCK, SyncProvider.DATASOURCE_ROW_LOCK, SyncProvider.DATASOURCE_TABLE_LOCK, SyncProvider.DATASOURCE_DB_LOCK,
SyncProviderException
- if an unsupported data source locking level
is set.getDataSourceLock()
public abstract int getDataSourceLock() throws SyncProviderException
SyncProvider
implementation.
SyncProvider
object;
one of the following:
SyncProvider.DATASOURCE_NO_LOCK, SyncProvider.DATASOURCE_ROW_LOCK, SyncProvider.DATASOURCE_TABLE_LOCK, SyncProvider.DATASOURCE_DB_LOCK
SyncProviderExceptiom
- if an error occurs determining the data
source locking level.
SyncProviderException
setDataSourceLock(int)
public abstract int supportsUpdatableView()
SyncProvider
implementation
can perform synchronization between a RowSet
object
and the SQL VIEW
in the data source from which
the RowSet
object got its data.
int
saying whether this SyncProvider
object supports updating an SQL VIEW
; one of the
following:
SyncProvider.UPDATABLE_VIEW_SYNC,
SyncProvider.NONUPDATABLE_VIEW_SYNCpublic abstract String getVersion()
SyncProvider
instance.
String
detailing the release version of the
SyncProvider
implementationpublic abstract String getVendor()
SyncProvider
instance
String
detailing the vendor name of this
SyncProvider
implementation
|
Java™ Platform Standard Ed. 6 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.