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
CachedRowSetimplementation or an implementation derived from it - an XML provider, which is used for reading and writing XML, such as with
WebRowSetobjects
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
RowSetobject, and theSyncFactorydoes not contain a reference to this provider, aSyncFactoryExceptionis thrown stating that the synchronization provider could not be found. - If a
RowSetimplementation is instantiated with a specified provider and the specified provider has been properly registered, the requested provider is supplied. Otherwise aSyncFactoryExceptionis thrown. - If a
RowSetobject does not specify aSyncProviderimplementation and no additionalSyncProviderimplementations 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
TheSyncFactorychecks this file and registers theSyncProviderimplementations 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 theSyncFactorywill attempt to loadSyncProviderimplementations 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,MyProvideris 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
FieldsModifier and TypeFieldDescriptionstatic final StringThe standard property-id for a synchronization provider implementation name.static final StringThe standard property-id for a synchronization provider implementation version tag.static final StringThe standard property-id for a synchronization provider implementation vendor name. -
Method Summary
Modifier and TypeMethodDescriptionstatic SyncProvidergetInstance(String providerID) Returns theSyncProviderinstance identified by providerID.static LoggerReturns 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 SyncFactoryReturns theSyncFactorysingleton.static voidregisterProvider(String providerID) Adds the given synchronization provider to the factory register.static voidsetJNDIContext(Context ctx) Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespacestatic voidSets the logging object to be used by theSyncProviderimplementation provided by theSyncFactory.static voidSets the logging object that is used bySyncProviderimplementations provided by theSyncFactorySPI.static voidunregisterProvider(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 theSyncProviderspecification for the required naming conventions forSyncProviderimplementations.Synchronization providers bound to a JNDI context can be registered by binding a SyncProvider instance to a JNDI namespace.
Furthermore, an initial JNDI context should be set with theSyncProvider p = new MySyncProvider(); InitialContext ic = new InitialContext(); ic.bind ("jdbc/rowset/MySyncProvider", p);SyncFactoryusing thesetJNDIContextmethod. TheSyncFactoryleverages this context to search for availableSyncProviderobjects bound to the JNDI context and its child nodes.- Parameters:
providerID- AStringobject 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 theSyncFactorysingleton.- Returns:
- the
SyncFactoryinstance
-
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 theSyncProviderinstance identified by providerID.- Parameters:
providerID- the unique identifier of the provider- Returns:
- a
SyncProviderimplementation - 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. ARowSetimplementation may use any provider in the enumeration as itsSyncProviderobject.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 theSyncProviderimplementation provided by theSyncFactory. AllSyncProviderimplementations can log their events to this object and the application can retrieve a handle to this object using thegetLoggermethod.This method checks to see that there is an
SQLPermissionobject which grants the permissionsetSyncFactorybefore allowing the method to succeed. If aSecurityManagerexists and itscheckPermissionmethod denies callingsetLogger, this method throws ajava.lang.SecurityException.- Parameters:
logger- A Logger object instance- Throws:
SecurityException- if a security manager exists and itscheckPermissionmethod denies callingsetLoggerNullPointerException- if the logger is null- See Also:
-
setLogger
Sets the logging object that is used bySyncProviderimplementations provided by theSyncFactorySPI. AllSyncProviderimplementations can log their events to this object and the application can retrieve a handle to this object using thegetLoggermethod.This method checks to see that there is an
SQLPermissionobject which grants the permissionsetSyncFactorybefore allowing the method to succeed. If aSecurityManagerexists and itscheckPermissionmethod 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 itscheckPermissionmethod denies callingsetLoggerNullPointerException- if the logger is null- See Also:
-
getLogger
Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.- Returns:
- The
Loggerthat has been specified for use bySyncProviderimplementations - 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
SQLPermissionobject which grants the permissionsetSyncFactorybefore allowing the method to succeed. If aSecurityManagerexists and itscheckPermissionmethod 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 itscheckPermissionmethod denies callingsetJNDIContext- See Also:
-