com.tangosol.net
Class DefaultCacheFactoryBuilder

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.net.DefaultCacheFactoryBuilder

All Implemented Interfaces:

CacheFactoryBuilder

public class DefaultCacheFactoryBuilder
extends Base
implements CacheFactoryBuilder

DefaultCacheFactoryBuilder provides the basic means to manage configurable cache factories (CCF). This implementation employs one of serveral strategies for resolving cache configurations with potentially conflicting service definitions:

• Compatibility mode - a single default ConfigurableCacheFactory instance is maintained, irrespective of the requesting class loader;
• Non-Validating union - loaded or externally provided configurations are used as-is without triggering any validation or modification logic;
• Validating union - loaded or externally provided configurations are used after ensuring that all service names are distinct;
• Unique Service Renaming - new configurations are compared against existing CCF instances as they are loaded and all service names are modified to ensure uniqueness.

DefaultCacheFactoryBuilder could be extended in advanced use-cases to provide further domain-specific logic for creating and managing CCF's. For example, a J2EE or OSGi container would extend DefaultCacheFactoryBuilder to provide classloader-based application scoping.

Since:

Coherence 3.5.1

Author:

rhl 2009.07.14

Field Summary

protected ConfigurableCacheFactory	m_ccfSingleton Singleton ConfigurableCacheFactory instance for the default URI, used when the resolution strategy is STRATEGY_COMPATIBILITY.
protected java.util.Map	m_mapByLoader Mapping used to associate class loaders with the cache factories that are configured on them.
protected java.util.Map	m_mapInternedConfig Mapping of configuration resource URLs to the xml configuration elements loaded from those resources.
protected int	m_nResolveStrategy The strategy to use for resolving configuration conflicts.
static int	STRATEGY_COMPATIBILITY Backward compatibility with pre-3.5.1 behaviour.
static int	STRATEGY_NONVALIDATION No service name validation is performed.
static int	STRATEGY_RENAME_UNIQUELY Service names are uniquely renamed for each class loader scope.
static int	STRATEGY_VALIDATION Strict validation ensures that all service names are unique.
protected static java.lang.String	URI_DEFAULT Innternally used "default" URI identifier.

Constructor Summary

	DefaultCacheFactoryBuilder() Default constructor using the compatibility strategy (STRATEGY_COMPATIBILITY).
protected	DefaultCacheFactoryBuilder(int nResolveStrategy) Construct a DefaultCacheFactoryBuilder with the specified configuration resolution strategy.

Method Summary

protected XmlElement	applyStrategy(XmlElement xmlConfig, java.lang.ClassLoader loader) Apply the resolution strategy for this builder to the specified xml configuration in the context of the specified class loader.
protected ConfigurableCacheFactory	buildFactory(XmlElement xmlConfig, java.lang.ClassLoader loader) Construct a ConfigurableCacheFactory for the specified XML configuration.
protected java.util.Set	collectServiceNames() Construct and return a collection of service names defined by any cache configurations known to this cache factory builder.
protected java.util.Map	ensureConfigCCFMap(java.lang.ClassLoader loader) Ensure that a map from URI to ConfigurableCacheFactory for the specified loader exists (creating it if necessary).
ConfigurableCacheFactory	getConfigurableCacheFactory(java.lang.ClassLoader loader) Return the default ConfigurableCacheFactory for a given class loader.
ConfigurableCacheFactory	getConfigurableCacheFactory(java.lang.String sConfigURI, java.lang.ClassLoader loader) Return the ConfigurableCacheFactory for a given URI and class loader.
protected ConfigurableCacheFactory	getDefaultFactory(java.lang.ClassLoader loader) Return a default cache factory for the specified loader.
protected ConfigurableCacheFactory	getFactory(java.lang.String sConfigURI, java.lang.ClassLoader loader) Helper method to return a CCF instance for the specified URI and class loader.
int	getResolutionStrategy() Return the configuration resolution strategy.
protected java.lang.String	getScopeName(java.lang.ClassLoader loader) Return the scope name corresponding to the specified class loader.
protected ConfigurableCacheFactory	getSingletonFactory() Return the singleton cache factory.
protected boolean	isCompatibility() Return true iff the resolution strategy of this builder is STRATEGY_COMPATIBILITY.
protected XmlElement	loadConfigFromURI(java.lang.String sConfigURI, java.lang.ClassLoader loader) Load the XML configuration from the specified URI.
protected XmlElement	modifyConfig(XmlElement xmlConfig, java.lang.ClassLoader loader) Modify the specified configuration to resolve any conflicts with existing service configurations.
protected java.lang.String	modifyServiceName(java.lang.String sName, java.lang.String sScope) Modify the specified service name to reflect the specified scope.
void	release(ConfigurableCacheFactory factory) Release the specified ConfigurableCacheFactory.
void	releaseAll(java.lang.ClassLoader loader) Release all ConfigurableCacheFactory objects for a given ClassLoader.
void	setCacheConfiguration(java.lang.ClassLoader loader, XmlElement xmlConfig) Dynamically set the default cache configuration for a given class loader.
void	setCacheConfiguration(java.lang.String sConfigURI, java.lang.ClassLoader loader, XmlElement xmlConfig) Dynamically set the cache configuration for a given URI and class loader.
protected void	setSingletonFactory(ConfigurableCacheFactory ccf) Set the singleton cache factory (see getSingletonFactory()).
protected void	validateConfig(XmlElement xmlConfig) Validate the specified configuration against the existing configurations.

