com.bea.p13n.cache
Class CacheFactory

java.lang.Object
  com.bea.p13n.cache.CacheFactory

public class CacheFactory
extends Object

Factory to create Singleton Cache objects. This implementation can be used by clients running inside of the application context (eg, most EJBs) as well as clients running outside of that context (eg, JDBC Connection Pools).

The CacheFactory uses the CacheProvider configured for each named cache (or the default privider for the app) to retrieve Cache implementations by name.

See getCacheProvider(String) and getDefaultProviderId() and getCache(String) for descriptions of how the factory determines which Cache providers are used.

Method Summary

static boolean	cacheExists(String cacheName) Determine whether named cache exists (is known; that is, has been created).
static void	flush(String cacheName) Performs a cluster-aware flush of a given cache.
static void	flush(String cacheName, Serializable cacheKey) Performs a cluster-aware flush of the given cache's key.
static void	flushKeys(String cacheName, IKeySelector keySelector) Flush the keys indicated by IKeySelector in the local cache and in any cluster cache that may exist.
static Cache	getCache(String name) Create or access an existing Cache.
static String[]	getCacheNames() Returns the names of all known Caches.
static CacheProvider	getCacheProvider() Return the default CacheProvider used by this factory.
static CacheProvider	getCacheProvider(String providerId) Return a cache provider based on the provider id.
static String	getDefaultProviderId() Return the id of the default provider.
static void	removeCache(String cacheName) Clear and remove a cache from the system.

Methods inherited from class java.lang.Object

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

Method Detail

getCacheNames

public static String[] getCacheNames()

Returns the names of all known Caches.

cacheExists

public static boolean cacheExists(String cacheName)

Determine whether named cache exists (is known; that is, has been created).

Returns

true if exists, false otherwise

getCache

public static Cache getCache(String name)

Create or access an existing Cache.

If the cache has been pre-configured, then create an instance of a cache with those configured parameters and return it. If the cache has not been pre-configured, then create a cache with default parameters (defined in CacheDefaults) and return it.

The cache will be creaed by the configured instance of the CacheProvider, which may be configured on a per-named-cache basis (in p13n-cache-config.xml), or by the configured default provider (See getDefaultProviderId()).

If the cache exists already in the CacheFactory's collection (eg, it has been created by a previous call to CacheFactory.getCache()), then that same cache will be returned.

Parameters

name - the name of the cache to create or retrieve

Returns

the cache that was created or retrieved.

See Also

CacheDefaults

removeCache

public static void removeCache(String cacheName)

Clear and remove a cache from the system.

Parameters

cacheName - The name of the cache to remove.

flush

public static void flush(String cacheName,
                         Serializable cacheKey)

Performs a cluster-aware flush of the given cache's key. Flush causes the given key to be removed from the named cache, first locally (the cache on this node), and then on all other nodes of the cluster.

Flushing a cache key will cause CacheFactory.getCache(cacheName).remove(cacheKey) to be called on each node in the cluster. Flushing an entire cache calls CacheFactory.removeCache(cacheName) on each cluster node.

The keys for caches to be flushed must be Serializable so the key can be broadcast to other nodes. Cache entries with non-serializable keys can not be flushed in this way.

The assumption inherrent in this design is that each node will retrieve and cache its own data. When the "real" data (i.e. in a database) changes, you want to clear all caches, cluster-wide, so on next access the cache will be empty, causing that node to re-fetch the data from the store.

The pattern for cached data that needs to be cluster-aware is something like:

  database.update( newData );  // change backing data
  CacheFactory.flush( "myCache", "myData" );  // cluster-wide flush
  CacheFactory.getCache( "myCache" ).put( "myData", newData );  // cache locally
 

Parameters

cacheName - the name of the cache to be flushed

cacheKey - the key in that cache to remove. If null, clear the entire cache.

See Also

flush(String)

flush

public static void flush(String cacheName)

Performs a cluster-aware flush of a given cache. Flush causes the given cache to be cleared and removed, first locally (the cache on this node), and then on all other nodes of the cluster. Same as flush(cacheName,null).

getDefaultProviderId

public static String getDefaultProviderId()

Return the id of the default provider. The following logic is used to determine the default provider:

1. If a provider id is specified in the p13n-cache-config.xml file, and a provider with that id was successfully loaded, then it is taken to be the default @{link CacheProvider}. Note that this way, each application can specify which cache provider it will use as default.
2. Otherwise, if the system property com.bea.p13n.cache.spi.CacheProvider is defined and is set to the id of a provider which was successfully loaded, then this is taken to be the default @{link CacheProvider}. Note that as this is a System property, it applies to the entire server.
3. If the above does not produce a default, the P13nCacheProvider is used as the default.

Returns

the default provider's id

getCacheProvider

public static CacheProvider getCacheProvider()

Return the default CacheProvider used by this factory. This is equivalent to getCacheProvider( getDefaultProviderId()() ).

Returns

the default CacheProvider

getCacheProvider

public static CacheProvider getCacheProvider(String providerId)

Return a cache provider based on the provider id. If no providers with the given id are installed or configured, the default configured provider is returned, based on the return from getDefaultProviderId().

The first invocation of this method loads Cache providers as follows:

1. The P13nCacheProvider is always loaded.
2. If Cache provider classes have been installed in JAR files that are visible to the application class loader (i.e. in APP-INF/lib or the system classpath), and the JAR file contains a file named META-INF/services/com.bea.p13n.cache.spi.CacheProvider, then the classes nameed in that file are loaded and initialized. Note that several providers may be loaded in this way.

Subsequent invocations of this method return the provider that was returned by the first invocation.

If the provider ID requested is not available (was not loaded or did not load successfully), then this method will return the default provier, as described by getDefaultProviderId().

Parameters

providerId - the ID of the requested provider. Null indicates the default provider.

Returns

the cache provider for the given id, if configured (otherwise the default provider)

flushKeys

public static void flushKeys(String cacheName,
                             IKeySelector keySelector)

Flush the keys indicated by IKeySelector in the local cache and in any cluster cache that may exist.

Parameters

cacheName - the name of the cache to be flushed

keySelector - the set of keys to be flushed