java.util.Enumeration e = SyncFactory.getRegisteredProviders();

rowset.provider.classname.2=com.fred.providers.HighAvailabilityProvider
rowset.provider.vendor.2=Fred, Inc.
rowset.provider.version.2=1.0

The Service Provider Interface (SPI) mechanism that generates SyncProvider
instances to be used by disconnected RowSet objects.
The SyncProvider instances in turn provide the
javax.sql.RowSetReader object the RowSet object
needs to populate itself with data and the
javax.sql.RowSetWriter object it needs to
propagate changes to its
data back to the underlying data source.

Because the methods in the SyncFactory class are all static,
there is only one SyncFactory object
per Java VM at any one time. This ensures that there is a single source from which a
RowSet implementation can obtain its SyncProvider
implementation.

1.0 Overview
The SyncFactory class provides an internal registry of available
synchronization provider implementations (SyncProvider objects).
This registry may be queried to determine which
synchronization providers are available.
The following line of code gets an enumeration of the providers currently registered.


    java.util.Enumeration e = SyncFactory.getRegisteredProviders();
All standard RowSet implementations must provide at least two providers:

 an optimistic provider for use with a CachedRowSet implementation
    or an implementation derived from it
 an XML provider, which is used for reading and writing XML, such as with
      WebRowSet objects

Note that the JDBC RowSet Implementations include the SyncProvider
implementations RIOptimisticProvider and RIXmlProvider,
which satisfy this requirement.

The SyncFactory class provides accessor methods to assist
applications in determining which synchronization providers are currently
registered with the SyncFactory.

Other methods let RowSet persistence providers be
registered or de-registered with the factory mechanism. This
allows additional synchronization provider implementations to be made
available to RowSet objects at run time.

Applications can apply a degree of filtering to determine the level of
synchronization that a SyncProvider implementation offers.
The following criteria determine whether a provider is
made available to a RowSet object:

If a particular provider is specified by a RowSet object, and
the SyncFactory does not contain a reference to this provider,
a SyncFactoryException is thrown stating that the synchronization
provider could not be found.

If a RowSet implementation is instantiated with a specified
provider and the specified provider has been properly registered, the
requested provider is supplied. Otherwise a SyncFactoryException
is thrown.

If a RowSet object does not specify a
SyncProvider implementation and no additional
SyncProvider implementations are available, the reference
implementation providers are supplied.

2.0 Registering SyncProvider Implementations

Both vendors and developers can register SyncProvider
implementations using one of the following mechanisms.

Using the command line
The name of the provider is supplied on the command line, which will add
the provider to the system properties.
For example:


   -Drowset.provider.classname=com.fred.providers.HighAvailabilityProvider
Using the Standard Properties File
The reference implementation is targeted
to ship with J2SE 1.5, which will include an additional resource file
that may be edited by hand. Here is an example of the properties file
included in the reference implementation:


  #Default JDBC RowSet sync providers listing
  #

  # Optimistic synchronization provider
  rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
  rowset.provider.vendor.0=Oracle Corporation
  rowset.provider.version.0=1.0

  # XML Provider using standard XML schema
  rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
  rowset.provider.vendor.1=Oracle Corporation
  rowset.provider.version.1=1.0
The SyncFactory checks this file and registers the
SyncProvider implementations that it contains. A
developer or vendor can add other implementations to this file.
For example, here is a possible addition:


    rowset.provider.classname.2=com.fred.providers.HighAvailabilityProvider
    rowset.provider.vendor.2=Fred, Inc.
    rowset.provider.version.2=1.0

Using a JNDI Context
Available providers can be registered on a JNDI
context, and the SyncFactory will attempt to load
SyncProvider implementations from that JNDI context.
For example, the following code fragment registers a provider implementation
on a JNDI context.  This is something a deployer would normally do. In this
example, MyProvider is being registered on a CosNaming
namespace, which is the namespace used by J2EE resources.


   import javax.naming.*;

   Hashtable svrEnv = new  Hashtable();
   srvEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");

   Context ctx = new InitialContext(svrEnv);
   com.fred.providers.MyProvider = new MyProvider();
   ctx.rebind("providers/MyProvider", syncProvider);

Next, an application will register the JNDI context with the
SyncFactory instance.  This allows the SyncFactory
to browse within the JNDI context looking for SyncProvider
implementations.


   Hashtable appEnv = new Hashtable();
   appEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
   appEnv.put(Context.PROVIDER_URL, "iiop://hostname/providers");
   Context ctx = new InitialContext(appEnv);

   SyncFactory.registerJNDIContext(ctx);
