Performing the Standalone Installation of BigMemory Max

Edit online

About this task

This section describes how to perform the installation of BigMemory Max if you intend to use BigMemory Max as a standalone product. If you plan to install BigMemory Max as part of a software bundle from Software AG rather than as a standalone product, use instead the Software AG Installer, as described in the section Installation using the Software AG Installer.

Performing the standalone installation of BigMemory Max is as easy as downloading the kit and ensuring that the correct files are on your application's classpath. The only platform requirement is using JDK 1.6 or higher.

To install BigMemory Max

Procedure

  1. If you do not have a standalone BigMemory Max kit, download it from http://terracotta.org/downloads/bigmemorymax.
    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:
    • 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/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar

      This file 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 explicitly specify the location of the license key file as described in Working with Terracotta License Files.
  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/> 
  </cache> 
  <!-- Specify where to find the server array configuration. In this 
  case, the configuration is retrieved from the local server. --> 
  <terracottaConfig url="localhost:9510" /> 
</ehcache>

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

    For more information on configuration options, see "Configuring Storage Tiers" in the BigMemory Max Configuration Guide and the reference ehcache.xml configuration file in the config-samples directory of the BigMemory Max kit.

  5. Use the -XX:MaxDirectMemorySize Java option to allocate enough direct memory in the JVM to accommodate 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, see "Allocating Direct Memory in the JVM" in the BigMemory Max Configuration Guide.

    Also, allocate at least enough heap using the -Xmx Java option to accommodate 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.

  6. Learn BigMemory basics from the "Tutorials" or look through the "Code Samples" for examples of how to employ the various features and capabilities of BigMemory Max. You will find both of these resources in the online documentation for BigMemory Max.