About Terracotta Documentation
This documentation is about Terracotta DSO, an advanced distributed-computing technology aimed at meeting special clustering requirements.
Terracotta products without the overhead and complexity of DSO meet the needs of almost all use cases and clustering requirements. To learn how to migrate from Terracotta DSO to standard Terracotta products, see Migrating From Terracotta DSO. To find documentation on non-DSO (standard) Terracotta products, see Terracotta Documentation. Terracotta release information, such as release notes and platform compatibility, is found in Product Information.
- How DSO Clustering Works
- Platform Concepts
- Hello Clustered World
- Setup and Configuration
- Planning for a Clustered App
- Configuring Terracotta DSO
- Configuration Reference
- Using Annotations
- Cluster Events
- Data Locality Methods
- Distributed Cache
- Clustered Async Data Processing
- Tool Guides
- Developer Console
- Operations Center
- tim-get (TIM Management Tool)
- Platform Statistics Recorder
- Eclipse Plugin
- Sessions Configurator
- Clustering Spring Webapp with Sessions Configurator
- Testing, Tuning, and Deployment
- Top 5 Tuning Tips
- Testing a Clustered App
- Tuning a Clustered App
- Deployment Guide
- Operations Guide
- FAQs and Troubleshooting
- General FAQ
- DSO Technical FAQ
- Troubleshooting Guide
- Non-portable Classes
- Migrating From DSO
- Concept and Architecture Guide
- Examinator Reference Application
- Clustered Data Structures Guide
- Integrating Terracotta DSO
- Clustering Spring Framework
- Integration Modules Manual
- AspectWerkz Pattern Language
Publish Date: November, 2011
- What You'll Need
- What You'll See
- Getting Started
- Build the Spring JPetStore Sample
- Start the JPetStore Database
- Start the Terracotta Sessions Configurator
- Import the JPetStore WAR
- Start the Application Servers Without Terracotta
- View the Application Unclustered
- Start the Application Servers With Terracotta
- Inspect the Clustered Session Object Graph
This tutorial shows how to configure a web application for session clustering using Terracotta Sessions. By the end of the tutorial, you should be ready to use Terracotta Sessions on your own Web applications.
- Terracotta Software
- The Spring Framework - We'll be using the Spring JPetStore example application.
- Apache Ant
At the end of the tutorial, you will have multiple application servers running a web application with clustered sessions.
The basic steps of this tutorial are:
- Download and install Terracotta.
- Download Spring and build the Spring JPetStore sample.
- Start the JPetStore database.
- Start the Terracotta Sessions Configurator
- Import the JPetStore WAR into the Terracotta Sessions Configurator.
- Start the application servers without Terracotta enabled. Verify that the application works without Terracotta and that its sessions are not clustered.
- Restart the application with Terracotta enabled. Verify that session clustering works.
- Inspect the clustered sessions object graph. Terracotta enables runtime visibility into live clustered objects.
- Download and install
html: Notify your Confluence administrator that "Bob Swift Atlassian Add-ons - HTML" requires a valid license. Reason: EXPIRED <a href="/dl/">Terracotta</a>.
- Download and unzip The Spring Framework. We'll be using the JPetStore sample application that comes with the Spring Framework kit.
- Download and install Apache Ant if you don't have it installed already. Detailed instructions for installing Ant are in the Apache Ant Manual
Note: For more detailed instructions on building the JPetStore sample, see the readme.txt file in the jpetstore samples directory.
- Change directories to <spring_dir>/samples/jpetstore
- Run ant warfile
This will leave the JPetStore WAR file in <spring_dir>/samples/jpetstore/dist/jpetstore.war
- Change directories to <spring_dir>/samples/jpetstore/db/hsqldb/
- Run the server.sh script.
You can obtain the Sessions Configurator from the Terracotta forge. See the README.txt for information on how to run the Sessions Configurator. See the Sessions Configurator Guide for an introduction to the Sessions Configurator.
Note: If the welcome screen is not visible, you can use the File -> Import... menu.
Import the JPetStore application by clicking the Import... button.
Use the file chooser to select <spring_dir>/samples/jpetstore/dist/jpetstore.war
Ensure that the Terracotta Sessions enabled checkbox is NOT selected. Click the Start all button to start the application servers.
This will start two instances of the application server in two separate Java Virtual Machines. Each of these application servers has its own instance of the web applications deployed inside them. The first few applications are Terracotta sample applications. You should see the JPetStore application listed below.
When the application servers have started, the hyper links to the different instances of the web applications will become active.
Click on the http://localhost:9081/jpetstore/_ link. This will open your browser to the application server instance listening on port 9081.
Click on the Enter the Store link.
You should see the JPetStore homepage.
Note: If you get an error that says "Could not open JDBC Connection for transaction", the JPetStore database is not running. Go back to that step and start the database.
Browse to one of the product pages and add an item to your shopping cart. Your cart should look something like this:
Now switch back to the Terracotta Sessions Configurator and click on the http://localhost:9082/jpetstore/ link. This will open your browser to the application server instance listening on port 9082.
In the new browser window, click the shopping cart icon. You should see an empty shopping cart.
Because the two application servers, 9081 and 9082, are running in separate JVMs and they aren't clustered, the session data that contained your shopping cart items is lost when you move from one application server to the next. The result is frustrated customers and lost sales.
This is precisely what happens when multiple application servers are load balanced and user sessions move from one application server to another. This may happen, for example, in the event that one or more application servers have crashed or have been taken down for maintenance.
Now let's watch what happens to your shopping cart when Terracotta session clustering is turned on.
Switch back to the Terracotta Sessions Configurator and stop the application servers by clicking on the Stop all button.
When the servers have stopped, click on the Terracotta Sessions enabled checkbox.
Click on the Start all button and, this time, the application servers will start with Terracotta session clustering enabled.
When the servers have started, go through the same process of adding items to you cart in one server and checking the contents of the cart in the other server:
- Click on the http://localhost:9081/jpetstore/ link.
- Enter the store and add an item to your cart.
- Switch back to the Terracotta Sessions Configurator a click on the http://localhost:9082/jpetstore/ link.
- In the new browser window, browse to the shopping cart. Your shopping cart from the server on port 9081 should be intact on the server on port 9082.
Switch back to the Terracotta Sessions Configurator and click on the Monitor tab at the top of the window.
Expand the Roots tree and select the tc:tomcat_session_jpetstore element.
This is a real-time view of the clustered session object graphs. These are the plain Java objects that are currently in your session.
Note: to refresh the object graph view, click on the element or select it and press F5 on your keyboard. You can also right-click on an element to see a context menu.
Explore the object tree to see what's in the session. You should be able to find individual shopping cart items in the graph. Try changing the quantities of certain items in your cart and updating the object graph view in the Terraotta Sessions Configurator. You should be able to see the changes to those objects in the object graph view.
This tutorial has taken you through the process of importing a web application into the Terracotta Sessions Configurator and viewing the application with Terracotta session clustering disabled and enabled. Terracotta Sessions Configurator is an easy way to get started with Terracotta and to watch the behavior of your clustered application at runtime.