com.tangosol.net

Class CacheFactory

java.lang.Object

com.tangosol.util.Base

com.tangosol.net.CacheFactory

public abstract class CacheFactory
extends Base

Factory for the Coherence™ cache product.

One of the most common functions provided by the CacheFactory is ability to obtain an instance of a cache. To get a cache reference use the getCache(String, ClassLoader) or getCache(String) methods.

When a cache retrieved by any of the above methods is no longer used, it is recommended to call releaseCache(NamedCache) to release the associated resources. To destroy all instances of the cache across the cluster, use destroyCache(NamedCache).

Applications that require more control when obtaining cache and service references should use the CacheFactoryBuilder API.

Author:

cp, gg 2001.12.14

Nested Class Summary

Nested classes/interfaces inherited from class com.tangosol.util.Base

Base.LoggingWriter, Base.StackFrame

Field Summary

Fields

Modifier and Type	Field and Description
static String	PRODUCT The product name string.
static String	VERSION Software version string.

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Constructor Summary

Constructors

Constructor and Description
CacheFactory()

Method Summary

Modifier and Type	Method and Description
static boolean	commitTransactionCollection(Collection collCaches, int cRetry) Commit the transaction represented by a collection of TransactionMap objects.
static void	destroyCache(NamedCache cache) Releases and destroys the specified NamedCache.
static Cluster	ensureCluster() Obtain a Cluster object running Coherence services.
static <K,V> NamedCache<K,V>	getCache(String sName) Return an instance of an cache configured by the current ConfigurableCacheFactory This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...)
static <K,V> NamedCache<K,V>	getCache(String sName, ClassLoader loader) Return an instance of a cache configured by the current ConfigurableCacheFactory with a specific ClassLoader no options.
static <K,V> NamedCache<K,V>	getCache(String sName, ClassLoader loader, NamedCache.Option... options) Return an instance of a cache configured by the current ConfigurableCacheFactory with a specific ClassLoader and NamedCache.Options This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...)
static <K,V> NamedCache<K,V>	getCache(String sName, NamedCache.Option... options) Return an instance of an cache configured by the current ConfigurableCacheFactory, using the specified NamedCache.Options.
static CacheFactoryBuilder	getCacheFactoryBuilder() Obtain the CacheFactoryBuilder singleton using the configuration info from the "cache-factory-builder-config" element.
static XmlElement	getCacheFactoryBuilderConfig() Return the cache factory builder configuration as defined by the "cache-factory-builder-config" element in the tangosol-coherence.xml configuration file.
static Cluster	getCluster() Return a Cluster object for Coherence services.
static XmlElement	getClusterConfig() Return the default cluster configuration as defined by the "cluster-config" element in the tangosol-coherence.xml configuration file.
static ConfigurableCacheFactory	getConfigurableCacheFactory() Obtain the ConfigurableCacheFactory singleton using the configuration info from the "configurable-cache-factory-config" element located in the tangosol-coherence.xml configuration file.
static ConfigurableCacheFactory	getConfigurableCacheFactory(ClassLoader loader) Obtain the ConfigurableCacheFactory associated with the specified class loader.
static XmlElement	getConfigurableCacheFactoryConfig() Return the configurable cache factory configuration as defined by the "configurable-cache-factory-config" element in the tangosol-coherence.xml configuration file.
static XmlElement	getDistributedCacheConfig() Return the default distributed (partitioned) cache configuration.
static String	getEdition() Returns the edition currently loaded based on the operational configuration.
static TransactionMap	getLocalTransaction(NamedCache map) Factory method returning an instance of the TransactionMap that is based on the specified NamedCache and is local to this JVM.
static XmlElement	getLoggingConfig() Return the configuration info for the logging facility as defined by the "logging-config" element in the tangosol-coherence.xml configuration file.
static XmlElement	getManagementConfig() Return the management framework configuration.
static XmlElement	getReplicatedCacheConfig() Return the default replicated cache configuration.
static XmlElement	getSecurityConfig() Return the security framework configuration.
static Service	getService(String sName) Return an instance of a service configured by the current ConfigurableCacheFactory.
static XmlElement	getServiceConfig(String sServiceType) Return the configuration for the specified service type.
static <K,V> NamedCache<K,V>	getTypedCache(String sCacheName, ClassLoader loader, TypeAssertion<K,V> assertion) Return an instance of a cache with the given name satisfying the specified TypeAssertion.
static <K,V> NamedCache<K,V>	getTypedCache(String sCacheName, TypeAssertion<K,V> assertion) Return an instance of a cache with the given name satisfying the specified TypeAssertion.
static boolean	isLogEnabled(int nSeverity) Check if a message of the specified severity level will be logged using the Coherence logging facility.
static void	log(String sMessage, int nSeverity) Log a message using Coherence logging facility which is driven by the "logging-config" element located in the tangosol-coherence.xml configuration file.
static void	main(String[] asArg) Invoke the Coherence command line tool.
static void	releaseCache(NamedCache cache) Release local resources associated with the specified instance of the cache.
static void	rollbackTransactionCollection(Collection collCaches) Roll back the transaction represented by a collection of TransactionMap objects.
static void	setCacheFactoryBuilder(CacheFactoryBuilder cfb) Specify a singleton CacheFactoryBuilder.
static void	setCacheFactoryBuilderConfig(XmlElement xmlCfg) Set the cache factory builder configuration.
static void	setConfigurableCacheFactory(ConfigurableCacheFactory factory) Deprecated. As of 12.2.1 deprecated with no replacement
static void	setConfigurableCacheFactoryConfig(XmlElement xmlCfg) Set the configurable cache factory configuration.
static void	setLoggingConfig(XmlElement xmlCfg) Set the configuration info for the logging facility.
static void	setManagementConfig(XmlElement xmlCfg) Set the management framework configuration.
static void	setSecurityConfig(XmlElement xmlCfg) Set the security framework configuration.
static void	setServiceConfig(String sServiceType, XmlElement xmlCfg) Set the configuration for the specified service type.
static void	shutdown() Shutdown all clustered services.

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getProcessRandom, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

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

