Skip navigation links

oracle.wcps.cache
Class CacheFactory

java.lang.Object
oracle.wcps.cache.CacheFactory

public abstract class CacheFactory

extends java.lang.Object

Factory to create/retrieve Singleton Cache objects.

There are two types of caches - normal caches and local caches.

Normal caches may (or may not) be remote or external to this VM (and are thus also externally managed). As the cached objects are often held remotely, these caches require the keys and values that they hold to be Serializable. The principal/preferred implementation for these caches is Coherence.

Local caches are based on local in-memory Maps, and thus do not have any remote capability, etc. So local caches do not have any serializable restrictions.

To use Coherence caches, the Coherence classes must be accessible via the same ClassLoader where this CacheFactory class is loaded. Also, a cache-config file named factoryName-coherence-cache-config.xml must also be accessible via the same loader (where factoryName is the argument to getInstance, and the file conforms to cache-config.dtd) . If Coherence is not available, the configuration file is not found, or there are problems in loading the configuration, then local caches will be used.

Each Coherence-backed CacheFactory will construct a DefaultConfigurableCacheFactory with the factoryName-coherence-cache-config.xml as a parameter. Note that, in an application with multiple cache factory names, a tangasol-coherence-override.xml file will likely be required to specify service-type names for each service in the cache-config file. This is necessary to keep the caches and their configurations separate from each other. For example, if you have one factoryName=wcps which uses a local-scheme with the default service-name, and a factoryName=foo which also uses a local-scheme, then foo's local-service will probably need a unique service-name and that service-type will need to be defined in a tangasol-coherence-override.xml file. See the Coherence documentation for more information.

