2.1 Terracotta Distributed Ehcache for Hibernate Express Installation

2.1.3a Using @Cache

Add the @Cache annotation to all entities in your application code that should be cached:

@Cache(usage=CacheConcurrencyStrategy.READ_WRITE)

public class Foo {...}

@Cache must set the cache concurrency strategy for the entity, which in the example above is READ_WRITE.

2.1.3b Using the <cache> Element

In the Hibernate mapping file ( hbm.xml file) for the target entity, set caching for the entity using the <cache> element:

<?xml version="1.0"?>

<!DOCTYPE hibernate-mapping PUBLIC

        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"

        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="com.my.package">

  <class name="Foo" table="BAR">

    <cache usage="read-write"/>

    <id name="id" column="BAR_ID">

      <generator class="native"/>

    </id>

    <!-- Some properties go here. -->

  </class>

</hibernate-mapping>

Use the usage attribute to specify the concurrency strategy.

2.1.3c Using the <class-cache> Element

In hibernate.cfg.xml , set caching for an entity by using <class-cache>, a subelement of the <session-factory> element:

<?xml version='1.0' encoding='utf-8'?>

<!DOCTYPE hibernate-configuration PUBLIC

    "-//Hibernate/Hibernate Configuration DTD//EN"

    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

  <session-factory name="java:some/name">

    <!-- Properties go here. -->

    <!-- mapping files -->

    <mapping resource="com/my/package/Foo.hbm.xml"/>

    <!-- cache settings -->

    <class-cache class="com.my.package.Foo" usage="read-write"/>

  </session-factory>

</hibernate-configuration>

Use the usage attribute to specify the concurrency strategy.

2.1.4a Hibernate Configuration File

For Hibernate 3.3, you can improve performance by substituting a factory class for the provider class used in previous versions of Hibernate. Add the following to your hibernate.cfg.xml file:

<property name="hibernate.cache.use_second_level_cache">true</property>

<property name="hibernate.cache.region.factory_class">net.sf.ehcache.hibernate.EhCacheRegionFactory</property>

For Hibernate 3.2, which cannot use the factory class, add the following to your hibernate.cfg.xml file:

<property name="hibernate.cache.use_second_level_cache">true</property>

<property name="hibernate.cache.provider_class">net.sf.ehcache.hibernate.EhCacheProvider</property>

  <bean id="mySessionFactory"

class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">

    <property name="dataSource" ref="myDataSource"/>

    </property>

<!-- Other properties, such as "mappingResources" listing Hibernate mapping files. -->

    <property name="hibernateProperties">

      <value>

        hibernate.cache.use_second_level_cache=true

hibernate.cache.region.factory_class=

                 net.sf.ehcache.hibernate.EhCacheRegionFactory

<!-- Other values, such as hibernate.dialect. -->

      </value>

    </property>

  </bean>

2.1.4b Distributed Ehcache Configuration File

Create a basic Ehcache configuration file, ehcache.xml by default:

<?xml version="1.0" encoding="UTF-8"?>

<ehcache name="Foo" 

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:noNamespaceSchemaLocation="ehcache.xsd">

      <defaultCache

        maxElementsInMemory="0"

        eternal="false"

        timeToIdleSeconds="1200"

        timeToLiveSeconds="1200">

          <terracotta />

      </defaultCache>

      <terracottaConfig url="localhost:9510" />

</ehcache>

This defaultCache configuration includes Terracotta clustering. The Terracotta client must load the configuration from a file or a Terracotta server. The value of the <terracottaConfig /> element’s url attribute should contain a path to the file or the address and DSO port (9510 by default) of a server. In the example value, "localhost:9510" means that the Terracotta server is on the local host.

ehcache.xml must be on your application's classpath. If you are using a WAR file, add the Ehcache configuration file to WEB-INF/classes or to a JAR file that is included in WEB-INF/lib .

<cache name="com.my.package.Foo" maxElementsInMemory="1000" 

       maxElementsOnDisk="10000" eternal="false" timeToIdleSeconds="3600" 

       timeToLiveSeconds="0" memoryStoreEvictionPolicy="LFU"> 

  <!-- Adding the element <terracotta /> turns on Terracotta clustering for the cache Foo. -->

  <terracotta /> 

</cache> 

UNIX/Linux

 [PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh &

Microsoft Windows

 [PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat

• 2. Start Your Application

Your application should now be running with the Terracotta second-level cache.

• 3. Start the Terracotta Developer Console.

To view the cluster along with the cache, run the following command to start the Terracotta Developer Console:

UNIX/Linux

[PROMPT] ${TERRACOTTA_HOME}/bin/dev-console.sh &

Microsoft Windows

[PROMPT] ${TERRACOTTA_HOME}\bin\dev-console.bat

• 4. On the console's initial panel, click Connect... .
• 5. In the cluster navigation tree, navigate to Terracotta cluster > My application > Hibernate .

Hibernate and second-level cache statistics, as well as other visibility and control panels should be available.

2.1.6a Procedure:

• 1. Shut down the Terracotta cluster.
• 2. Create a Terracotta configuration file called tc-config.xml with contents similar to the following:

<?xml version="1.0" encoding="UTF-8"?>

<!-- All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved. -->

<tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-4.xsd" xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <servers>

    <!-- Sets where the Terracotta server can be found. Replace the value of 

         host with the server's IP address. -->

    <server host="server.1.ip.address" name="Server1">

      <data>%(user.home)/terracotta/server-data</data>

      <logs>%(user.home)/terracotta/server-logs</logs>

    </server>

    <!-- If using a standby Terracotta server, also referred to as an ACTIVE-

         PASSIVE configuration, add the second server here. -->

    <server host="server.2.ip.address" name="Server2">

      <data>%(user.home)/terracotta/server-data</data>

      <logs>%(user.home)/terracotta/server-logs</logs>

    </server>

    <ha>

       <mode>networked-active-passive</mode>

       <networked-active-passive>

          <election-time>5</election-time>

       </networked-active-passive>

    </ha>

  </servers>

  <!-- Sets where the generated client logs are saved on clients. -->  

  <clients>

    <logs>%(user.home)/terracotta/client-logs</logs>

  </clients>

</tc:tc-config>

• 3. Install Terracotta 3.2.1 on a separate machine for each server you configure in tc-config.xml .
• 4. Copy the tc-config.xml to a location accessible to the Terracotta servers.
• 5. Perform Step 2: Install and Update the JAR files and Step 4: Edit Configuration Files steps on each application node you want to run in the cluster.

Be sure to install your application and any application servers on each node.

• 6. Edit the <terracottaConfig> element in Terracotta Distributed Ehcache for Hibernate configuration file, ehcache.xml , that you created above:

<!-- Add the servers that are configured in tc-config.xml. -->

<terracottaConfig url="server.1.ip.address:9510,server.2.ip.address:9510" />

Later in this procedure, you will see where to get more information on editing the settings in the configuration file.

• 7. Copy ehcache.xml to each application node and ensure that it is on your application's classpath (or in WEB-INF/classes for web applications).
• 8. Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in tc-config.xml :

 [PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh -f <path/to/tc-config.xml> -n Server1 &

 [PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat -f <path\to\tc-config.xml> -n Server1 &