Field Detail

PRODUCT

public static final String PRODUCT

The product name string.

VERSION

public static final String VERSION

Software version string.

Constructor Detail

CacheFactory

public CacheFactory()

Method Detail

getCacheFactoryBuilder

public static CacheFactoryBuilder getCacheFactoryBuilder()

Obtain the CacheFactoryBuilder singleton using the configuration info from the "cache-factory-builder-config" element.

Returns:

an instance of CacheFactoryBuilder

Since:

Coherence 3.5.1

setCacheFactoryBuilder

public static void setCacheFactoryBuilder(CacheFactoryBuilder cfb)

Specify a singleton CacheFactoryBuilder.

Parameters:

cfb - an instance of CacheFactoryBuilder

Since:

Coherence 3.5.1

getConfigurableCacheFactory

public static ConfigurableCacheFactory getConfigurableCacheFactory()

Obtain the ConfigurableCacheFactory singleton using the configuration info from the "configurable-cache-factory-config" element located in the tangosol-coherence.xml configuration file.

Returns:

an instance of ConfigurableCacheFactory

Since:

Coherence 2.2

getConfigurableCacheFactory

public static ConfigurableCacheFactory getConfigurableCacheFactory(ClassLoader loader)

Obtain the ConfigurableCacheFactory associated with the specified class loader.

Note: if setConfigurableCacheFactory(com.tangosol.net.ConfigurableCacheFactory) has been called, the same factory instance will be returned.

Parameters:

loader - the class loader for which to return a configurable cache factory

Returns:

the configurable cache factory for the specified loader

setConfigurableCacheFactory

public static void setConfigurableCacheFactory(ConfigurableCacheFactory factory)

Deprecated. As of 12.2.1 deprecated with no replacement

Specify a singleton of ConfigurableCacheFactory.

Parameters:

factory - an instance of ConfigurableCacheFactory

Since:

Coherence 2.2

getService

public static Service getService(String sName)

Return an instance of a service configured by the current ConfigurableCacheFactory. This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureService(String) method.