If a RowSet object attempts to obtain a MyProvider
object, the SyncFactory will try to locate it. First it searches
for it in the system properties, then it looks in the resource files, and
finally it checks the JNDI context that has been set. The SyncFactory
instance verifies that the requested provider is a valid extension of the
SyncProvider abstract class and then gives it to the
RowSet object. In the following code fragment, a new
CachedRowSet object is created and initialized with
env, which contains the binding to MyProvider.


   Hashtable env = new Hashtable();
   env.put(SyncFactory.ROWSET_SYNC_PROVIDER, "com.fred.providers.MyProvider");
   CachedRowSet crs = new com.sun.rowset.CachedRowSetImpl(env);
Further details on these mechanisms are available in the
javax.sql.rowset.spi package specification.

Indicates an error with SyncFactory mechanism. A disconnected
RowSet implementation cannot be used  without a SyncProvider
being successfully instantiated

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

SyncFactory.registerProvider(
                     "com.fred.providers.HighAvailabilityProvider");

com.sun.rowset.providers.RIOptimisticProvider

  CachedRowSet crs = new CachedRowSet(
             "com.fred.providers.HighAvailabilitySyncProvider");

  CachedRowSet crs = new CachedRowSet();
  crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");

SyncProvider.DATASOURCE_NO_LOCK
SyncProvider.DATASOURCE_ROW_LOCK
SyncProvider.DATASOURCE_TABLE_LOCK
SyncProvider.DATASOURCE_DB_LOCK

SyncProvider.UPDATABLE_VIEW_SYNC
SyncProvider.NONUPDATABLE_VIEW_SYNC

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.

1.0 Naming Convention for Implementations
As a guide  to naming SyncProvider
implementations, the following should be noted:

The name for a SyncProvider implementation
is its fully qualified class name.
It is recommended that vendors supply a
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 Oracle Corporation by sending email to jdbc@sun.com.
Oracle 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.

2.0 How a RowSet Object Gets Its Provider

A disconnected Rowset object may get access to a
SyncProvider object in one of the following two ways:

 Using a constructor


      CachedRowSet crs = new CachedRowSet(
                 "com.fred.providers.HighAvailabilitySyncProvider");
 Using the 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.

3.0 Violations and Synchronization Issues
If an update between a disconnected 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.

4.0 Updatable SQL VIEWs
It is possible for any disconnected or connected 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.

5.0 SyncProvider Constants
The SyncProvider 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.

 Constants to indicate the synchronization grade of a
    SyncProvider object

   SyncProvider.GRADE_NONE
   SyncProvider.GRADE_MODIFIED_AT_COMMIT
   SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
   SyncProvider.GRADE_LOCK_WHEN_MODIFIED
   SyncProvider.GRADE_LOCK_WHEN_LOADED

 Constants to indicate what locks are set on the data source

    SyncProvider.DATASOURCE_NO_LOCK
    SyncProvider.DATASOURCE_ROW_LOCK
    SyncProvider.DATASOURCE_TABLE_LOCK
    SyncProvider.DATASOURCE_DB_LOCK

 Constants to indicate whether a SyncProvider object can
      perform updates to an SQL VIEW
      These constants are explained in the preceding section (4.0).

    SyncProvider.UPDATABLE_VIEW_SYNC
    SyncProvider.NONUPDATABLE_VIEW_SYNC

Indicates an error with the SyncProvider mechanism. This exception
is created by a SyncProvider abstract class extension if it
encounters violations in reading from or writing to the originating data source.

If it is implemented to do so, the SyncProvider object may also create a
SyncResolver object and either initialize the SyncProviderException
object with it at construction time or set it with the SyncProvider object at
a later time.

The method acceptChanges will throw this exception after the writer
has finished checking for conflicts and has found one or more conflicts. An
application may catch a SyncProviderException object and call its
getSyncResolver method to get its SyncResolver object.
See the code fragment in the interface comment for
SyncResolver for an example.
This SyncResolver object will mirror the RowSet
object that generated the exception, except that it will contain only the values
from the data source that are in conflict.  All other values in the SyncResolver
object will be null.

The SyncResolver object may be used to examine and resolve
each conflict in a row and then go to the next row with a conflict to
repeat the procedure.

A SyncProviderException object may or may not contain a description of the
condition causing the exception.  The inherited method getMessage may be
called to retrieve the description if there is one.

 catch (SyncProviderException spe) {
    SyncResolver resolver = spe.getSyncResolver();
...
}

 int operation = resolver.getStatus();

java.lang.Object conflictValue = resolver.getConflictValue(2);

resolver.setResolvedValue("DEPT", 8390426);