Field Detail

STRATEGY_COMPATIBILITY

public static final int STRATEGY_COMPATIBILITY

Backward compatibility with pre-3.5.1 behaviour. A single cache factory instance is maintained for the default configurable cache factory.

See Also:

Constant Field Values

STRATEGY_VALIDATION

public static final int STRATEGY_VALIDATION

Strict validation ensures that all service names are unique.

See Also:

Constant Field Values

STRATEGY_NONVALIDATION

public static final int STRATEGY_NONVALIDATION

No service name validation is performed.

See Also:

Constant Field Values

STRATEGY_RENAME_UNIQUELY

public static final int STRATEGY_RENAME_UNIQUELY

Service names are uniquely renamed for each class loader scope.

See Also:

Constant Field Values

URI_DEFAULT

protected static final java.lang.String URI_DEFAULT

Innternally used "default" URI identifier.

See Also:

Constant Field Values

m_mapByLoader

protected java.util.Map m_mapByLoader

Mapping used to associate class loaders with the cache factories that are configured on them. The map is (weakly) keyed by class loader instances and holds a maps of URI to ConfigurableCacheFactory as a values (e.g. Map<ClassLoader, Map<URI, ConfigurableCacheFactory>>).

m_mapInternedConfig

protected java.util.Map m_mapInternedConfig

Mapping of configuration resource URLs to the xml configuration elements loaded from those resources.

Note: only xml configuration elements that are configured from a loaded resource are interned; externally configured cache factories are excluded.

m_ccfSingleton

protected ConfigurableCacheFactory m_ccfSingleton

Singleton ConfigurableCacheFactory instance for the default URI, used when the resolution strategy is STRATEGY_COMPATIBILITY.

m_nResolveStrategy

protected int m_nResolveStrategy

The strategy to use for resolving configuration conflicts.

Constructor Detail

DefaultCacheFactoryBuilder

public DefaultCacheFactoryBuilder()

Default constructor using the compatibility strategy (STRATEGY_COMPATIBILITY).

DefaultCacheFactoryBuilder

protected DefaultCacheFactoryBuilder(int nResolveStrategy)

Construct a DefaultCacheFactoryBuilder with the specified configuration resolution strategy.

Parameters:

nResolveStrategy - the STRATEGY_* constant to use for resolving multiple configurations

Method Detail

isCompatibility

protected boolean isCompatibility()

Return true iff the resolution strategy of this builder is STRATEGY_COMPATIBILITY.

Returns:

true iff the resolution strategy of this builder is STRATEGY_COMPATIBILITY

getSingletonFactory

protected ConfigurableCacheFactory getSingletonFactory()

Return the singleton cache factory. A singleton cache factory is an unnamed configurable cache factory that does not depend on a class loader. It is only used by the STRATEGY_COMPATIBILITY resolution mode to preserve backward compatibility.

Returns:

the singleton cache factory

setSingletonFactory

protected void setSingletonFactory(ConfigurableCacheFactory ccf)

Set the singleton cache factory (see getSingletonFactory()).

Parameters:

ccf - the singleton configurable cache factory

getResolutionStrategy

public int getResolutionStrategy()

Return the configuration resolution strategy.

Returns:

the configuration resolution strategy

getConfigurableCacheFactory

public ConfigurableCacheFactory getConfigurableCacheFactory(java.lang.ClassLoader loader)

Return the default ConfigurableCacheFactory for a given class loader.

Specified by:

getConfigurableCacheFactory in interface CacheFactoryBuilder

Parameters:

loader - class loader for which the configuration should be used; must not be null

Returns:

the default ConfigurableCacheFactory for a given class loader

getConfigurableCacheFactory

public ConfigurableCacheFactory getConfigurableCacheFactory(java.lang.String sConfigURI,
                                                            java.lang.ClassLoader loader)

Return the ConfigurableCacheFactory for a given URI and class loader.

Specified by:

getConfigurableCacheFactory in interface CacheFactoryBuilder

Parameters:

sConfigURI - the configuration URI; must not be null

loader - class loader for which the configuration should be used; must not be null

Returns:

the ConfigurableCacheFactory for a given URI and class loader

getFactory

protected ConfigurableCacheFactory getFactory(java.lang.String sConfigURI,
                                              java.lang.ClassLoader loader)

Helper method to return a CCF instance for the specified URI and class loader.

Parameters:

sConfigURI - the configuration URI to return a CCF for

