Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright © 2006 BEA Systems, Inc. All Rights Reserved
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006 BEA Systems, Inc. All Rights Reserved