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
TheSyncFactory
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
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 theSyncFactory
does not contain a reference to this provider, aSyncFactoryException
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 aSyncFactoryException
is thrown. - If a
RowSet
object does not specify aSyncProvider
implementation and no additionalSyncProvider
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
TheSyncFactory
checks this file and registers theSyncProvider
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 theSyncFactory
will attempt to loadSyncProvider
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);
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.- Since:
- 1.5
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The standard property-id for a synchronization provider implementation name.static final String
The standard property-id for a synchronization provider implementation version tag.static final String
The standard property-id for a synchronization provider implementation vendor name. -
Method Summary
Modifier and TypeMethodDescriptionstatic SyncProvider
getInstance
(String providerID) Returns theSyncProvider
instance identified by providerID.static Logger
Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.static Enumeration
<SyncProvider> Returns an Enumeration of currently registered synchronization providers.static SyncFactory
Returns theSyncFactory
singleton.static void
registerProvider
(String providerID) Adds the given synchronization provider to the factory register.static void
setJNDIContext
(Context ctx) Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespacestatic void
Sets the logging object to be used by theSyncProvider
implementation provided by theSyncFactory
.static void
Sets the logging object that is used bySyncProvider
implementations provided by theSyncFactory
SPI.static void
unregisterProvider
(String providerID) Removes the designated currently registered synchronization provider from the Factory SPI register.
-
Field Details
-
ROWSET_SYNC_PROVIDER
The standard property-id for a synchronization provider implementation name.- See Also:
-
ROWSET_SYNC_VENDOR
The standard property-id for a synchronization provider implementation vendor name.- See Also:
-
ROWSET_SYNC_PROVIDER_VERSION
The standard property-id for a synchronization provider implementation version tag.- See Also:
-
-
Method Details
-
registerProvider
Adds the given synchronization provider to the factory register. Guidelines are provided in theSyncProvider
specification for the required naming conventions forSyncProvider
implementations.Synchronization providers bound to a JNDI context can be registered by binding a SyncProvider instance to a JNDI namespace.
SyncProvider p = new MySyncProvider(); InitialContext ic = new InitialContext(); ic.bind ("jdbc/rowset/MySyncProvider", p);
SyncFactory
using thesetJNDIContext
method. TheSyncFactory
leverages this context to search for availableSyncProvider
objects bound to the JNDI context and its child nodes.- Parameters:
providerID
- AString
object with the unique ID of the synchronization provider being registered- Throws:
SyncFactoryException
- if an attempt is made to supply an empty or null provider name- See Also:
-
getSyncFactory
Returns theSyncFactory
singleton.- Returns:
- the
SyncFactory
instance
-
unregisterProvider
Removes the designated currently registered synchronization provider from the Factory SPI register.- Parameters:
providerID
- The unique-id of the synchronization provider- Throws:
SyncFactoryException
- If an attempt is made to unregister a SyncProvider implementation that was not registered.
-
getInstance
Returns theSyncProvider
instance identified by providerID.- Parameters:
providerID
- the unique identifier of the provider- Returns:
- a
SyncProvider
implementation - Throws:
SyncFactoryException
- If the SyncProvider cannot be found, the providerID isnull
, or some error was encountered when trying to invoke this provider.
-
getRegisteredProviders
Returns an Enumeration of currently registered synchronization providers. ARowSet
implementation may use any provider in the enumeration as itsSyncProvider
object.At a minimum, the reference synchronization provider allowing RowSet content data to be stored using a JDBC driver should be possible.
- Returns:
- Enumeration A enumeration of available synchronization providers that are registered with this Factory
- Throws:
SyncFactoryException
- If an error occurs obtaining the registered providers
-
setLogger
Sets the logging object to be used by theSyncProvider
implementation provided by theSyncFactory
. AllSyncProvider
implementations can log their events to this object and the application can retrieve a handle to this object using thegetLogger
method.This method checks to see that there is an
SQLPermission
object which grants the permissionsetSyncFactory
before allowing the method to succeed. If aSecurityManager
exists and itscheckPermission
method denies callingsetLogger
, this method throws ajava.lang.SecurityException
.- Parameters:
logger
- A Logger object instance- Throws:
SecurityException
- if a security manager exists and itscheckPermission
method denies callingsetLogger
NullPointerException
- if the logger is null- See Also:
-
setLogger
Sets the logging object that is used bySyncProvider
implementations provided by theSyncFactory
SPI. AllSyncProvider
implementations can log their events to this object and the application can retrieve a handle to this object using thegetLogger
method.This method checks to see that there is an
SQLPermission
object which grants the permissionsetSyncFactory
before allowing the method to succeed. If aSecurityManager
exists and itscheckPermission
method denies callingsetLogger
, this method throws ajava.lang.SecurityException
.- Parameters:
logger
- a Logger object instancelevel
- a Level object instance indicating the degree of logging required- Throws:
SecurityException
- if a security manager exists and itscheckPermission
method denies callingsetLogger
NullPointerException
- if the logger is null- See Also:
-
getLogger
Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.- Returns:
- The
Logger
that has been specified for use bySyncProvider
implementations - Throws:
SyncFactoryException
- if no logging object has been set.
-
setJNDIContext
Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespaceThis method checks to see that there is an
SQLPermission
object which grants the permissionsetSyncFactory
before allowing the method to succeed. If aSecurityManager
exists and itscheckPermission
method denies callingsetJNDIContext
, this method throws ajava.lang.SecurityException
.- Parameters:
ctx
- a valid JNDI context- Throws:
SyncFactoryException
- if the supplied JNDI context is nullSecurityException
- if a security manager exists and itscheckPermission
method denies callingsetJNDIContext
- See Also:
-