Release: 2.4 Previous Releases
Publish Date: October, 2007

rate-6226388-27848

Article Rating?

1

2

3

4

5

Sessions Quick Start

Introduction
Installation
Starting the Configurator
Running the Configurator
Troubleshooting

Configurator Alerts
Log File Messages

Appendix

Contacting Terracotta
Platform Support

Introduction

This document describes the process of clustering HTTP session data with Terracotta. The basic process is:

Download and install Terracotta
Use the Terracotta Sessions Configurator to deploy a web application in a local test environment
Test the failover of an HTTP session from one application server instance to another to ensure proper Terracotta configuration
Deploy Terracotta in a multi-server environment

You may not need to make changes to your application or the Terracotta configuration to make it work with Terracotta Sessions. However, in some cases you may need to make modifications to the Terracotta configuration file or your application. In particular, objects like sockets, input/output streams, and other native hardware resources cannot be shared across Java Virtual Machines (JVMs). If your application adds any of these inherently non-shareable objects to the session, adjusting your application or the Terracotta configuration will be required.

Installation

Download the Terracotta binary distribution for your platform and install it.

Unix/Linux
Unzip and untar the distribution. A typical location to use for a production deployment is the /usr/local directory. For testing purposes, your home directory is appropriate.

Microsoft Windows
Run the installer for the Windows distribution. The installer guides you through the process of installing the product.

If the same version of the product has been previously installed in the same directory, the installer will backup the existing installation and perform a new install. The installer will notify the user about the backup and display the location of the new backup directory.

The installation creates an uninstaller for removing the product. The uninstaller does not delete files modified or created after the installation. These files will need to be deleted manually.

Starting the Configurator

Unix/Linux
To run Terracotta Sessions Configurator, go into the tools/sessions directory and enter the command:

./sessions-configurator.sh

Windows
To run Terracotta Sessions Configurator, go to the Start menu and choose Programs→Terracotta→Sessions→Terracotta Sessions Configurator

Running the Configurator

When you are getting started with Terracotta Sessions, you spend most of your time using the Terracotta Sessions Configurator, a graphical tool for experimenting with your web application inside a Terracotta Sessions context.

Configurator is a Java Swing application that provides a complete, automated Terracotta environment, which allows you to:

Start and stop the Terracotta server and two parallel web container instances. The default web container is Apache Tomcat.
Test your Web application and see it being clustered by Terracotta.
Enable and disable Terracotta Sessions to see its effect on your application.
Modify the Terracotta configuration and easily restart the system.
View error messages and automatically correct problems.
View the logs produced by the web containers and Terracotta software.

Start Configurator using the sessions-configurator.sh or sessions-configurator.bat script in the tools/sessions directory. On Microsoft Windows, you can also start Configurator from the Terracotta group on the Start Menu.

Useful Information

Configurator provides two web container instances because this is the minimum number that lets you check to see that your application is being clustered correctly. However, there is no limit to the number of application servers that can be supported by Terracotta Sessions in a production configuration.

Overview

The Terracotta Sessions Configurator is a single-window interface that is divided into three main sections on the right, which you control with three tabs at the top of the screen under the menu bar. These tabs are described in this section.

Terracotta Sessions Configurator

Control

Allows you to start and stop all processes (the Terracotta Server and both web container instances), view output of these processes, and provides links to each of your web applications. The Control tab also allows you to control whether Terracotta is enabled or disabled.

Configure

Allows you to view and edit the Terracotta configuration file and is subdivided into four tabs, which display at the bottom of the screen.

Tabs for configration file:

Instrumented Classes
Transient Fields
Boot Classes
tc-config.xml

The first three tabs provide access to various features of the Terracotta configuration file and the fourth shows a textual view of the configuration file.

Monitor

Provides a simplified version of the Terracotta Console, a full-featured, graphical interface that allows you to monitor many characteristics of a running Terracotta Server and the applications that are running against it.

Typically, you begin by using the Control tab. If you need to make changes to the Terracotta configuration to support your application, use the Configure tab. While you may never actually need to use the Monitor tab, it can give you an idea of the level of control and reporting that is possible in a production Terracotta system.

Selecting the Web Container

Terracotta Sessions Configurator is preconfigured to use a bundled Apache Tomcat web container. Other web containers are available from the File | Servers menu option. Each web container generally requires two properties for successful operation. The first is the location of the product home directory (such as CATALINA_HOME or BEA_HOME) and the second is the location of the Java Development Kit (JDK) to use when running the web container (speciffied by the TC_JAVA_HOME property).

Apache Tomcat 5.5
If CATALINA_HOME is not set it will default to the bundled version. If JAVA_HOME is not set it will default to the bundled version.

Apache Tomcat 5.0:
CATALINA_HOME must be set to a valid Tomcat 5.0 installation directory. JAVA_HOME must be set to a valid JDK installation directory. Note that a JDK is required for Tomcat 5.0, as opposed to a JRE.

BEA WebLogic 8.1:
BEA_HOME must be set to a valid BEA 8.1 installation directory. JAVA_HOME must be set to a valid JDK 1.4 installation directory. Note that WLS 8.1 does not work with Java 5.

