com.bea.p13n.cache.spi
Class CacheProvider

java.lang.Object
  com.bea.p13n.cache.spi.CacheProvider

Direct Known Subclasses:

P13nCacheProvider

public abstract class CacheProvider
extends Object

Service-provider class for Cache implementations.

A Cache provider is a concrete subclass of this class that has a public no- argument constructor and implements the abstract methods specified below.

A CacheProvider implementer should generally package their provider in a jar. That jar should consist of any necessary classes (including, of course, an implementation of CacheProvider), as well as a file named META-INF/services/com.bea.p13n.cache.spi.CacheProvider. That services file should contain one or more class names, one per line, each of which should be a concrete CacheProvider implementation.

The provider jar(s) should then be deployed with the application by including the jar in the application's APP-INF/lib directory. Provider jars may also be included in the system classpath, although this changes the scoping of the provider class objects, and causes the provider implementations to be shared by multiple applications. It is suggested that provider implementors specify to their customers if such a configuration is suggested or supported.

On initialization, the CacheFactory will load all such providers, and additionally choose one provider to be the default. The default is set by the application's configuration or by a system property. Additionally, each named cache may choose a specific provider. See the following CacheFactory methods for further description of this: CacheFactory.getCacheProvider(String), CacheFactory.getDefaultProviderId(), and CacheFactory.getCache(String).

Implementations of the abstract methods of this class must be safe for use by multiple concurrent threads.

Configure caches to use the provider using the application's META-INF/p13n-cache-config.xml descriptor. Set the provider-id element on a set of caches, and/or use the default-provider-id.

Constructor Summary

CacheProvider()
Default constructor.

Method Summary

void	flushCache(String cacheName, Object key) Clear all clustered replicas of the Cache with the given name.
void	flushKeys(String cacheName, IKeySelector keySelector) Flush the keys indicated by IKeySelector in the local cache and any cluster cache that may exist.
abstract Cache	getCache(String cacheName, CacheConfig config) Return a Cache implementation with the given name.
abstract String	getProviderId() Name or identity of this provider.
protected String	getScopeIdentifier() Return a scope identifier that may be used by the CacheProvider to scope the Cache implementations returned by the CacheProvider.
abstract String	getVendorInfo() Returns the name of the organization, vendor, or company that provided this implementation.
abstract String	getVersionString() Return the version of this Cache provider implementation.
void	init() Initialize the CacheProvider.
void	release() Release all local resources associated with the CacheProvider.
void	releaseCache(Cache cache) Release all local resources associated with the specified Cache instance.
String	toString() Return a human readable String representation of this CacheProvider.

Methods inherited from class java.lang.Object

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

Constructor Detail

CacheProvider

public CacheProvider()

Default constructor.

Method Detail

init

public void init()

Initialize the CacheProvider. This method is called immediately after instantiation and before the provider is used.

This default implementation does nothing.

release

public void release()

Release all local resources associated with the CacheProvider.

The CacheFactory will call this method after the J2EE application for which this CacheProvider is providing Cache implementations is shutdown.

Releasing a CacheProvider makes it no longer usable; any attempt to use the CacheProvider may result in an exception.

This default implementation does nothing.

getCache

public abstract Cache getCache(String cacheName,
                               CacheConfig config)

Return a Cache implementation with the given name.

It is the responsibility of the CacheProvider to perform any Cache configuration before returning the Cache instance from this method. The Cache configuration mechanism is assumed to be vendor specific, however the CacheConfig object supplied in the method may be used to obtain suggested Cache configuration properties. This CacheConfig will be constructed from the p13n-cache-config.xml, if the cache is configured there.

Parameters

cacheName - the name of the Cache to return

config - suggested Cache configuration that may be used by the CacheProvider to configure the returned Cache; this may be ignored by the CacheProvider

Returns

a Cache instance identified by the given name

flushCache

public void flushCache(String cacheName,
                       Object key)

Clear all clustered replicas of the Cache with the given name.

This default implementation will use multicast to broadcast a flush signal to all peer nodes of the WebLogic cluster. Upon receipt of this signal, the instance of that cache will call either Cache.remove(Object) with the key, or Cache.clear() if key is null.

Providers with other flushing strategies should override this method without calling super.flushCache().

Parameters

cacheName - the name of the Cache to flush

key - an optional key; if not null, only the entry with the given key should be removed from all clustered replicas

releaseCache

public void releaseCache(Cache cache)

Release all local resources associated with the specified Cache instance.

Releasing a Cache reference makes it no longer usable; any attempt to use the reference may result in an exception.

This default implementation simply calls Cache.clear()

Providers with other strategies should override this method without calling super.releaseCache().

Parameters

cache - the Cache to release

getProviderId

public abstract String getProviderId()

Name or identity of this provider. This is used to uniquely identify a provider during configuration. It is suggested that this id be based on the vendor package namespace, such as "com.bea.p13n" (which is the name of the default P13nCacheProvider).

Returns

the provider id

getVendorInfo

public abstract String getVendorInfo()

Returns the name of the organization, vendor, or company that provided this implementation.

Returns

the name of the vendor that implemented this Cache provider

getVersionString

public abstract String getVersionString()

Return the version of this Cache provider implementation.

Returns

the version

getScopeIdentifier

protected final String getScopeIdentifier()

Return a scope identifier that may be used by the CacheProvider to scope the Cache implementations returned by the CacheProvider. Its use is not required. It is provided for those providers which may need some scoping hint from the server.

When used within a J2EE application, this scope identifier is the application name. When used outside an application context (i.e J2SE), this will be null.

One approach to scoping Cache implementation would be to fully qualify the cache name by append the scope identifier to the name passed to the getCache(String, CacheConfig) method.

Returns

the name of the cache provider's scope (usually an application name). May be null.

toString

public String toString()

Return a human readable String representation of this CacheProvider.

Overrides:

toString in class Object

Returns

a String representation of this object.

flushKeys

public void flushKeys(String cacheName,
                      IKeySelector keySelector)

Flush the keys indicated by IKeySelector in the local cache and any cluster cache that may exist. An implementation of the CacheProvider interface should override the default implementation of this method.

The default implementation will use multicast to broadcast a flush signal to all peer nodes of the WebLogic cluster. Upon receipt of this signal, the instance of that cache will call either Cache.remove(Object) with the key, or Cache.clear() if key is null.

Parameters

cacheName - the name of the cache to be flushed

keySelector - the set of keys to be flushed