Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.util
Class CacheFactory

java.lang.Object
  extended by com.jivesoftware.util.CacheFactory

public class CacheFactory
extends java.lang.Object

Creates Cache objects. The returned caches will either be local or clustered depending on the clustering enabled setting and a user's license.

When clustered caching is turned on, cache usage statistics for all caches that have been created are periodically published to the clustered cache named "opt-$cacheStats".


Nested Class Summary
static interface CacheFactory.ClusteringListener
          Listener interface for any object which needs to be notified when clustering starts or stops
 
Field Summary
static java.lang.String CLUSTER_PROPERTY_NAME
           
static com.tangosol.util.ConcurrentMap lockingMap
          A special map that can be used for doing cluster-wide locking.
 
Method Summary
static void addClusteringListener(CacheFactory.ClusteringListener listener)
           
static void clearCaches()
           
static Cache createCache(java.lang.String name)
          Returns the named cache, creating it as necessary.
static Cache createCache(java.lang.String name, int maxCacheSize, long maxLifetime)
          Returns the named cache, creating it as necessary, using the supplied name, size, and lifetime.
static void doClusterTask(com.tangosol.net.Invocable task)
          Invokes a task on other cluster members in an asynchronous fashion.
static void doClusterTask(com.tangosol.net.Invocable task, com.tangosol.net.InvocationObserver observer)
          Invokes a task on other cluster members in an asynchronous fashion.
static void doClusterTask(com.tangosol.net.Invocable task, com.tangosol.net.InvocationObserver observer, boolean sendAsynchronously)
          Invokes a task on other cluster members in an asynchronous fashion.
static void doRandomMemberClusterTask(com.tangosol.net.Invocable task, com.tangosol.net.InvocationObserver observer, boolean sendAsynchronously)
          Invokes a task on a random member of the cluster in an asynchronous fashion.
static java.util.Map doSynchronousClusterTask(com.tangosol.net.Invocable task, boolean includeLocalMember)
          Invokes a task on other cluster members synchronously and returns the result as a Map (method will not return until the task has been executed on each cluster member).
static Cache[] getAllCaches()
          Returns an array of all caches in the system.
static long getMaxLifetimeFromProperty(java.lang.String cacheName, long defaultLifetime)
          If a local property is found for the supplied name which specifies a value for cache entry lifetime, it is returned.
static int getMaxSizeFromProperty(java.lang.String cacheName, int defaultSize)
          If a local property is found for the supplied name which specifies a value for cache size, it is returned.
static void initialize()
          Starts the cluster service if clustering is enabled, and begins tracking cache statistics.
static boolean isClusteringEnabled()
          Returns true if cache clustering is enabled.
static boolean isSeniorClusterMember()
          Returns true if this member is the senior member in the cluster.
static void removeClusteringListener(CacheFactory.ClusteringListener listener)
           
static void saveCacheSettings()
          Saves current cache settings to local properties.
static void setClusteringEnabled(boolean enabled)
          Sets whether cache clustering should be enabled.
static void setMaxLifetimeProperty(java.lang.String cacheName, long lifetime)
          Sets a local property which overrides the maximum cache entry lifetime as configured in coherence-cache-config.xml for the supplied cache name.
static void setMaxSizeProperty(java.lang.String cacheName, int size)
          Sets a local property which overrides the maximum cache size as configured in coherence-cache-config.xml for the supplied cache name.
static void shutdownClusteringService()
          Shuts down the clustering service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLUSTER_PROPERTY_NAME

public static java.lang.String CLUSTER_PROPERTY_NAME

lockingMap

public static com.tangosol.util.ConcurrentMap lockingMap
A special map that can be used for doing cluster-wide locking. If clustering is disabled, the map will be a local ConcurrentMap that can be used for local locking.

Method Detail

getAllCaches

public static Cache[] getAllCaches()
Returns an array of all caches in the system.

Returns:
an array of all caches in the system.

createCache

public static Cache createCache(java.lang.String name,
                                int maxCacheSize,
                                long maxLifetime)
Returns the named cache, creating it as necessary, using the supplied name, size, and lifetime. Note the preferred method of configuring and creating caches is to define a cache mapping in coherence-cache-config.xml and to use CacheFactory.createCache(String).

Parameters:
name - the name of the cache to create.
maxCacheSize - the max size the cache can grow to, in bytes.
maxLifetime - the max number of milliseconds that objects can remain in cache.
Returns:
a cache with the specified properties.

createCache

public static Cache createCache(java.lang.String name)
Returns the named cache, creating it as necessary.

Parameters:
name - the name of the cache to create.

isClusteringEnabled

public static boolean isClusteringEnabled()
Returns true if cache clustering is enabled.

Returns:
true if clustering is enabled.

setClusteringEnabled

public static void setClusteringEnabled(boolean enabled)
Sets whether cache clustering should be enabled. Anytime this value is changed, the application server must be restarted

Parameters:
enabled - true if cache clustering should be enabled.

clearCaches

public static void clearCaches()

isSeniorClusterMember

public static boolean isSeniorClusterMember()
Returns true if this member is the senior member in the cluster. If clustering is not enabled, this method will also return true. This test is useful for tasks that should only be run on a single member in a cluster.

Returns:
true if this cluster member is the senior or if clustering is not enabled.

doClusterTask

public static void doClusterTask(com.tangosol.net.Invocable task)
Invokes a task on other cluster members in an asynchronous fashion. The task will not be executed on the local cluster member. If clustering is not enabled, this method will do nothing.

Parameters:
task - the task to be invoked on all other cluster members.

doClusterTask

