SyncFactory (Java Platform SE 8 )
Keywords: javax.sql.rowset.spi.SyncFactory class
Date: 2018-07-01

compact3
javax.sql.rowset.spi

## Class SyncFactory

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

-     public class SyncFactory
      extends Object

  The Service Provider Interface (SPI) mechanism that generates `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

  The `SyncFactory` 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
  Note that the JDBC RowSet Implementations include the `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:

  1. If a particular provider is specified by a `RowSet` object, and the `SyncFactory` does not contain a reference to this provider, a `SyncFactoryException` is thrown stating that the synchronization provider could not be found.
  2. If a `RowSet` implementation is instantiated with a specified provider and the specified provider has been properly registered, the requested provider is supplied. Otherwise a `SyncFactoryException` is thrown.
  3. If a `RowSet` object does not specify a `SyncProvider` implementation and no additional `SyncProvider` 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

    The `SyncFactory` checks this file and registers the `SyncProvider` 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 the `SyncFactory` will attempt to load `SyncProvider` 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);

  Next, an application will register the JNDI context with the `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.
  See Also:
    `SyncProvider`, `SyncFactoryException`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ROWSET_SYNC_PROVIDER` The standard property-id for a synchronization provider implementation name.
    `static String` | `ROWSET_SYNC_PROVIDER_VERSION` The standard property-id for a synchronization provider implementation version tag.
    `static String` | `ROWSET_SYNC_VENDOR` The standard property-id for a synchronization provider implementation vendor name.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SyncProvider` | `getInstance(String providerID)` Returns the `SyncProvider` instance identified by providerID.
    `static Logger` | `getLogger()` 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 SyncFactory` | `getSyncFactory()` Returns the `SyncFactory` singleton.
    `static void` | `registerProvider(String providerID)` Adds the 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 namespace
    `static void` | `setLogger(Logger logger)` Sets the logging object to be used by the `SyncProvider` implementation provided by the `SyncFactory`.
    `static void` | `setLogger(Logger logger, Level level)` Sets the logging object that is used by `SyncProvider` implementations provided by the `SyncFactory` SPI.
    `static void` | `unregisterProvider(String providerID)` Removes the designated currently registered synchronization provider from the Factory SPI register.

    - ### Methods inherited from class java.lang.Object

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

- - ### 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 the given synchronization provider to the factory register. Guidelines are provided in the `SyncProvider` specification for the required naming conventions for `SyncProvider` 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);

      Furthermore, an initial JNDI context should be set with the `SyncFactory` using the `setJNDIContext` method. The `SyncFactory` leverages this context to search for available `SyncProvider` objects bound to the JNDI context and its child nodes.
      Parameters:
        `providerID` - A `String` 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:
        `setJNDIContext(javax.naming.Context)`

    - #### getSyncFactory

          public static SyncFactory getSyncFactory()

      Returns the `SyncFactory` singleton.
      Returns:
        the `SyncFactory` instance

    - #### 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 the `SyncProvider` 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 is `null`, 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. A `RowSet` implementation may use any provider in the enumeration as its `SyncProvider` 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

          public static void setLogger(Logger logger)

      Sets the logging object to be used by the `SyncProvider` implementation provided by the `SyncFactory`. All `SyncProvider` implementations can log their events to this object and the application can retrieve a handle to this object using the `getLogger` method.

      This method checks to see that there is an `SQLPermission` object which grants the permission `setSyncFactory` before allowing the method to succeed. If a `SecurityManager` exists and its `checkPermission` method denies calling `setLogger`, this method throws a `java.lang.SecurityException`.

      Parameters:
        `logger` - A Logger object instance
      Throws:
        `SecurityException` - if a security manager exists and its `checkPermission` method denies calling `setLogger`
        `NullPointerException` - 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 by `SyncProvider` implementations provided by the `SyncFactory` SPI. All `SyncProvider` implementations can log their events to this object and the application can retrieve a handle to this object using the `getLogger` method.

      This method checks to see that there is an `SQLPermission` object which grants the permission `setSyncFactory` before allowing the method to succeed. If a `SecurityManager` exists and its `checkPermission` method denies calling `setLogger`, this method throws a `java.lang.SecurityException`.

      Parameters:
        `logger` - a Logger object instance
        `level` - a Level object instance indicating the degree of logging required
      Throws:
        `SecurityException` - if a security manager exists and its `checkPermission` method denies calling `setLogger`
        `NullPointerException` - 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 `Logger` that has been specified for use by `SyncProvider` implementations
      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 namespace

      This method checks to see that there is an `SQLPermission` object which grants the permission `setSyncFactory` before allowing the method to succeed. If a `SecurityManager` exists and its `checkPermission` method denies calling `setJNDIContext`, this method throws a `java.lang.SecurityException`.

      Parameters:
        `ctx` - a valid JNDI context
      Throws:
        `SyncFactoryException` - if the supplied JNDI context is null
        `SecurityException` - if a security manager exists and its `checkPermission` method denies calling `setJNDIContext`
      See Also:
        `SecurityManager.checkPermission(java.security.Permission)`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2018, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.