Getting Started With TC Server 4.3.x

Getting started with the Terracotta Server 4.x is a simple matter of downloading, changing a few configuration items, and starting it up. Because the server isn't very interesting without something using it, this guide will show you how to put the Terracotta Server to its most common use: clustering an Ehcache cache.

Download and Install

Installing and using Terracotta Server 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.

1 - Download the Terracotta Server.

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

2 - Update Classpath

Add the following JARs from within the kit to your application's classpath (if they are not already there):

• apis/ehcache/lib/ehcache-<version>.jar – This file contains the Ehcache API.
• 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-<version>.jar – This JAR contains the libraries that enable connecting Ehcache to the Terracotta Server.

3 - Configure Ehcache

Configure Ehcache to utilize the Terracotta Server. Create an `ehcache.xml` configuration file, or modify your own existing Ehcache configuration, or update the one that is provided in the config-samples/ directory of the downloaded Terracotta Server 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>

Ensure that your `ehcache.xml` file is in the top-level of your classpath.

Note

1 - 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.
2 - 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
3 - If necessary, define the JAVA_HOME environment variable.

Start The Terracotta Server

You should be able to run the server for testing without a configuration change, but we will give you a pointer on where to find the configuration file before starting the server.

1 - Configure the Terracotta Server

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 terracotta 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-9.xsd">
  <servers>
    <server host="localhost" name="My Server Name">
       <!-- Specify the port clients will connect to the server on. -->
       <tsa-port>9510</tsa-port>
       <!-- Configure memory (off-heap) space to use on the server. -->
       <dataStorage size=”4g”>
       </dataStorage>
    </server>
  </servers>
  <clients>
    <logs>logs-%i</logs>
  </clients>
</tc:tc-config>

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

2 - Start the Terracotta Server

In a terminal, change to your Terracotta `server/` directory. Then execute the start-tc-server command. For *nix systems:

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

For Windows systems:

> cd \path\to\terracotta-<version>\server
> .\bin\start-tc-server.bat

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

Not quite ready yet?

Read the user documentation for everything you've been wondering about the new API!

  .....
  <cache alias="foo"> 
    <key-type>java.lang.String</key-type> 
    <resources>
      <heap unit="entries">2000</heap> 
      <offheap unit="MB">500</offheap> 
    </resources>
  </cache>

  <cache-template name="myDefaults"> 
    <key-type>java.lang.Long</key-type>
    <value-type>java.lang.String</value-type>
    <heap unit="entries">200</heap>
  </cache-template>

  <cache alias="bar" uses-template="myDefaults"> 
    <key-type>java.lang.Number</key-type>
  </cache>

  <cache alias="simpleCache" uses-template="myDefaults" />
  .....
       

  .....
  CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .withCache("preConfigured", CacheConfigurationBuilder
      .newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10))) 
    .build(); 

  cacheManager.init(); 

  Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured", Long.class, String.class); 

  Cache<Long, String> myCache = cacheManager.createCache("myCache", 
    CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10)).build());

  myCache.put(1L, "da one!"); 
  String value = myCache.get(1L); 

  cacheManager.removeCache("preConfigured"); 

  cacheManager.close();
  .....
      

  .....
  final CacheManagerBuilder<PersistentCacheManager> clusteredCacheManagerBuilder =
    CacheManagerBuilder.newCacheManagerBuilder() 
      .with(ClusteringServiceConfigurationBuilder
        .cluster(URI.create("terracotta://localhost:9510/my-application")).autoCreate()); 

  final PersistentCacheManager cacheManager = clusteredCacheManagerBuilder.build(true); 

  cacheManager.close();
  .....
      

  <?xml version="1.0" encoding="UTF-8"?>
  <tc-config xmlns="http://www.terracotta.org/config" xmlns:ohr="http://www.terracotta.org/config/offheap-resource">
    <services>
      <service id="resources">
        <ohr:offheap-resources>
          <ohr:resource name="primary-server-resource" unit="MB">128</ohr:resource>   
          <ohr:resource name="secondary-server-resource" unit="MB">96</ohr:resource>  
        </ohr:offheap-resources>
      </service>
    </services>
  </tc-config>
       

  cd <path/to/terracotta/kit>/server/bin
  start-tc-server.bat -f <path/to/server/config>/tc-config.xml
      

  cd <path/to/terracotta/kit>/server/bin
  ./start-tc-server.sh -f <path/to/server/config>/tc-config.xml
      

  .....
  <cache alias="foo"> 
    <key-type>java.lang.String</key-type> 
    <resources>
      <heap unit="entries">2000</heap> 
      <offheap unit="MB">500</offheap> 
    </resources>
  </cache>

  <cache-template name="myDefaults"> 
    <key-type>java.lang.Long</key-type>
    <value-type>java.lang.String</value-type>
    <heap unit="entries">200</heap>
  </cache-template>

  <cache alias="bar" uses-template="myDefaults"> 
    <key-type>java.lang.Number</key-type>
  </cache>

  <cache alias="simpleCache" uses-template="myDefaults" />
  .....
       

  .....
  CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .withCache("preConfigured", CacheConfigurationBuilder
      .newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10))) 
    .build(); 

  cacheManager.init(); 

  Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured", Long.class, String.class); 

  Cache<Long, String> myCache = cacheManager.createCache("myCache", 
    CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10)).build());

  myCache.put(1L, "da one!"); 
  String value = myCache.get(1L); 

  cacheManager.removeCache("preConfigured"); 

  cacheManager.close();
  .....
      

  .....
  final CacheManagerBuilder<PersistentCacheManager> clusteredCacheManagerBuilder =
    CacheManagerBuilder.newCacheManagerBuilder() 
      .with(ClusteringServiceConfigurationBuilder
        .cluster(URI.create("terracotta://localhost:9510/my-application")).autoCreate()); 

  final PersistentCacheManager cacheManager = clusteredCacheManagerBuilder.build(true); 

  cacheManager.close();
  .....
      

  <?xml version="1.0" encoding="UTF-8"?>
  <tc-config xmlns="http://www.terracotta.org/config" xmlns:ohr="http://www.terracotta.org/config/offheap-resource">
    <services>
      <service id="resources">
        <ohr:offheap-resources>
          <ohr:resource name="primary-server-resource" unit="MB">128</ohr:resource>   
          <ohr:resource name="secondary-server-resource" unit="MB">96</ohr:resource>  
        </ohr:offheap-resources>
      </service>
    </services>
  </tc-config>
       

  cd <path/to/terracotta/kit>/server/bin
  start-tc-server.bat -f <path/to/server/config>/tc-config.xml
      

  cd <path/to/terracotta/kit>/server/bin
  ./start-tc-server.sh -f <path/to/server/config>/tc-config.xml