Web applications that you import into the Configurator are deployed to the currently selected web container. The Terracotta provided sample web applications are pre-deployed to each of the supported web containers.

Importing Web Applications

When Configurator starts up, it offers to import an existing WAR (Web ARchive) into the Terracotta Sessions sandbox. Configurator can import a web application that is packaged as a valid WAR file. If your application is not packaged as a WAR, consult Sun's documentation to make it a WAR before importing it with Configurator.

To import Web applications in Configurator, perform the following steps:

Choose Import... from the File menu, or click the Import... button on the splash screen at startup. A standard file-chooser dialog box displays.
Use this dialog to navigate to the directory that contains your web applications and choose the application you wish to import. Configurator imports your application by copying it into the appropriate subdirectories of the web container.

Don't Just Copy Applications

It is important to use Configurator to import your application(s) rather than copying them directly because Configurator does some internal bookkeeping to ensure it knows which applications are installed.

If you choose not to import your web application, or have no web applications you wish to test with Terracotta Sessions at this time, click the Skip button on the splash screen instead. Sample web applications are provided for you in the left pane.

Cart

A simple Web application that Apache provides in its standard Tomcat distribution in the webapps/jsp-examples/sessionsdirectory. It has been updated only to provide some additional text that explains what happens as you run it with and without Terracotta Sessions enabled.

Department Task List

A Web application that demonstrates clustering an application that uses Apache Struts. The application implements a task list as the data model part of the Struts Model-View-Controller architecture. Terracotta Sessions clusters the data model enabling Struts applications to be deployed across a server farm in a fault-tolerant manner.

Townsend Camera and Supply

A Web application that contains a small product catalog of cameras and tracks the most recent cameras viewed by the user. Terracotta Sessions is used to cluster the list of recent cameras so that trips to the database are minimized and the list is available even if a server fails.

Running Your Web Applications

After your application is imported into the Terracotta Sessions "sandbox", you should first try running it without Terracotta Sessions enabled. This lets you verify that it was correctly imported and observe its behavior before session clustering is enabled.

To run your application without Terracotta Sessions enabled:

In Configurator, uncheck the Terracotta enabled checkbox and click the Start all button.Various logging messages begin to appear in both of the web container log panes.The Terracotta Configurator reports the status of each process using text and an icon above the log pane. When they are ready for use, the icon turns green.
Expand the view for your application on the left and click the blue underlined web links to open your default web browser and point it at the instances of your application.
Test your application for a while and make sure it works correctly. However, read the section Unclustered Web Applications. You will observe strange behavior if you switch back and forth between two web container instances. Because you have disabled Terracotta Sessions, no Terracotta software is running with your application right now. If you run into problems with your application, check the validity of the WAR file to make sure it matches the WAR specification.

External Dependencies

It is easy to inadvertently build many external dependencies into a web application such as paths in the filesystem or files outside of the WAR file itself. If you do this, your application may not run correctly in the sandbox whether Terracotta Sessions is enabled or not.

Unclustered Web Applications

As you switch back and forth between the two web container instances that are running your application, you may notice some strange behavior. This is because you are alternating between two web container servers running the same application, without having those servers clustered. Doing this causes the web server to continually reset your session. Here's an example of what happens:

You visit your application on port 9081. The web server notices that you have no session cookie set, and creates one for you. We'll call the value of this cookie A. So the first web server issues you a cookie with value A and creates a session for you in its internal store under the key A.

So far, as long as you only visit port 9081, things will work perfectly. However...

You then switch to your application on port 9082. Because both servers show up in the same Internet domain (here, localhost), your browser sends the web server on port 9082 the cookie with the value A.

However, the web server on port 9082 has no record whatsoever of a session with ID A. Because of this, it assumes you have a stale session record, and creates a new session for you. You're sent a replacement cookie with a value we'll call B.

Now, as long as you only visit port 9082, everything will work fine as well. However...

You then switch back to port 9081. Because the web server on port 9082 replaced your original cookie (remember, they have the same Internet domain), your browser sends the web server on port 9081 the value B for your cookie.However, the web server on port 9081 has no record whatsoever of a session with ID B. Because of this, it assumes you have a stale session record and creates a new session for you. You are then sent a replacement cookie with a value we will call C.

...and the cycle repeats.

Being aware of this set of issues is important as you test web applications when running without Terracotta. This behavior will happen any time you host a single website on multiple servers without clustering their sessions. The best way to avoid this scenario is to enable Terracotta Sessions. After you make sure that your application works correctly on one node without Terracotta enabled, click the Stop all button to shut everything down.

Clustered Web Applications

Click the Terracotta enabled checkbox to turn on Terracotta Sessions and then click Start all again.

Assume, for the moment, that your application does not use any unsupported classes or other features that require some modifications to make your application work with Terracotta Sessions. Try using your application on only one of the web containers. For example, click the 9081 link for your application and use that browser window only. You should notice no change from before and it should still behave correctly.

However, Terracotta Sessions is now automatically and transparently clustering your session data, sharing it between the two web container instances on demand. If you click the other web container link (for example, the 9082 link) you should be able to use your application just as if nothing has changed, which is the whole point. Terracotta is sharing session data across the two web container instances at a fine-grained, field-change level, all without changes to your application code.