try {

    crs.acceptChanges(con);

} catch (SyncProviderException spe) {

    SyncResolver resolver = spe.getSyncResolver();

    Object crsValue;  // value in the RowSet object
    Object resolverValue:  // value in the SyncResolver object
    Object resolvedValue:  // value to be persisted

    while(resolver.nextConflict())  {
        if(resolver.getStatus() == SyncResolver.UPDATE_ROW_CONFLICT)  {
            int row = resolver.getRow();
            crs.absolute(row);

            int colCount = crs.getMetaData().getColumnCount();
            for(int j = 1; j <= colCount; j++) {
                if (resolver.getConflictValue(j) != null)  {
                    crsValue = crs.getObject(j);
                    resolverValue = resolver.getConflictValue(j);
                    . . .
                    // compare crsValue and resolverValue to determine
                    // which should be the resolved value (the value to persist)
                    resolvedValue = crsValue;

                    resolver.setResolvedValue(j, resolvedValue);
                 }
             }
         }
     }
 }

Defines a framework that allows applications to use a manual decision tree
to decide what should be done when a synchronization conflict occurs.
Although it is not mandatory for
applications to resolve synchronization conflicts manually, this
framework provides the means to delegate to the application when conflicts
arise.

Note that a conflict is a situation where the RowSet object's original
values for a row do not match the values in the data source, which indicates that
the data source row has been modified since the last synchronization. Note also that
a RowSet object's original values are the values it had just prior to the
the last synchronization, which are not necessarily its initial values.


Description of a SyncResolver Object

A SyncResolver object is a specialized RowSet object
that implements the SyncResolver interface.
It may operate as either a connected RowSet object (an
implementation of the JdbcRowSet interface) or a connected
RowSet object (an implementation of the
CachedRowSet interface or one of its subinterfaces). For information
on the subinterfaces, see the
javax.sql.rowset package
description. The reference implementation for SyncResolver implements
the CachedRowSet interface, but other implementations
may choose to implement the JdbcRowSet interface to satisfy
particular needs.

After an application has attempted to synchronize a RowSet object with
the data source (by calling the CachedRowSet
method acceptChanges), and one or more conflicts have been found,
a rowset's SyncProvider object creates an instance of
SyncResolver. This new SyncResolver object has
the same number of rows and columns as the
RowSet object that was attempting the synchronization. The
SyncResolver object contains the values from the data source that caused
the conflict(s) and null for all other values.
In addition, it contains information about each conflict.


Getting and Using a SyncResolver Object

When the method acceptChanges encounters conflicts, the
SyncProvider object creates a SyncProviderException
object and sets it with the new SyncResolver object. The method
acceptChanges will throw this exception, which
the application can then catch and use to retrieve the
SyncResolver object it contains. The following code snippet uses the
SyncProviderException method getSyncResolver to get
the SyncResolver object resolver.


     catch (SyncProviderException spe) {
        SyncResolver resolver = spe.getSyncResolver();
    ...
    }

}

With resolver in hand, an application can use it to get the information
it contains about the conflict or conflicts.  A SyncResolver object
such as resolver keeps
track of the conflicts for each row in which there is a conflict.  It also places a
lock on the table or tables affected by the rowset's command so that no more
conflicts can occur while the current conflicts are being resolved.

The following kinds of information can be obtained from a SyncResolver
object:

   What operation was being attempted when a conflict occurred
The SyncProvider interface defines four constants
describing states that may occur. Three
constants describe the type of operation (update, delete, or insert) that a
RowSet object was attempting to perform when a conflict was discovered,
and the fourth indicates that there is no conflict.
These constants are the possible return values when a SyncResolver object
calls the method getStatus.


     int operation = resolver.getStatus();

   The value in the data source that caused a conflict
A conflict exists when a value that a RowSet object has changed
and is attempting to write to the data source
has also been changed in the data source since the last synchronization.  An
application can call the SyncResolver method
getConflictValue to retrieve the
value in the data source that is the cause of the conflict because the values in a
SyncResolver object are the conflict values from the data source.


    java.lang.Object conflictValue = resolver.getConflictValue(2);
Note that the column in resolver can be designated by the column number,
as is done in the preceding line of code, or by the column name.

With the information retrieved from the methods getStatus and
getConflictValue, the application may make a determination as to
which value should be persisted in the data source. The application then calls the
SyncResolver method setResolvedValue, which sets the value
to be persisted in the RowSet object and also in the data source.


    resolver.setResolvedValue("DEPT", 8390426);
In the preceding line of code,
the column name designates the column in the RowSet object
that is to be set with the given value. The column number can also be used to
designate the column.