loader - the loader to return a CCF for

Returns:

a CCF instance

setCacheConfiguration

public void setCacheConfiguration(java.lang.ClassLoader loader,
                                  XmlElement xmlConfig)

Dynamically set the default cache configuration for a given class loader.

Specified by:

setCacheConfiguration in interface CacheFactoryBuilder

Parameters:

loader - class loader for which the configuration should be used; must not be null

xmlConfig - cache configuration in xml element format

setCacheConfiguration

public void setCacheConfiguration(java.lang.String sConfigURI,
                                  java.lang.ClassLoader loader,
                                  XmlElement xmlConfig)

Dynamically set the cache configuration for a given URI and class loader.

Specified by:

setCacheConfiguration in interface CacheFactoryBuilder

Parameters:

sConfigURI - the configuration URI; must not be null

loader - class loader for which the configuration should be used; must not be null

xmlConfig - cache configuration in xml element format

releaseAll

public void releaseAll(java.lang.ClassLoader loader)

Release all ConfigurableCacheFactory objects for a given ClassLoader.

Specified by:

releaseAll in interface CacheFactoryBuilder

Parameters:

loader - the class loader for which all associated cache factories should be released

release

public void release(ConfigurableCacheFactory factory)

Release the specified ConfigurableCacheFactory.

Specified by:

release in interface CacheFactoryBuilder

Parameters:

factory - the ConfigurableCacheFactory to release

getScopeName

protected java.lang.String getScopeName(java.lang.ClassLoader loader)

Return the scope name corresponding to the specified class loader. This method is used by the unique renaming strategy to provide a scope-specific service identifier with which to uniquely rename services. Naturally, this method should be expected to produce the same scope identifier across different cluster members for a given scope. See also modifyServiceName(java.lang.String, java.lang.String).

Note: this method must be overriden if the unique naming strategy is to be used.

Parameters:

loader - the class loader

Returns:

the scope name corresponding to the specified class loader

modifyServiceName

protected java.lang.String modifyServiceName(java.lang.String sName,
                                             java.lang.String sScope)

Modify the specified service name to reflect the specified scope. This method is used by the unique renaming strategy to construct unique services names given the configured service name and a scope-specific identifier. See also getScopeName(java.lang.ClassLoader).

Parameters:

sName - the configured service name to modify

sScope - the scope identifier to use in modifying the service name

Returns:

the modified service name

ensureConfigCCFMap

protected java.util.Map ensureConfigCCFMap(java.lang.ClassLoader loader)

Ensure that a map from URI to ConfigurableCacheFactory for the specified loader exists (creating it if necessary).

Parameters:

loader - the class loader to which the map corresponds

Returns:

a map from URI to ConfigurableCacheFactory

getDefaultFactory

protected ConfigurableCacheFactory getDefaultFactory(java.lang.ClassLoader loader)

Return a default cache factory for the specified loader. The default cache factory is specified by the "configurable-cache-factory-config" xml configuration element.

Parameters:

loader - the loader for which to create a default cache factory

Returns:

a default cache factory

loadConfigFromURI

protected XmlElement loadConfigFromURI(java.lang.String sConfigURI,
                                       java.lang.ClassLoader loader)

Load the XML configuration from the specified URI.

Parameters:

sConfigURI - the configuration URI; must not be null

loader - class loader to use

Returns:

the XML configuration, or null if the config could not be loaded

collectServiceNames

protected java.util.Set collectServiceNames()

Construct and return a collection of service names defined by any cache configurations known to this cache factory builder.

Returns:

a collection of service names known to this builder

applyStrategy

protected XmlElement applyStrategy(XmlElement xmlConfig,
                                   java.lang.ClassLoader loader)

Apply the resolution strategy for this builder to the specified xml configuration in the context of the specified class loader.

Parameters:

xmlConfig - the XML configuration on which to apply the resolution strategy

loader - the class loader with which to apply the resolution strategy

Returns:

the (possibly modified) result of the resolution strategy

validateConfig

protected void validateConfig(XmlElement xmlConfig)

Validate the specified configuration against the existing configurations.

Parameters:

xmlConfig - the configuration to validate with respect to the existing config

Throws:

java.lang.IllegalStateException - if there are conflicting service definitions.

modifyConfig

protected XmlElement modifyConfig(XmlElement xmlConfig,
                                  java.lang.ClassLoader loader)

Modify the specified configuration to resolve any conflicts with existing service configurations.

Parameters:

xmlConfig - the configuration to validate with respect to the existing config

loader - the class loader for which to modify the specified config

Returns:

the possibly modified XML configuration

buildFactory

protected ConfigurableCacheFactory buildFactory(XmlElement xmlConfig,
                                                java.lang.ClassLoader loader)

Construct a ConfigurableCacheFactory for the specified XML configuration.

Parameters:

xmlConfig - the XML configuration to create a factory for

loader - the class loader associated with the factory

Returns:

a ConfigurableCacheFactory for the specified XML configuration