Open source Java projects: Terracotta

A unique approach to clustering conquers scalability and fail-over

1 2 Page 2
Page 2 of 2

Listing 3's hello.jsp file loads the name attribute from the HttpSession and displays it in a "Hello, NAME" greeting. And it provides the same form from the enterYourName.jsp page that allows the user to update his or her name.

Finally, Listing 4 shows the Web deployment descriptor for this application.

Listing 4. web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" xmlns="" xmlns:xsi="" xsi:schemaLocation="">

The web.xml file defines the SessionServlet and maps requests for /SessionServlet to the SessionServlet.

Package these files into a WAR file named TerracottaExample.war with the following structure:


Using the Terracotta Sessions Configurator

To test the sample application and build a Terracotta configuration file, you'll use the Sessions Configurator. Launch the welcome application (by executing either welcome.bat or, select the Sessions tab (shown in Figure 1), and choose Terracotta Sessions Configurator.

Launching the Terracotta Sessions Configurator
Figure 1. Launching the Terracotta Sessions Configurator

When the Sessions Configurator starts, click the Import button. Or, if you close the initial dialog box, you can choose File ->Import webapp. Navigate to your WAR file and click OK, as shown in Figure 2.

 Opening a WAR application
Figure 2. Opening a WAR application

The Control tab, shown in Figure 3, shows your application configured to run in two Tomcat instances.

 Two instances of the Terracotta example application
Figure 3. Two instances of the Terracotta example application

The Terracotta Sessions enabled checkbox configures Tomcat to cluster Tomcat sessions. A simple way to see the effects of the clustering is to launch the application with this checkbox disabled and hit both servers, then launch the application with the checkbox enabled and hit both servers. Give it a try:

  1. Disable the checkbox.
  2. Click Start all.
  3. Hit both servers, which are at these URLs:
    • http://localhost:9081/TerracottaExample/SessionServlet
    • http://localhost:9082/TerracottaExample/SessionServlet
  4. Click Stop all.
  5. Enable the checkbox.
  6. Repeat steps 2 through 4.

What you should notice is that when you hit the individual servers with Terracotta Sessions disabled, the servers know nothing about each other. As a matter of fact they clobber each other's session cookie, and the results are rather random. When you enable Terracotta Sessions and then enter your name into one server, the other server is immediately aware of your name. And when you change your name on one server, the change is immediately reflected on the other server.

Figure 4 shows screen shots from both of my Tomcat servers showing the same data.

Both Tomcat instances showing the same data
Figure 4. Both Tomcat instances showing the same data

To see the data being clustered, click on the Monitor tab of the Sessions Configurator and log in using the default values: localhost on port 9520.

Figure 5 shows the Terracotta Server Monitor that I have navigated to the name attribute's value in the HttpSession.

Terracotta server monitor
Figure 5. Terracotta server monitor

Depending on your needs, you can modify the rules that Terracotta uses to determine what to cluster. In Figure 6, I've replaced the rule of clustering *..* with javax.servlet.http.HttpSession, so that Terracotta will cluster only the HttpSession object.

Configuring the clustering rules
Figure 6. Configuring the clustering rules

Once you are satisfied that your clustering is working, choose File -> Export Configuration. This generates a configuration file that you'll need to configure Tomcat with on startup to tell Terracotta which classes should be clustered.

Production deployment

To integrate Terracotta with Tomcat:

  1. Start the Terracotta Server by launching start-tc.server.bat or from the Terracotta bin folder.
  2. Update the catalina.bat or script in the Tomcat bin folder to load Terracotta and point it to your configuration file:


    . $TC_INSTALL_DIR/bin/ -q


    set TC_INSTALL_DIR=<path_to_local_terracotta_home>
    set TC_CONFIG_PATH=<path_to_local_tc-config.xml>
    %TC_INSTALL_DIR%\bin\dso-env.bat -q
  3. Start the Tomcat servers using the startup.bat or script.
  4. Hit your application on both servers and observe that the session is clustered.
  5. (Optionally) open the monitoring tab in the Sessions Configurator and find your clustered object value.

In conclusion

Terracotta's strategy is to bypass Java serialization, identifying only the components that change in stateful objects and then persisting those changes to the Terracotta server. Then when stateful objects are requested, the Terracotta client obtains the objects from the Terracotta server and injects them into the application. Bypassing Java serialization and hosting all data in a central server rather than sending data to all replicated servers aids in obtaining linear scalability. Configuring all application servers to connect to the Terracotta server and then injecting data as it is requested ensures reliability. Linear scalability and 100% reliability, all freely available as open source code -- who could ask for more?

Session clustering is but one of Terracotta's capabilities. You can use the technology to accomplish many things, including caching. For example, if you're building a new application and want to share data among multiple servers -- such as by using a distributed cache -- then Terracotta is an excellent solution: you can configure Terracotta to cluster a hashmap across all of your servers and store shared data in that hashmap.

Steven Haines is the founder and CEO of GeekCap, Inc., which provides technical e-learning courses for software developers. Previously he was the Java EE Domain Expert at Quest Software, defining software used to monitor the performance of various Java EE application servers. He is the author of Pro Java EE 5 Performance Management and Optimization, Java 2 Primer Plus, and Java 2 From Scratch. He is the Java host on and a Java Community Editor on Steven has taught Java at the University of California, Irvine and Learning Tree University.

Learn more about this topic

More from JavaWorld

1 2 Page 2
Page 2 of 2