An application calls the method setResolvedValue after it has
resolved all of the conflicts in the current conflict row and repeats this process
for each conflict row in the SyncResolver object.


Navigating a SyncResolver Object

Because a SyncResolver object is a RowSet object, an
application can use all of the RowSet methods for moving the cursor
to navigate a SyncResolver object. For example, an application can
use the RowSet method next to get to each row and then
call the SyncResolver method getStatus to see if the row
contains a conflict.  In a row with one or more conflicts, the application can
iterate through the columns to find any non-null values, which will be the values
from the data source that are in conflict.

To make it easier to navigate a SyncResolver object, especially when
there are large numbers of rows with no conflicts, the SyncResolver
interface defines the methods nextConflict and
previousConflict, which move only to rows
that contain at least one conflict value. Then an application can call the
SyncResolver method getConflictValue, supplying it
with the column number, to get the conflict value itself. The code fragment in the
next section gives an example.

Code Example

The following code fragment demonstrates how a disconnected RowSet
object crs might attempt to synchronize itself with the
underlying data source and then resolve the conflicts. In the try
block, crs calls the method acceptChanges, passing it the
Connection object con.  If there are no conflicts, the
changes in crs are simply written to the data source.  However, if there
is a conflict, the method acceptChanges throws a
SyncProviderException object, and the
catch block takes effect.  In this example, which
illustrates one of the many ways a SyncResolver object can be used,
the SyncResolver method nextConflict is used in a
while loop. The loop will end when nextConflict returns
false, which will occur when there are no more conflict rows in the
SyncResolver object resolver. In This particular code fragment,
resolver looks for rows that have update conflicts (rows with the status
SyncResolver.UPDATE_ROW_CONFLICT), and the rest of this code fragment
executes only for rows where conflicts occurred because crs was attempting an
update.

After the cursor for resolver has moved to the next conflict row that
has an update conflict, the method getRow indicates the number of the
current row, and
the cursor for the CachedRowSet object crs is moved to
the comparable row in crs. By iterating
through the columns of that row in both resolver and crs, the conflicting
values can be retrieved and compared to decide which one should be persisted. In this
code fragment, the value in crs is the one set as the resolved value, which means
that it will be used to overwrite the conflict value in the data source.



    try {

        crs.acceptChanges(con);

    } catch (SyncProviderException spe) {

        SyncResolver resolver = spe.getSyncResolver();

        Object crsValue;  // value in the RowSet object
        Object resolverValue:  // value in the SyncResolver object
        Object resolvedValue:  // value to be persisted

        while(resolver.nextConflict())  {
            if(resolver.getStatus() == SyncResolver.UPDATE_ROW_CONFLICT)  {
                int row = resolver.getRow();
                crs.absolute(row);

                int colCount = crs.getMetaData().getColumnCount();
                for(int j = 1; j <= colCount; j++) {
                    if (resolver.getConflictValue(j) != null)  {
                        crsValue = crs.getObject(j);
                        resolverValue = resolver.getConflictValue(j);
                        . . .
                        // compare crsValue and resolverValue to determine
                        // which should be the resolved value (the value to persist)
                        resolvedValue = crsValue;

                        resolver.setResolvedValue(j, resolvedValue);
                     }
                 }
             }
         }
     }

A specialized interface that facilitates an extension of the standard
SyncProvider abstract class so that it has finer grained
transaction control.

If one or more disconnected RowSet objects are participating
in a global transaction, they may wish to coordinate their synchronization
commits to preserve data integrity and reduce the number of
synchronization exceptions. If this is the case, an application should set
the CachedRowSet constant COMMIT_ON_ACCEPT_CHANGES
to false and use the commit and rollback
methods defined in this interface to manage transaction boundaries.

A specialized interface that facilitates an extension of the
SyncProvider abstract class for XML orientated
synchronization providers.

SyncProvider  implementations that supply XML data reader
capabilities such as output XML stream capabilities can implement this
interface to provide standard XmlReader objects to
WebRowSet implementations.

An XmlReader object is registered as the
XML reader for a WebRowSet by being assigned to the
rowset's xmlReader field. When the WebRowSet
object's readXml method is invoked, it in turn invokes
its XML reader's readXML method.

A specialized interface that facilitates an extension of the
SyncProvider abstract class for XML orientated
synchronization providers.

SyncProvider  implementations that supply XML data writer
capabilities such as output XML stream capabilities can implement this
interface to provide standard XmlWriter objects to
WebRowSet implementations.

Writing a WebRowSet object includes printing the
rowset's data, metadata, and properties, all with the
appropriate XML tags.