It may also be advisable to use something like WebLogic's prefer-application-resources in your Ear's weblogic-application.xml descriptor in order to isolate configuration for your application from other applications (and the server's classpath). For example:

   <prefer-application-resources>
     <resource-name>wcps-coherence-cache-config.xml</resource-name>
     <resource-name>foo-coherence-cache-config.xml</resource-name>
     <resource-name>tangosol-coherence-override.xml</resource-name>
   </prefer-application-resources>
 

The above assumes that the caches are configured per-ear, and that the named resources (config files) are accessible via the ear's classloader, for example APP-INF/classes/wcps-coherence-cache-config.xml.

Caches have their configuration exposed via CacheConfig, although regular caches may not obey any of the configuration settings, as they are intended to be managed externally. Local caches always observe configuration changes.

CacheConfig is a JMX MXBean, so management of caches (especially local caches) can be done via jconsole (for example). The MBean ObjectName is oracle.wcps.cache:name=factoryName.cacheName

If the system property oracle.wcps.cache.forceLocalCaches is set to true (before the first use of this class), then all caches will be forced to be local, regardless of any other configuration.
If the system property oracle.wcps.cache.localCachesInactive is set to true, the default initial value for the isActive attribute for local caches will be false.
To disable caching system-wide, set both oracle.wcps.cache.forceLocalCaches and oracle.wcps.cache.localCachesInactive to true (and don't change the cache isActive property after that via code or via JMX).

Field Summary

static java.lang.String	FORCE_LOCAL_CACHES system property - set to true to force use of local caches system-wide
static java.lang.String	LOCAL_CACHES_INACTIVE System property - set to true to disable all local caches system-wide.
protected CacheFactory	localInstance
static java.lang.String	MBEAN_BASE_NAME CacheConfig ObjectName in the platform mbean server is MBEAN_BASE_NAME + factoryName.cacheName (oracle.wcps.cache:name=factoryName.cacheName) factoryName is the arg to CacheFactory.getInstance(factoryName) cacheName is the name of the cache.

Constructor Summary

protected

CacheFactory(java.lang.String factoryName)

Method Summary

boolean	cacheExists(java.lang.String name) Is this cache name known.
protected abstract Cache<?,?>	createCache(java.lang.String name)
Cache<? extends java.io.Serializable,? extends java.io.Serializable>	getCache(java.lang.String name) Create or access an existing Cache.
<K extends java.io.Serializable,V extends java.io.Serializable> Cache<K,V>	getCache(java.lang.String name, java.lang.Class<K> keyType, java.lang.Class<V> valueType) Create or retrieve a cache.
java.util.Set<java.lang.String>	getCacheNames() Return all known caches that have been accessed by this instance's getCache method.
static CacheFactory	getInstance(java.lang.String factoryName) Return the named cache factory instance.
Cache<?,?>	getLocalCache(java.lang.String name) Create or access an existing LOCAL Cache.
<K,V> Cache<K,V>	getLocalCache(java.lang.String name, java.lang.Class<K> keyType, java.lang.Class<V> valueType) Create or retrieve a local cache.
java.util.Set<java.lang.String>	getLocalCacheNames() Return all local caches that have been created by this instance's getLocalCache method.
java.lang.String	getName()
abstract boolean	isLocal() Returns true if the caches are all local.
boolean	localCacheExists(java.lang.String name) Is this local cache name known.

Methods inherited from class java.lang.Object

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

Field Detail

MBEAN_BASE_NAME

public static final java.lang.String MBEAN_BASE_NAME

CacheConfig ObjectName in the platform mbean server is MBEAN_BASE_NAME + factoryName.cacheName (oracle.wcps.cache:name=factoryName.cacheName) factoryName is the arg to CacheFactory.getInstance(factoryName) cacheName is the name of the cache.

FORCE_LOCAL_CACHES

public static final java.lang.String FORCE_LOCAL_CACHES

system property - set to true to force use of local caches system-wide

See Also:

Constant Field Values

LOCAL_CACHES_INACTIVE

public static final java.lang.String LOCAL_CACHES_INACTIVE

System property - set to true to disable all local caches system-wide. When set to true, sets the _initial_ value of the isActive configuration property to false. Note that this does not force all caches off, but simply changes the default initial isActive value.

See Also:

Constant Field Values

localInstance

protected final CacheFactory localInstance

Constructor Detail

CacheFactory

protected CacheFactory(java.lang.String factoryName)

Method Detail

getInstance

public static final CacheFactory getInstance(java.lang.String factoryName)

Return the named cache factory instance. Will never return null.

getName

public final java.lang.String getName()

createCache

protected abstract Cache<?,?> createCache(java.lang.String name)

isLocal

public abstract boolean isLocal()

Returns true if the caches are all local.

Returns:

true if calls to getCache will always return the same type of local caches as calls to getLocalCache.

cacheExists

public final boolean cacheExists(java.lang.String name)

Is this cache name known. Note that this may return false when a cache does exist but is managed externally. It is mainly an indicator (if false) that a cache (or a proxy to an external cache) will be created when getCache is called.

localCacheExists

public final boolean localCacheExists(java.lang.String name)

Is this local cache name known.

getCache

public final Cache<? extends java.io.Serializable,? extends java.io.Serializable> getCache(java.lang.String name)

Create or access an existing Cache. Will never return null, will always return some instance of a cache.

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

Parameters:

name - the name of the cache to create or retrieve

Returns:

the cache that was created or retrieved.

Throws:

java.lang.IllegalArgumentException - if a LOCAL cache with this name already exists

getLocalCache

public final Cache<?,?> getLocalCache(java.lang.String name)

Create or access an existing LOCAL Cache. Will never return null, will always return some instance of a cache.

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

Parameters:

name - the name of the local cache to create or retrieve

Returns:

the cache that was created or retrieved.

Throws:

java.lang.IllegalArgumentException - if a Serializable cache with this name already exists

getCache

public final <K extends java.io.Serializable,V extends java.io.Serializable> Cache<K,V> getCache(java.lang.String name,
                                                                                                 java.lang.Class<K> keyType,
                                                                                                 java.lang.Class<V> valueType)

Create or retrieve a cache. Will never return null (will always create a cache if it does not already exist).

The resulting cache will not be type safe (checked) - this is simply a convenience to allow you to avoid excess generic-related casts in your code.

Type Parameters:

K - key type

V - value type

Parameters:

name - cache name

keyType - key type class object

valueType - value type class object

Returns:

the cache that was created or retrieved

Throws:

java.lang.IllegalArgumentException - if a LOCAL cache with this name already exists

getLocalCache

public final <K,V> Cache<K,V> getLocalCache(java.lang.String name,
                                            java.lang.Class<K> keyType,
                                            java.lang.Class<V> valueType)

Create or retrieve a local cache. Will never return null (will always create a cache if it does not already exist).

The resulting cache will not be type safe (checked) - this is simply a convenience to allow you to avoid excess generic-related casts in your code.

Type Parameters:

K - key type

V - value type

Parameters:

name - cache name

keyType - key type class object

valueType - value type class object

Returns:

the cache that was created or retrieved

Throws:

java.lang.IllegalArgumentException - if a Serializable cache with this name already exists

getCacheNames

public java.util.Set<java.lang.String> getCacheNames()

Return all known caches that have been accessed by this instance's getCache method. Note that this may not return names of caches that do exist but are managed externally and unknown to this instance. It is mainly an indicator that a cache (or a proxy to an external cache) has been created by getCache.

Returns:

A copy of the caches know to this instance. This set is a copy, and as such is not backed by the cache facotry (changes after this call will not be reflected as updates to the set.

getLocalCacheNames

public java.util.Set<java.lang.String> getLocalCacheNames()

Return all local caches that have been created by this instance's getLocalCache method.

Returns:

A copy of the local caches know to this instance. This set is a copy, and as such is not backed by the cache facotry (changes after this call will not be reflected as updates to the set.

Skip navigation links