Module java.sql.rowset

Package javax.sql.rowset.spi

Class SyncFactory

java.lang.Object

javax.sql.rowset.spi.SyncFactory

       public class SyncFactory extends Object
      

服务提供者接口（SPI）机制用于生成供离线RowSet对象使用的SyncProvider实例。 SyncProvider实例反过来提供RowSet对象需要用于填充自身数据的javax.sql.RowSetReader对象和需要将数据更改传播回底层数据源的javax.sql.RowSetWriter对象。

由于SyncFactory类中的方法都是静态的，因此在任何时候Java虚拟机中只有一个SyncFactory对象。这确保了存在一个单一的源，RowSet实现可以从中获取其SyncProvider实现。

1.0 概述

SyncFactory类提供了一个可用同步提供者实现（SyncProvider对象）的内部注册表。可以查询此注册表以确定哪些同步提供者可用。以下代码行获取当前注册的提供者的枚举。

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

所有标准的RowSet实现必须提供至少两个提供者：

• 一个乐观的提供者，用于与CachedRowSet实现或从中派生的实现一起使用
• 一个XML提供者，用于读取和写入XML，例如与WebRowSet对象一起使用

注意，JDBC RowSet实现包括SyncProvider实现RIOptimisticProvider和RIXmlProvider，它们满足此要求。

SyncFactory类提供了访问器方法，以帮助应用程序确定哪些同步提供者当前已注册到SyncFactory中。

其他方法允许RowSet持久性提供者在工厂机制中注册或取消注册。这允许在运行时向RowSet对象提供其他同步提供者实现。

应用程序可以应用一定程度的过滤来确定SyncProvider实现提供的同步级别。以下标准确定了提供者是否向RowSet对象提供：

1. 如果特定提供者由RowSet对象指定，并且SyncFactory不包含对此提供者的引用，则会抛出一个声明找不到同步提供者的SyncFactoryException。
2. 如果使用指定提供者实例化了RowSet实现，并且已正确注册了指定提供者，则提供请求的提供者。否则会抛出SyncFactoryException。
3. 如果RowSet对象未指定SyncProvider实现且没有其他可用的SyncProvider实现，则提供参考实现提供者。

2.0 注册SyncProvider实现

供应商和开发人员可以使用以下机制注册SyncProvider实现。

• 使用命令行
  在命令行上提供提供者的名称，这将将提供者添加到系统属性中。例如：

      -Drowset.provider.classname=com.fred.providers.HighAvailabilityProvider
   

• 使用标准属性文件
  参考实现目标是与J2SE 1.5一起发布，其中将包括一个可以手动编辑的附加资源文件。以下是参考实现中包含的属性文件示例：

     #默认的JDBC RowSet同步提供者列表
     #
  
     # 乐观同步提供者
     rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
     rowset.provider.vendor.0=Oracle Corporation
     rowset.provider.version.0=1.0
  
     # 使用标准XML模式的XML提供者
     rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
     rowset.provider.vendor.1=Oracle Corporation
     rowset.provider.version.1=1.0
   

  SyncFactory检查此文件并注册其中包含的SyncProvider实现。开发人员或供应商可以向此文件添加其他实现。例如，以下是可能的添加：

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

• 使用JNDI上下文
  可以在JNDI上下文中注册可用提供者，并且SyncFactory将尝试从该JNDI上下文加载SyncProvider实现。例如，以下代码片段在JNDI上下文中注册提供者实现。这通常是部署者会执行的操作。在此示例中，MyProvider正在注册到CosNaming命名空间上，这是J2EE资源使用的命名空间。

      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实例注册JNDI上下文。这允许SyncFactory在JNDI上下文中查找绑定的SyncProvider实现。

    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);
 

如果RowSet对象尝试获取MyProvider对象，SyncFactory将尝试定位它。首先在系统属性中搜索，然后查找资源文件，最后检查已设置的JNDI上下文。SyncFactory实例验证请求的提供者是SyncProvider抽象类的有效扩展，然后将其提供给RowSet对象。在以下代码片段中，创建一个新的CachedRowSet对象，并使用包含对MyProvider的绑定的env进行初始化。

    Hashtable env = new Hashtable();
    env.put(SyncFactory.ROWSET_SYNC_PROVIDER, "com.fred.providers.MyProvider");
    CachedRowSet crs = new com.sun.rowset.CachedRowSetImpl(env);
 

有关这些机制的更多详细信息，请参阅javax.sql.rowset.spi包规范。

自1.5版本起

参见：

• SyncProvider
• SyncFactoryException

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ROWSET_SYNC_PROVIDER	同步提供者实现名称的标准属性ID。
static final String	ROWSET_SYNC_PROVIDER_VERSION	同步提供者实现版本标签的标准属性ID。
static final String	ROWSET_SYNC_VENDOR	同步提供者实现供应商名称的标准属性ID。

Method Summary

Modifier and Type	Method	Description
static SyncProvider	getInstance(String providerID)	返回由providerID标识的SyncProvider实例。
static Logger	getLogger()	返回供应用程序检索由SyncProvider实现发布的同步事件的日志对象。
static Enumeration<SyncProvider>	getRegisteredProviders()	返回当前注册的同步提供者的枚举。
static SyncFactory	getSyncFactory()	返回SyncFactory单例。
static void	registerProvider(String providerID)	将给定的同步提供者添加到工厂注册表中。
static void	setJNDIContext(Context ctx)	设置可从JNDI命名空间中检索SyncProvider实现的初始JNDI上下文
static void	setLogger(Logger logger)	设置由SyncFactory提供的SyncProvider实现使用的日志对象。
static void	setLogger(Logger logger, Level level)	设置由SyncFactory SPI提供的SyncProvider实现使用的日志对象。
static void	unregisterProvider(String providerID)	从工厂SPI注册中删除指定的当前注册的同步提供者。

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

