Configuration Overview

Introduction

BigMemory Go supports declarative configuration via an XML configuration file, as well as programmatic configuration via class-constructor APIs. Choosing one approach over the other can be a matter of preference or a requirement, such as when an application requires a certain runtime context to determine appropriate configuration settings.

If your project permits the separation of configuration from runtime use, there are advantages to the declarative approach:

• Cache configuration can be changed more easily at deployment time.
• Configuration can be centrally organized for greater visibility.
• Configuration lifecycle can be separated from application-code lifecycle.
• Configuration errors are checked at startup rather than causing an unexpected runtime error.
• If the configuration file is not provided, a default configuration is always loaded at runtime.

This documentation focuses on XML declarative configuration. Programmatic configuration is explored in certain examples and is documented in Javadocs.

XML Configuration

BigMemory Go uses Ehcache as its user-facing interface and is configured using the Ehcache configuration system. By default, Ehcache looks for an ASCII or UTF8 encoded XML configuration file called ehcache.xml at the top level of the Java classpath. You may specify alternate paths and filenames for the XML configuration file by using the various CacheManager constructors.

To avoid resource conflicts, one XML configuration is required for each CacheManager that is created. For example, directory paths and listener ports require unique values. BigMemory Go will attempt to resolve conflicts, and, if one is found, it will emit a warning reminding the user to use separate configurations for multiple CacheManagers.

The sample ehcache.xml is included in the BigMemory Go distribution. It contains full commentary on how to configure each element. This file can also be downloaded from http://ehcache.org/ehcache.xml.

Dynamically Changing Cache Configuration

While most of the BigMemory Go configuration is not changeable after startup, certain cache configuration parameters can be modified dynamically at runtime. These include the following:

• Expiration settings

  • timeToLive – The maximum number of seconds an element can exist in the cache regardless of access. The element expires at this limit and will no longer be returned from the cache. The default value is 0, which means no TTL eviction takes place (infinite lifetime).

  • timeToIdle – The maximum number of seconds an element can exist in the cache without being accessed. The element expires at this limit and will no longer be returned from the cache. The default value is 0, which means no TTI eviction takes place (infinite lifetime).

• Local sizing attributes

  • maxEntriesLocalHeap
  • maxBytesLocalHeap
  • maxEntriesLocalDisk
  • maxBytesLocalDisk.

• memory-store eviction policy

• CacheEventListeners can be added and removed dynamically

Note that the eternal attribute, when set to "true", overrides timeToLive and timeToIdle so that no expiration can take place.

This example shows how to dynamically modify the cache configuration of a running cache:

Cache cache = manager.getCache("sampleCache");
CacheConfiguration config = cache.getCacheConfiguration();
config.setTimeToIdleSeconds(60);
config.setTimeToLiveSeconds(120);
config.setmaxEntriesLocalHeap(10000);
config.setmaxEntriesLocalDisk(1000000);

Dynamic cache configurations can also be disabled to prevent future changes:

Cache cache = manager.getCache("sampleCache");
cache.disableDynamicFeatures();

In ehcache.xml, you can disable dynamic configuration by setting the <ehcache> element's dynamicConfig attribute to "false". For a complete list of configuration parameters that can be changed dynamically, see this introduction to Ehcache configuration.

Passing Copies Instead of References

By default, a get() operation on store data returns a reference to that data, and any changes to that data are immediately reflected in the memory store. In cases where an application requires a copy of data rather than a reference to it, you can configure the store to return a copy. This allows you to change a copy of the data without affecting the original data in the memory store.

This is configured using the copyOnRead and copyOnWrite attributes of the <cache> and <defaultCache elements in your configuration, or programmatically as follows:

CacheConfiguration config = new CacheConfiguration("copyCache", 1000)
                            .copyOnRead(true).copyOnWrite(true);
Cache copyCache = new Cache(config);

The default configuration is "false" for both options.

To copy elements on put()-like and/or get()-like operations, a copy strategy is used. The default implementation uses serialization to copy elements. You can provide your own implementation of net.sf.ehcache.store.compound.CopyStrategy using the <copyStrategy> element:

