- java.lang.Object
-
- javax.sql.rowset.spi.SyncFactory
-
public class SyncFactory extends Object
The Service Provider Interface (SPI) mechanism that generatesSyncProviderinstances to be used by disconnectedRowSetobjects. TheSyncProviderinstances in turn provide thejavax.sql.RowSetReaderobject theRowSetobject needs to populate itself with data and thejavax.sql.RowSetWriterobject it needs to propagate changes to its data back to the underlying data source.Because the methods in the
SyncFactoryclass are all static, there is only oneSyncFactoryobject per Java VM at any one time. This ensures that there is a single source from which aRowSetimplementation can obtain itsSyncProviderimplementation.1.0 Overview
TheSyncFactoryclass provides an internal registry of available synchronization provider implementations (SyncProviderobjects). 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 standardRowSetimplementations 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
SyncProviderimplementationsRIOptimisticProviderandRIXmlProvider, which satisfy this requirement.The
SyncFactoryclass provides accessor methods to assist applications in determining which synchronization providers are currently registered with theSyncFactory.Other methods let
RowSetpersistence providers be registered or de-registered with the factory mechanism. This allows additional synchronization provider implementations to be made available toRowSetobjects at run time.Applications can apply a degree of filtering to determine the level of synchronization that a
SyncProviderimplementation offers. The following criteria determine whether a provider is made available to aRowSetobject:- 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
SyncProviderImplementationsBoth vendors and developers can register
SyncProviderimplementations 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);
SyncFactoryinstance. This allows theSyncFactoryto browse within the JNDI context looking forSyncProviderimplementations.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 aRowSetobject attempts to obtain aMyProviderobject, theSyncFactorywill 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. TheSyncFactoryinstance verifies that the requested provider is a valid extension of theSyncProviderabstract class and then gives it to theRowSetobject. In the following code fragment, a newCachedRowSetobject is created and initialized with env, which contains the binding toMyProvider.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 thejavax.sql.rowset.spipackage specification.- Since:
- 1.5
- See Also:
SyncProvider,SyncFactoryException
- an optimistic provider for use with a
-
-
Field Summary
Fields Modifier and Type Field Description static StringROWSET_SYNC_PROVIDERThe standard property-id for a synchronization provider implementation name.static StringROWSET_SYNC_PROVIDER_VERSIONThe standard property-id for a synchronization provider implementation version tag.static StringROWSET_SYNC_VENDORThe standard property-id for a synchronization provider implementation vendor name.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static SyncProvidergetInstance(String providerID)Returns theSyncProviderinstance identified by providerID.static LoggergetLogger()Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.static Enumeration<SyncProvider>getRegisteredProviders()Returns an Enumeration of currently registered synchronization providers.static SyncFactorygetSyncFactory()Returns 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 voidsetLogger(Logger logger)Sets the logging object to be used by theSyncProviderimplementation provided by theSyncFactory.static voidsetLogger(Logger logger, Level level)Sets 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 Detail
-
ROWSET_SYNC_PROVIDER
public static final String ROWSET_SYNC_PROVIDER
The standard property-id for a synchronization provider implementation name.- See Also:
- Constant Field Values
-
ROWSET_SYNC_VENDOR
public static final String ROWSET_SYNC_VENDOR
The standard property-id for a synchronization provider implementation vendor name.- See Also:
- Constant Field Values
-
ROWSET_SYNC_PROVIDER_VERSION
public static final String ROWSET_SYNC_PROVIDER_VERSION
The standard property-id for a synchronization provider implementation version tag.- See Also:
- Constant Field Values
-
-
Method Detail
-
registerProvider
public static void registerProvider(String providerID) throws SyncFactoryException
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:
setJNDIContext(javax.naming.Context)
-
getSyncFactory
public static SyncFactory getSyncFactory()
Returns theSyncFactorysingleton.- Returns:
- the
SyncFactoryinstance
-
unregisterProvider
public static void unregisterProvider(String providerID) throws SyncFactoryException
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
public static SyncProvider getInstance(String providerID) throws SyncFactoryException
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
public static Enumeration<SyncProvider> getRegisteredProviders() throws SyncFactoryException
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
public static void setLogger(Logger logger)
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:
SecurityManager.checkPermission(java.security.Permission)
-
setLogger
public static void setLogger(Logger logger, Level level)
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:
SecurityManager.checkPermission(java.security.Permission),LoggingPermission
-
getLogger
public static Logger getLogger() throws SyncFactoryException
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
public static void setJNDIContext(Context ctx) throws SyncFactoryException
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:
SecurityManager.checkPermission(java.security.Permission)
-
-