javax.sql.rowset.spi
类 SyncFactory

java.lang.Object
  javax.sql.rowset.spi.SyncFactory

public class SyncFactory
extends Object

该服务提供者接口 (SPI) 机制可以生成由非连接 RowSet 对象使用的 SyncProvider 实例。SyncProvider 实例依次提供 javax.sql.RowSetReader 对象和 javax.sql.RowSetWriter 对象，RowSet 对象需要前者来使用数据填充本身，需要后者来将对其数据的更改传播回底层数据源。

因为 SyncFactory 类中的方法都是静态的，所以每个 Java VM 在任意一个时刻内仅有一个 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 一起发行，这将包含一个可以手工编辑的附加资源文件。下面是参考实现中包含的属性文件示例：

     #Default JDBC RowSet sync providers listing
     #
  
     # Optimistic synchronization provider
     rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
     rowset.provider.vendor.0=Sun Microsystems Inc
     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=Sun Microsystems Inc.
     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 对象。在以下代码片段中，使用 env 创建并初始化一个新的 CachedRowSet 对象，该对象包含对 MyProvider 的绑定。

    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 包规范中提供了关于这些机制的更多详细信息。

另请参见：

SyncProvider, SyncFactoryException

字段摘要

static String	ROWSET_SYNC_PROVIDER 用于同步提供者实现名称的标准属性 id。
static String	ROWSET_SYNC_PROVIDER_VERSION 用于同步提供者实现版本标记的标准属性 id。
static String	ROWSET_SYNC_VENDOR 用于同步提供者实现供应商名称的标准属性 id。

方法摘要

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 上下文，通过该上下文可以从 JNDI 名称空间获取 SyncProvider 实现
static void	setLogger(Logger logger) 设置 SyncFactory 提供的 SyncProvider 实现所使用的日志对象。
static void	setLogger(Logger logger, Level level) 设置 SyncFactory SPI 提供的 SyncProvider 实现所使用的日志对象。
static void	unregisterProvider(String providerID) 从工厂 SPI 注册器移除指派的当前已注册同步提供者。

从类 java.lang.Object 继承的方法

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

字段详细信息

ROWSET_SYNC_PROVIDER

public static String ROWSET_SYNC_PROVIDER

用于同步提供者实现名称的标准属性 id。

ROWSET_SYNC_VENDOR

public static String ROWSET_SYNC_VENDOR

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

ROWSET_SYNC_PROVIDER_VERSION

public static String ROWSET_SYNC_PROVIDER_VERSION

用于同步提供者实现版本标记的标准属性 id。

方法详细信息

registerProvider

public static void registerProvider(String providerID)
                             throws SyncFactoryException

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

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

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

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

参数：

providerID - 一个 String 对象，具有注册的同步提供者的唯一 ID

抛出：

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

另请参见：

setJNDIContext(javax.naming.Context)

getSyncFactory

public static SyncFactory getSyncFactory()

返回一个 SyncFactory。

返回：

SyncFactory 实例

unregisterProvider

public static void unregisterProvider(String providerID)
                               throws SyncFactoryException

从工厂 SPI 注册器移除指派的当前已注册同步提供者。

参数：

providerID - 同步提供者的唯一 id

抛出：

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

getInstance

public static SyncProvider getInstance(String providerID)
                                throws SyncFactoryException

返回 providerID 标识的 SyncProvider 实例。

参数：

providerID - 提供者的唯一标识符

返回：

SyncProvider 实现

抛出：

SyncFactoryException - 如果无法找到 SyncProvider，或者尝试调用此提供者时遇到某种错误。

getRegisteredProviders

public static Enumeration<SyncProvider> getRegisteredProviders()
                                                        throws SyncFactoryException

返回当前已注册的同步提供者所组成的枚举。RowSet 实现可以将枚举中的任何提供者用作其 SyncProvider 对象。

至少应该可以使用允许用 JDBC 驱动程序存储 RowSet 内容数据的那个同步提供者。

返回：

Enumeration 向此工厂注册的可用同步提供者所组成的枚举

抛出：

SyncFactoryException

setLogger

public static void setLogger(Logger logger)

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

参数：

logger - Logger 对象实例

setLogger

public static void setLogger(Logger logger,
                             Level level)

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

参数：

logger - Logger 对象实例

level - 指示所需日志等级的 Level 对象实例

getLogger

public static Logger getLogger()
                        throws SyncFactoryException

返回应用程序的日志对象，以获取 SyncProvider 实现发送的同步事件。

抛出：

SyncFactoryException - 如果未设置任何日志对象。

setJNDIContext

public static void setJNDIContext(Context ctx)
                           throws SyncFactoryException

设置初始 JNDI 上下文，通过该上下文可以从 JNDI 名称空间获取 SyncProvider 实现

参数：

ctx - 有效的 JNDI 上下文

抛出：

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