<cache name="copyCache"
    maxEntriesLocalHeap="10"
    eternal="false"
    timeToIdleSeconds="5"
    timeToLiveSeconds="10"
    copyOnRead="true"
    copyOnWrite="true">
  <copyStrategy class="com.company.ehcache.MyCopyStrategy"/>
</cache>

A single instance of your CopyStrategy is used per cache. Therefore, in your implementation of CopyStrategy.copy(T), T has to be thread-safe.

A copy strategy can be added programmatically in the following way:

CacheConfiguration cacheConfiguration = new CacheConfiguration("copyCache", 10);

CopyStrategyConfiguration copyStrategyConfiguration = new CopyStrategyConfiguration();
copyStrategyConfiguration.setClass("com.company.ehcache.MyCopyStrategy");

cacheConfiguration.addCopyStrategy(copyStrategyConfiguration);

Special System Properties

net.sf.ehcache.disabled

Setting this system property to true (using java -Dnet.sf.ehcache.disabled=true in the Java command line) disables caching in ehcache. If disabled, no elements can be added to a cache (puts are silently discarded).

net.sf.ehcache.use.classic.lru

When LRU is selected as the eviction policy, set this system property to true (using java -Dnet.sf.ehcache.use.classic.lru=true in the Java command line) to use the older LruMemoryStore implementation. This is provided for ease of migration.

ehcache.xsd

Ehcache configuration files must be comply with the Ehcache XML schema, ehcache.xsd, which can be downloaded from http://ehcache.org/ehcache.xsd.

Each BigMemory Go distribution also contains a copy of ehcache.xsd.

ehcache-failsafe.xml

If the CacheManager default constructor or factory method is called, Ehcache looks for a file called ehcache.xml in the top level of the classpath. Failing that it looks for ehcache-failsafe.xml in the classpath. ehcache-failsafe.xml is packaged in the Ehcache JAR and should always be found.

ehcache-failsafe.xml provides an extremely simple default configuration to enable users to get started before they create their own ehcache.xml.

If it used Ehcache will emit a warning, reminding the user to set up a proper configuration. The meaning of the elements and attributes are explained in the section on ehcache.xml.

<ehcache>
  <diskStore path="java.io.tmpdir"/>
  <defaultCache
     maxEntriesLocalHeap="10000"
     eternal="false"
     timeToIdleSeconds="120"
     timeToLiveSeconds="120"
     maxEntriesLocalDisk="10000000"
     diskExpiryThreadIntervalSeconds="120"
     memoryStoreEvictionPolicy="LRU">
     <persistence strategy="localTempSwap"/>
  </defaultCache>
</ehcache>

About Default Cache

The defaultCache configuration is applied to any cache that is not explicitly configured. The defaultCache appears in ehcache-failsafe.xml by default, and can also be added to any BigMemory Go configuration file.

While the defaultCache configuration is not required, an error is generated if caches are created by name (programmatically) with no defaultCache loaded.

More Information on Configuration Topics

Topic	Description
Sizing Caches	Tuning Ehcache often involves sizing cached data appropriately. Ehcache provides a number of ways to size the different data tiers using simple cache-configuration sizing attributes. This page explains simplified tuning of cache size by configuring dynamic allocation of memory and automatic load balancing.
Expiration, Pinning, and Eviction	The architecture of an Ehcache node can include a number of tiers that store data. One of the most important aspects of managing cached data involves managing the life of the data in each tier. This page covers managing data life in Ehcache and the Terracotta Server Array, including the pinning features of Automatic Resource Control (ARC).
Fast Restartability	This page covers persistence, fast restartability, and using the local disk as a storage tier. The Fast Restart feature provides enterprise-ready crash resilience, which can serve as a fast recovery system after failures, a hot mirror of the data set on the disk at the application node, and an operational store with in-memory speed for reads and writes.
Code Samples	Examples of working with key classes and methods such as CacheManager and Cache, loading configuration, and getting statistics.