Parameters:

sName - service name (unique for a given configurable cache factory). If the Service with the specified name already exists, a reference to the same object will be returned

Returns:

the Service object

Since:

Coherence 3.3

getCache

public static <K,V> NamedCache<K,V> getCache(String sName)

Return an instance of an cache configured by the current ConfigurableCacheFactory

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...) method, using Base.ensureClassLoader(ClassLoader) to determine the ClassLoader and no options.

Parameters:

sName - cache name (unique for a given configurable cache factory). If the NamedCache with the specified name already exists, a reference to the same object will be returned

Returns:

the NamedCache object

Since:

Coherence 2.2

getCache

public static <K,V> NamedCache<K,V> getCache(String sName,
                                             NamedCache.Option... options)

Return an instance of an cache configured by the current ConfigurableCacheFactory, using the specified NamedCache.Options.

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...) method, using Base.ensureClassLoader(ClassLoader) to determine the ClassLoader.

To enable type-safety checking, applications may specify the TypeAssertion NamedCache.Option.

Parameters:

sName - cache name (unique for a given configurable cache factory). If the NamedCache with the specified name already exists, a reference to the same object will be returned

Returns:

the NamedCache object

Since:

Coherence 12.2.1.1.0

getCache

public static <K,V> NamedCache<K,V> getCache(String sName,
                                             ClassLoader loader)

Return an instance of a cache configured by the current ConfigurableCacheFactory with a specific ClassLoader no options.

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...) method.

Parameters:

sName - cache name (unique for a given configurable cache factory). If the NamedCache with the specified name already exists, a reference to the same object will be returned

loader - ClassLoader that should be used to deserialize objects inserted in the map by other members of the cluster

Returns:

the NamedCache reference

Since:

Coherence 2.2

getCache

public static <K,V> NamedCache<K,V> getCache(String sName,
                                             ClassLoader loader,
                                             NamedCache.Option... options)

Return an instance of a cache configured by the current ConfigurableCacheFactory with a specific ClassLoader and NamedCache.Options

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureCache(String, ClassLoader, NamedCache.Option...) method.

To enable type-safety checking, applications may specify the TypeAssertion NamedCache.Option.

Parameters:

sName - cache name (unique for a given configurable cache factory). If the NamedCache with the specified name already exists, a reference to the same object will be returned

loader - ClassLoader that should be used to deserialize objects inserted in the map by other members of the cluster

options - the NamedCache.Options

Returns:

the NamedCache reference

Since:

Coherence 2.2

getTypedCache

public static <K,V> NamedCache<K,V> getTypedCache(String sCacheName,
                                                  TypeAssertion<K,V> assertion)

Return an instance of a cache with the given name satisfying the specified TypeAssertion.

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureTypedCache(String, ClassLoader, TypeAssertion) method, using Base.ensureClassLoader(ClassLoader) to determine the ClassLoader.

Parameters:

sCacheName - the cache name

assertion - the TypeAssertion

Returns:

a NamedCache reference

Since:

Coherence 12.2.1

See Also:

TypeAssertion.withTypes(Class, Class), TypeAssertion.withoutTypeChecking(), TypeAssertion.withRawTypes()

getTypedCache

public static <K,V> NamedCache<K,V> getTypedCache(String sCacheName,
                                                  ClassLoader loader,
                                                  TypeAssertion<K,V> assertion)

Return an instance of a cache with the given name satisfying the specified TypeAssertion.

This helper method is a simple wrapper around the ConfigurableCacheFactory.ensureTypedCache(String, ClassLoader, TypeAssertion) method.

Parameters:

sCacheName - the cache name

loader - ClassLoader that should be used to deserialize objects in the cache

assertion - the TypeAssertion

Returns:

a NamedCache reference

Since:

Coherence 12.2.1

See Also:

TypeAssertion.withTypes(Class, Class), TypeAssertion.withoutTypeChecking(), TypeAssertion.withRawTypes()

getLocalTransaction

public static TransactionMap getLocalTransaction(NamedCache map)

Factory method returning an instance of the TransactionMap that is based on the specified NamedCache and is local to this JVM.