When Web Application Issues Arise

It is possible that your web application adds objects to the servlet session which either are fundamentally unclusterable (like java.net.Socket, for example), or require additional Terracotta configuration in order to be clustered (certain classes in the java. package hierarchy, for example). If so, you will either see failures in your application, or more likely, error messages presented from Configurator or in the logs.

If this happens, refer to the Troubleshooting chapter. Many issues that you may run into can be corrected with a simple mouse click or two, enabling you to solve them in a short amount of time.

Troubleshooting

This section covers topics about solving problems encountered attempting to cluster an application.

Configurator Alerts

In some cases, you may find that your application does not work immediately when used with Terracotta Sessions. Fortunately, correcting these issues is usually straightforward and can often be done automatically for you by Configurator.

Typically, Configurator displays a dialog box when these issues occur. This dialog identifies the problem and, when possible, offers to correct it for you. See below for an example of what happens when you attempt to share an object of a class from the java. hierarchy that is not pre-instrumented by the Terracotta runtime:

Configurator Alert Dialog

If the issue is one that can be corrected by Configurator automatically, you will have the option to do so. Clicking Yes in this dialog stops all servers, modifies the Terracotta configuration as appropriate, and restarts all servers automatically. If there are no more issues preventing your application from running with Terracotta Sessions, troubleshooting is complete. If more issues remain another error message will display, and the process repeats.

If the issue is one that can't be corrected by Configurator automatically, you can make the changes to correct the issue yourself. These changes are usually easy. Refer to the topics in this section for descriptions of each particular issue for more details on how to correct them.

Useful Information

If you encounter alerts or other error messages beyond the scope of this document, post a question to: http://forums.terracotta.org/

Log File Messages

In addition to the alerts that Configurator displays, the log files produced by the Terracotta Clients running as part of the web container instances also contain copies of error messages that occur during the execution of your application. The log files are in the tools/sessions/configurator-sandbox/logs/client-logs and tools/sessions/configurator-sandbox/<server-name>/logs/server-logs directories.
The Terracotta Server writes log messages directly to its standard output and standard error streams, which appear directly in Configurator's pane for the Terracotta Server. The Terracotta Server is configured this way for ease of use with Terracotta Sessions. Generally, it writes its logs to files.

Tip

If you are running the Terracotta Server manually, you may wish to redirect its standard output and error streams to a file in order to view its output more easily.

Error messages (coming from Configurator instances) display output similar to this example in the Terracotta Client logs:

2006-05-09 18:23:16,250 [docs22:http-9081-Processor9] ERROR com.tc.object.ClientObjectManager
- ChannelID=[1]: com.tc.exception.TCNonPortableObjectException:
**************************************************************************************
Attempt to share an instance of a non-portable class by passing it as an argument to a
method of a logically-managed class. This unshareable class must be in the DSO boot
jar. It also has superclasses which must be in the DSO boot jar. Please add all of
these classes to the boot jar configuration and re-create the DSO boot jar.

Thread : http-9081-Processor9
JVM ID : VM(1)
Logically-managed class name: java.util.HashMap
Logical method name : put()
Classes to add to boot jar : java.awt.geom.Arc2D, java.awt.geom.Arc2D$Double
**************************************************************************************

The error messages contain the same information as the alerts that Configurator produces.

Appendix

Contacting Terracotta

Contact Terracotta at the following:
Web site: http://www.terracotta.org
Online forums: http://forums.terracottatech.com/forums/
Information: info@terracottatech.com

Platform Support

See Platform Support for information on which platforms are supported by Terracotta.
See Integrations to see the status of integrations with third-party technologies.

Copyright Information

This publication (the "Documentation") and the Terracotta software which it describes (the "Software") are protected to the maximum extent permitted under applicable law, including but not limited to, the regulations set forth in Title 17 of the United States Code, and California law. This Documentation, or any parts thereof, may not be reproduced in any form, by any method, for any purpose, without the express written consent of Terracotta. Terracotta makes no warranty, either express or implied, including but not limited to any implied warranties of merchantability or fitness for a particular purpose, with respect to the Software discussed in this Documentation, and the Documentation itself (collectively, "the Materials"). The Materials are made available solely on an "as-is" basis. In no event shall Terracotta be liable to anyone for special, collateral, incidental, indirect, punitive, exemplary, or consequential damages in connection with, or arising from the purchase or use of, the Materials. Under no circumstances and regardless of the cause of action alleged, shall Terracotta's liability exceed the purchase price of the Software described herein. Terracotta reserves the right to revise and improve its Software and Documentation as it deems fit. The Documentation describes the state of the Software at the time of publication.

Trademarks
"Terracotta," the stylized "T" logo, and "Open Terracotta" are trademarks of Terracotta. All other brand names, product names, or trademarks belong to their respective holders. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other brand names, product names, or trademarks belong to their respective holders.

Government Use
Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer Software-Restricted Rights) and DFAR 267.7202 (Rights in Technical Data and Computer Software), as applicable.