ROWSET_SYNC_PROVIDER

             public static final String ROWSET_SYNC_PROVIDER
            

同步提供者实现名称的标准属性ID。

参见：

• 常量字段值

ROWSET_SYNC_VENDOR

             public static final String ROWSET_SYNC_VENDOR
            

同步提供者实现供应商名称的标准属性ID。

参见：

• 常量字段值

ROWSET_SYNC_PROVIDER_VERSION

             public static final String ROWSET_SYNC_PROVIDER_VERSION
            

同步提供者实现版本标签的标准属性ID。

参见：

• 常量字段值

Method Details

registerProvider

             public static void registerProvider(String providerID) throws SyncFactoryException
            

将给定的同步提供者添加到工厂注册表中。在SyncProvider规范中提供了SyncProvider实现所需命名约定的指导方针。

绑定到JNDI上下文的同步提供者可以通过将SyncProvider实例绑定到JNDI命名空间来注册。

 
 SyncProvider p = new MySyncProvider();
 InitialContext ic = new InitialContext();
 ic.bind ("jdbc/rowset/MySyncProvider", p);
  

此外，应使用setJNDIContext方法为SyncFactory设置初始JNDI上下文。 SyncFactory利用此上下文搜索绑定到JNDI上下文及其子节点的可用SyncProvider对象。

参数：

providerID - 一个唯一的同步提供者ID的String对象

抛出：

SyncFactoryException - 如果尝试提供空或null提供者名称

参见：

• setJNDIContext(javax.naming.Context)

getSyncFactory

             public static SyncFactory getSyncFactory()
            

返回SyncFactory单例。

返回：

SyncFactory实例

unregisterProvider

             public static void unregisterProvider(String providerID) throws SyncFactoryException
            

从工厂SPI注册中删除指定的当前注册的同步提供者。

参数:

providerID - 同步提供程序的唯一标识符

抛出:

SyncFactoryException - 如果尝试注销未注册的SyncProvider实现。

getInstance

             public static SyncProvider getInstance(String providerID) throws SyncFactoryException
            

返回由providerID标识的SyncProvider实例。

参数:

providerID - 提供程序的唯一标识符

返回:

一个SyncProvider实现

抛出:

SyncFactoryException - 如果找不到SyncProvider，providerID为null>，或在尝试调用此提供程序时遇到错误。

getRegisteredProviders

             public static Enumeration<SyncProvider> getRegisteredProviders() throws SyncFactoryException
            

返回当前注册的同步提供程序的枚举。 RowSet实现可以使用枚举中的任何提供程序作为其SyncProvider对象。

至少应该可能使用JDBC驱动程序存储RowSet内容数据的参考同步提供程序。

返回:

枚举 已注册到此工厂的可用同步提供程序的枚举

抛出:

SyncFactoryException - 如果获取已注册提供程序时发生错误

setLogger

             public static void setLogger(Logger logger)
            

设置SyncFactory提供的SyncProvider实现要使用的日志记录对象。所有SyncProvider实现都可以将其事件记录到此对象，并且应用程序可以使用getLogger方法检索此对象的句柄。

此方法检查是否存在授予权限setSyncFactory的SQLPermission对象，然后允许方法成功。如果存在SecurityManager及其checkPermission方法拒绝调用setLogger，此方法将抛出java.lang.SecurityException。

参数:

logger - 一个Logger对象实例

抛出:

SecurityException - 如果存在SecurityManager及其checkPermission方法拒绝调用setLogger

NullPointerException - 如果logger为null

参见:

• SecurityManager.checkPermission(java.security.Permission)

setLogger

             public static void setLogger(Logger logger, Level level)
            

设置由SyncFactory SPI提供的SyncProvider实现使用的日志记录对象。所有SyncProvider实现都可以将其事件记录到此对象，并且应用程序可以使用getLogger方法检索此对象的句柄。

此方法检查是否存在授予权限setSyncFactory的SQLPermission对象，然后允许方法成功。如果存在SecurityManager及其checkPermission方法拒绝调用setLogger，此方法将抛出java.lang.SecurityException。

参数:

logger - 一个Logger对象实例

level - 指示所需日志程度的Level对象实例

抛出:

SecurityException - 如果存在SecurityManager及其checkPermission方法拒绝调用setLogger

NullPointerException - 如果logger为null

参见:

• SecurityManager.checkPermission(java.security.Permission)
• LoggingPermission

getLogger

             public static Logger getLogger() throws SyncFactoryException
            

返回应用程序用于检索由SyncProvider实现发布的同步事件的日志记录对象。

返回:

已指定用于由SyncProvider实现使用的Logger

抛出:

SyncFactoryException - 如果未设置日志记录对象。

setJNDIContext

             public static void setJNDIContext(Context ctx) throws SyncFactoryException
            

设置初始JNDI上下文，从中可以从JNDI命名空间检索SyncProvider实现

此方法检查是否存在授予权限setSyncFactory的SQLPermission对象，然后允许方法成功。如果存在SecurityManager及其checkPermission方法拒绝调用setJNDIContext，此方法将抛出java.lang.SecurityException。

参数:

ctx - 一个有效的JNDI上下文

抛出:

SyncFactoryException - 如果提供的JNDI上下文为null

SecurityException - 如果存在SecurityManager及其checkPermission方法拒绝调用setJNDIContext

参见:

• SecurityManager.checkPermission(java.security.Permission)