Note: TransactionMap instance returned by this method will also implement the NamedCache interface, allowing a client code to chain local transaction by using the returned TransactionMap as a parameter for another getLocalTransaction() call.

Parameters:

map - the NamedCache object to be used as a base for transaction

Returns:

a TransactionMap instance

Since:

Coherence 1.2

commitTransactionCollection

public static boolean commitTransactionCollection(Collection collCaches,
                                                  int cRetry)

Commit the transaction represented by a collection of TransactionMap objects. Due to any of a number of reasons, the transaction could fail to commit; if it fails to commit, the transaction is rolled back.

Parameters:

collCaches - a collection of TransactionMap objects

cRetry - the number of times [0..100] to retry a stage of the transaction if a concurrency conflict occurs

Returns:

true if the transaction could be committed; false otherwise

rollbackTransactionCollection

public static void rollbackTransactionCollection(Collection collCaches)

Roll back the transaction represented by a collection of TransactionMap objects.

Parameters:

collCaches - a collection of TransactionMap objects

getCluster

public static Cluster getCluster()

Return a Cluster object for Coherence services.

Returns:

a Cluster object which may or may not be running

Since:

Coherence 1.1

ensureCluster

public static Cluster ensureCluster()

Obtain a Cluster object running Coherence services. Calling this method is optional. The cluster member carrying caching services will be lazily initialized when a first cache is about to be created. However, that operation could take significant time (especially for a first cluster member). This method forces initialization, making all cache creating requests predictably faster.

Returns:

a Cluster object

Since:

Coherence 1.1

shutdown

public static void shutdown()

Shutdown all clustered services.

Since:

Coherence 1.0

releaseCache

public static void releaseCache(NamedCache cache)

Release local resources associated with the specified instance of the cache. This invalidates a reference obtained by any of getCache() methods.

Releasing a NamedCache reference makes it no longer usable, but does not affect the content of the cache. In other words, all other references to the cache will still be valid, and the cache data is not affected by releasing the reference.

The reference that is released using this method can no longer be used; any attempt to use the reference will result in an exception.

The purpose for releasing a cache reference is to allow the cache implementation to release the ClassLoader used to deserialize items in the cache. The cache implementation ensures that all references to that ClassLoader are released. This implies that objects in the cache that were loaded by that ClassLoader will be re-serialized to release their hold on that ClassLoader. The result is that the ClassLoader can be garbage-collected by Java in situations where the cache is operating in an application server and applications are dynamically loaded and unloaded.

Parameters:

cache - the NamedCache object to be released

Since:

Coherence 1.1

See Also:

CacheService.releaseCache(NamedCache), destroyCache(NamedCache)

destroyCache

public static void destroyCache(NamedCache cache)

Releases and destroys the specified NamedCache.

Warning: This method is used to completely destroy the specified cache across the cluster. All references in the entire cluster to this cache will be invalidated, the cached data will be cleared, and all resources will be released.

Parameters:

cache - the NamedCache object to be destroyed

Since:

Coherence 1.1

See Also:

CacheService.destroyCache(NamedCache), releaseCache(NamedCache)

getEdition

public static String getEdition()

Returns the edition currently loaded based on the operational configuration.

Returns:

the abbreviated string representation of the current edition. Potential values include (GE,EE,SE,RTC,DC)

Since:

Coherence 12.1.2

log

public static void log(String sMessage,
                       int nSeverity)

Log a message using Coherence logging facility which is driven by the "logging-config" element located in the tangosol-coherence.xml configuration file.

Parameters:

sMessage - a message to log

nSeverity - the severity of the logged message; 0=default, 1=error; 2=warning; 3=info; 4-9=debug

Since:

Coherence 2.0

isLogEnabled

public static boolean isLogEnabled(int nSeverity)

Check if a message of the specified severity level will be logged using the Coherence logging facility.

Parameters:

nSeverity - the severity of a message

Returns:

true if a message with the specified severity level will be logged; false otherwise

Since:

Coherence 3.2

See Also:

log(java.lang.String, int)

getClusterConfig