public static void doClusterTask(com.tangosol.net.Invocable task,
                                 com.tangosol.net.InvocationObserver observer)
Invokes a task on other cluster members in an asynchronous fashion. The task will not be executed on the local cluster member. If clustering is not enabled, this method will do nothing.

Parameters:
task - the Invocable object to be invoked on all other cluster members.
observer - the InvocationObserver object that will receive notifications related to the task. This may be null if there is no wish to receive notifications related to the task.

doClusterTask

public static void doClusterTask(com.tangosol.net.Invocable task,
                                 com.tangosol.net.InvocationObserver observer,
                                 boolean sendAsynchronously)
Invokes a task on other cluster members in an asynchronous fashion. The task will not be executed on the local cluster member. If clustering is not enabled, this method will do nothing. If sendAsynchronously is set to true, then the invocable will be queued and sent to other cluster members on another thread. When false, the invokable will be sent to other cluster members immediately (network operation). When invocables are sent asynchronously, there is no fault-tolerance -- if the local cluster member dies before the invocable is sent to other cluster members then the invocable will never be executed across the cluster.

Parameters:
task - the Invocable object to be invoked on all other cluster members.
observer - the InvocationObserver object that will receive notifications related to the task. This may be null if there is no wish to receive notifications related to the task.
sendAsynchronously - true if the invocable should be added to a queue and sent to other cluster members on a queue. When false, the invocable will be sent to other cluster members immediately (network operation).

doRandomMemberClusterTask

public static void doRandomMemberClusterTask(com.tangosol.net.Invocable task,
                                             com.tangosol.net.InvocationObserver observer,
                                             boolean sendAsynchronously)
Invokes a task on a random member of the cluster in an asynchronous fashion. The task may be executed on the local cluster member. If clustering is not enabled, this method will do nothing. If sendAsynchronously is set to true, then the invocable will be queued and sent to other cluster members on another thread. When false, the invokable will be sent to other cluster members immediately (network operation). When invocables are sent asynchronously, there is no fault-tolerance -- if the local cluster member dies before the invocable is sent to other cluster members then the invocable will never be executed across the cluster.

Parameters:
task - the Invocable object to be invoked on a random cluster member.
observer - the InvocationObserver object that will receive notifications related to the task. This may be null if there is no wish to receive notifications related to the task.
sendAsynchronously - true if the invocable should be added to a queue and sent to other cluster members on a queue. When false, the invocable will be sent to other cluster members immediately (network operation).

doSynchronousClusterTask

public static java.util.Map doSynchronousClusterTask(com.tangosol.net.Invocable task,
                                                     boolean includeLocalMember)
Invokes a task on other cluster members synchronously and returns the result as a Map (method will not return until the task has been executed on each cluster member). The task will not be executed on the local cluster member. If clustering is not enabled, this method will return null.

Parameters:
task - the Invocable object to be invoked on all other cluster members.
includeLocalMember - true to run the task on the local member, false otherwise

shutdownClusteringService

public static void shutdownClusteringService()
Shuts down the clustering service. This method should be called when the Jive system is shutting down, and must not be called otherwise. By default, a ServletContextListener is registered to listen for the web application shutting down, and will automatically call this method. However, if the Jive system is being used in another context, such as a command-line application, this method should be called explicitly. Failing to call this method may temporarily impact cluster performance, as the system will have to do extra work to recover from a non-clean shutdown. If clustering is not enabled, this method will do nothing.


addClusteringListener

public static void addClusteringListener(CacheFactory.ClusteringListener listener)

removeClusteringListener

public static void removeClusteringListener(CacheFactory.ClusteringListener listener)

saveCacheSettings

public static void saveCacheSettings()
Saves current cache settings to local properties.


setMaxSizeProperty

public static void setMaxSizeProperty(java.lang.String cacheName,
                                      int size)
Sets a local property which overrides the maximum cache size as configured in coherence-cache-config.xml for the supplied cache name.

Parameters:
cacheName - the name of the cache to store a value for.
size - the maximum cache size.

setMaxLifetimeProperty

public static void setMaxLifetimeProperty(java.lang.String cacheName,
                                          long lifetime)
Sets a local property which overrides the maximum cache entry lifetime as configured in coherence-cache-config.xml for the supplied cache name.

Parameters:
cacheName - the name of the cache to store a value for.
lifetime - the maximum cache entry lifetime.

getMaxSizeFromProperty

public static int getMaxSizeFromProperty(java.lang.String cacheName,
                                         int defaultSize)
If a local property is found for the supplied name which specifies a value for cache size, it is returned. Otherwise, the defaultSize argument is returned.

Parameters:
cacheName - the name of the cache to look up a corresponding property for.
defaultSize - the value to return if no property is set.
Returns:
either the property value or the default value.

getMaxLifetimeFromProperty

public static long getMaxLifetimeFromProperty(java.lang.String cacheName,
                                              long defaultLifetime)
If a local property is found for the supplied name which specifies a value for cache entry lifetime, it is returned. Otherwise, the defaultLifetime argument is returned.

Parameters:
cacheName - the name of the cache to look up a corresponding property for.
defaultLifetime - the value to return if no property is set.
Returns:
either the property value or the default value.

initialize

public static void initialize()
Starts the cluster service if clustering is enabled, and begins tracking cache statistics. Before this method is called, any Caches returned by calls to createCache(java.lang.String, int, long) will return local caches. The process of starting clustering will recreate them as distributed caches. This is safer than the alternative - where clustering is started before any caches are created. In that scenario, cluster tasks can fire off in this process before it is safe for them to do so, and cluster wide deadlocks can occur.


Jive Forums Project Page

Copyright © 1999-2006 Jive Software.