This site hosts historical documentation. Visit www.terracotta.org for recent product information.

Open Source

Configuring BigMemory Max

Introduction

BigMemory Max 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 Max 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 Max 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 Max distribution. It contains full commentary on how to configure each element. This file can also be downloaded from http://ehcache.org/ehcache.xml.

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 Max 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 is 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 Max configuration file.

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

Quick Start for BigMemory Max

Configuration involves adding BigMemory Max to your application's installation and setting up the Terracotta server.

Install and Configure BigMemory Max

  1. If you do not have a BigMemory Max kit, download it from here.

    The kit is packaged as a tar.gz file. Unpack it on the command line or with the appropriate decompression application.

  2. Add the following JARs from in the kit to your application's classpath:

    • common/lib/bigmemory-<version>.jar – This is the main JAR to enable BigMemory.

    • apis/ehcache/lib/ehcache-ee-<version>.jar – This file contains the API to BigMemory Max.

    • apis/ehcache/lib/slf4j-api-<version>.jar – This file is the bridge, or logging facade, to the BigMemory Max logging framework.

    • apis/ehcache/lib/slf4j-jdk14-<version>.jar – This is a binding JAR for the provided SLF4J logging framework, java.util.logging. Binding JARs for other frameworks are available from the SLF4J website.

    • apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar – This JAR contains the libraries for the Terracotta Server Array.

  3. Save the BigMemory Max license-key file to the BigMemory Max home directory. This file, called terracotta-license.key, was attached to an email you received after registering for the BigMemory Max download.

    Alternatively, you can add the license-key file to your application's classpath, or specify it with the following Java system property:

    -Dcom.tc.productkey.path=/path/to/terracotta-license.key

  4. BigMemory Max uses Ehcache as its user-facing interface. To configure BigMemory Max, create an ehcache.xml configuration file, or update the one that is provided in the config-samples/ directory of the BigMemory Max kit. For example:

    <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd"
     name="myBigMemoryMaxConfig">

  <!-- Tell BigMemory where to write its data to disk. -->
  <diskStore path="/path/to/my/disk/store/directory"/>

  <!-- Set 'maxBytesLocalOffHeap' to the amount of off-heap in-memory 
  storage you want to use. This memory is invisible to the Java garbage 
  collector, providing for gigabytes to terabytes of in-memory data without 
  garbage collection pauses. --> 
  <cache name="myBigMemoryMaxStore"
        maxBytesLocalHeap="512M"
        maxBytesLocalOffHeap="8G">

    <!-- Tell BigMemory to use the "localRestartable" persistence
    strategy for fast restart (optional). -->
    <persistence strategy="localRestartable"/>

    <!-- Include the terracotta element so that the data set will be 
    managed as a client of the Terracotta server array.  -->
    <terracotta/>

  <!-- Specify where to find the server array configuration. In this 
  case, the configuration is retrieved from the local server. --> 
  <terracottaConfig url="localhost:9510" />

  </cache>
</ehcache>

    Place your ehcache.xml file in the top-level of your classpath.

  5. Use the -XX:MaxDirectMemorySize Java option to allocate enough direct memory in the JVM to accomodate the off-heap storage specified in your configuration, plus at least 250MB to allow for other direct memory usage that might occur in your application. For example:

    -XX:MaxDirectMemorySize=9G

    Set MaxDirectMemorySize to the amount of BigMemory you have. For more information about this step, refer to Allocating Direct Memory in the JVM.

    Also, allocate at least enough heap using the -Xmx Java option to accomodate the on-heap storage specified in your configuration, plus enough extra heap to run the rest of your application. For example:

    -Xmx1g

    Finally, if necessary, define the JAVA_HOME environment variable.

Start the Terracotta Server and Management Console

Large data sets in BigMemory Max can be distributed across the Terracotta Server Array (TSA) and managed with the Terracotta Management Console (TMC).

  1. To configure the Terracotta server, create a tc-config.xml configuration file, or update the one that is provided in the config-samples/ directory of the BigMemory Max kit. For example:

    <?xml version="1.0" encoding="UTF-8" ?>
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd">
  <servers>
    <server host="localhost" name="My Server Name">
      <!-- Specify the path where the server should store its data. -->
      <data>/local/disk/path/to/terracotta/server1-data</data>
       <!-- Specify the port where the server should listen for client 
       traffic. -->
       <tsa-port>9510</tsa-port>
       <jmx-port>9520</jmx-port>
       <tsa-group-port>9530</tsa-group-port>
       <!-- Enable BigMemory on the server. -->
       <offheap>
         <enabled>true</enabled>
         <maxDataSize>4g</maxDataSize>
       </offheap>
     </server>
    <!-- Add the restartable element for Fast Restartability (optional). -->
    <restartable enabled="true"/>
  </servers>
  <clients>
    <logs>logs-%i</logs>
  </clients>
</tc:tc-config>

    Place your tc-config.xml file in the Terracotta server/ directory.

    For more information about configuration options, refer to the TSA configuration documentation.

  2. In a terminal, change to your Terracotta server/ directory. Then execute the start-tc-server command:

    %> cd /path/to/bigmemory-max-<version>/server
%> ./bin/start-tc-server.sh

    You should see confirmation in the terminal that the server started.

    Note: For Microsoft Windows installations, use the BAT scripts, and where forward slashes ("/") are given in directory paths, substitute back slashes ("\").

  3. In a terminal, change to your Terracotta tools/management-console/ directory. Then execute the start-tmc command:

    %> cd /path/to/bigmemory-max-<version>/tools/management-console
%> ./bin/start-tmc.sh

  4. In a browser, enter the URL http://localhost:9889/tmc. When you first connect to the TMC, the authentication setup page appears, where you can choose to run the TMC with authentication or without.

    Terracotta Management Console

  5. Use the TMC to manage all of the clients and servers in your deployment.

    Terracotta Management Console

For more information about the TMC, refer to the TMC documentation.

More Information on Configuration

Topic Description
Terracotta Clustering BigMemory Max can manage in-memory data in a single, standalone installation or with a Terracotta server. This page provides configuration essentials for distributing BigMemory across a Terracotta cluster or server array.
Storage Tiers BigMemory Max includes storage options for your in-memory data. This page discusses the storage tier options and shows how to configure them in a standalone installation. Refer to Terracotta Server Array Architecture for distributed configuration information.
Sizing Storage Tiers Tuning BigMemory Max often involves sizing data storage tiers appropriately. BigMemory Max provides a number of ways to size tiers using simple cache-configuration sizing attributes. This page explains tuning of tier size by configuring dynamic allocation of memory and automatic load balancing.
Expiration, Pinning, and Eviction One of the most important aspects of managing in-memory data involves managing the life of the data in each tier. This page covers managing data life in BigMemory Max 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.
Visit www.terracotta.org for most recent product information.