public static XmlElement getClusterConfig()

Return the default cluster configuration as defined by the "cluster-config" element in the tangosol-coherence.xml configuration file.

Returns:

XmlElement representing the default cluster configuration

getReplicatedCacheConfig

public static XmlElement getReplicatedCacheConfig()

Return the default replicated cache configuration.

Returns:

XmlElement representing the replicated cache configuration

See Also:

getServiceConfig(String)

getDistributedCacheConfig

public static XmlElement getDistributedCacheConfig()

Return the default distributed (partitioned) cache configuration.

Returns:

XmlElement representing the partitioned cache configuration

See Also:

getServiceConfig(String)

getLoggingConfig

public static XmlElement getLoggingConfig()

Return the configuration info for the logging facility as defined by the "logging-config" element in the tangosol-coherence.xml configuration file.

Returns:

XmlElement representing the logging facility configuration

Since:

Coherence 2.2

setLoggingConfig

public static void setLoggingConfig(XmlElement xmlCfg)

Set the configuration info for the logging facility. If the Logger daemon is already running, this call will also force its restart.

Parameters:

xmlCfg - an XmlElement representing the new logging configuration

Since:

Coherence 3.4.1

getCacheFactoryBuilderConfig

public static XmlElement getCacheFactoryBuilderConfig()

Return the cache factory builder configuration as defined by the "cache-factory-builder-config" element in the tangosol-coherence.xml configuration file.

Returns:

XmlElement representing the cache factory builder configuration

Since:

Coherence 3.5.1

setCacheFactoryBuilderConfig

public static void setCacheFactoryBuilderConfig(XmlElement xmlCfg)

Set the cache factory builder configuration. If the Cluster service is already running, this call will not have any effect.

Parameters:

xmlCfg - an XmlElement representing the cache factory builder configuration

Since:

Coherence 3.5.1

getConfigurableCacheFactoryConfig

public static XmlElement getConfigurableCacheFactoryConfig()

Return the configurable cache factory configuration as defined by the "configurable-cache-factory-config" element in the tangosol-coherence.xml configuration file.

Returns:

XmlElement representing the configurable cache factory configuration

Since:

Coherence 2.2

setConfigurableCacheFactoryConfig

public static void setConfigurableCacheFactoryConfig(XmlElement xmlCfg)

Set the configurable cache factory configuration. If the Cluster service is already running, this call will not have any effect.

Parameters:

xmlCfg - an XmlElement representing the configurable cache factory configuration

Since:

Coherence 3.4.1

getSecurityConfig

public static XmlElement getSecurityConfig()

Return the security framework configuration.

Returns:

XmlElement representing the security framework configuration

Since:

Coherence 2.5

setSecurityConfig

public static void setSecurityConfig(XmlElement xmlCfg)

Set the security framework configuration. If the Cluster service is already running, this call will not have any effect.

Parameters:

xmlCfg - an XmlElement representing the security framework configuration

Since:

Coherence 3.4.1

getManagementConfig

public static XmlElement getManagementConfig()

Return the management framework configuration.

Returns:

XmlElement representing the management framework configuration

Since:

Coherence 3.3

setManagementConfig

public static void setManagementConfig(XmlElement xmlCfg)

Set the management framework configuration. If the Cluster service is already running, this call will not have any effect.

Parameters:

xmlCfg - an XmlElement representing the management framework configuration

Since:

Coherence 3.4.1

getServiceConfig

public static XmlElement getServiceConfig(String sServiceType)

Return the configuration for the specified service type.

Parameters:

sServiceType - the service type

Returns:

XmlElement representing the service configuration

Since:

Coherence 2.2

setServiceConfig

public static void setServiceConfig(String sServiceType,
                                    XmlElement xmlCfg)

Set the configuration for the specified service type. If the Cluster service is already running, this call may not have any effect.

Parameters:

sServiceType - the service type

xmlCfg - an XmlElement representing the service configuration

Since:

Coherence 3.4.1

main

public static void main(String[] asArg)
                 throws Exception

Invoke the Coherence command line tool.

Throws:

Exception