SyncFactory (Java Platform SE 6) - JDK 5 Documentation v6.0, Java 2 SDK 英文文档

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java™ Platform
Standard Ed. 6

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Class SyncFactory

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

public class SyncFactory
extends Object
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 implemtations 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 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.
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.
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=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

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

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

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 Summary
`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
`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 String ROWSET_SYNC_PROVIDER

The standard property-id for a synchronization provider implementation name.

ROWSET_SYNC_VENDOR

public static String ROWSET_SYNC_VENDOR

The standard property-id for a synchronization provider implementation vendor name.

ROWSET_SYNC_PROVIDER_VERSION

public static String ROWSET_SYNC_PROVIDER_VERSION

The standard property-id for a synchronization provider implementation version tag.

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

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.

Parameters:: logger - A Logger object instance

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.

Parameters:: logger - a Logger object instance; level - a Level object instance indicating the degree of logging required

getLogger

public static Logger getLogger()
                        throws SyncFactoryException

Returns the logging object for applications to retrieve synchronization events posted 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

Parameters:: ctx - a valid JNDI context
Throws:: SyncFactoryException - if the supplied JNDI context is null

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java™ Platform
Standard Ed. 6

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

SyncFactory (Java Platform SE 6) - JDK 5 Documentation v6.0, Java 2 SDK 英文文档

javax.sql.rowset.spi Class SyncFactory

1.0 Overview

2.0 Registering SyncProvider Implementations

ROWSET_SYNC_PROVIDER

ROWSET_SYNC_VENDOR

ROWSET_SYNC_PROVIDER_VERSION

registerProvider

getSyncFactory

unregisterProvider

getInstance

getRegisteredProviders

setLogger

setLogger

getLogger

setJNDIContext

javax.sql.rowset.spi
Class SyncFactory

2.0 Registering `SyncProvider` Implementations