This site hosts historical documentation. Visit www.terracotta.org for recent product information.
To cluster your application's web sessions, add the following two JAR files to your application's classpath, and place these files in the WEB-INF/lib
folder of the Web Application Archive (WAR) on all of your application servers. These files are under ${TERRACOTTA_HOME}/.
sessions/lib/web-sessions-<version>.jar
<version> is the current version of the Terracotta Web Sessions JAR.
apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar
The Terracotta Toolkit JAR contains the Terracotta client libraries. <version> is the current version of the Terracotta Toolkit JAR.
Terracotta servers, and Terracotta clients running on the application servers in the cluster, are configured with a Terracotta configuration file, tc-config.xml
by default. Servers that are not started with a specified configuration will use a default configuration.
To add Terracotta clustering to your application, you must specify how Terracotta clients get their configuration by including the source in your web.xml
file. Add the following configuration snippet to web.xml
:
<filter>
<filter-name>terracotta</filter-name>
<!-- The filter class is specific to the application server. -->
<filter-class>org.terracotta.session.{container-specific-class}</filter-class>
<init-param>
<param-name>tcConfigUrl</param-name>
<!-- <init-param> of type tcConfigUrl has a <param-value> element containing
the URL or filepath (for example, /lib/tc-config.xml) to tc-config.xml.
If the Terracotta configuration source changes at a later time,
it must be updated in configuration. -->
<param-value>localhost:9510</param-value>
</init-param>
<!-- The following init-params are optional.
<init-param>
<param-name>synchronousWrite</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>sessionLocking</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>maxBytesOnHeap</param-name>
<param-value>128M</param-value>
</init-param>
<init-param>
<param-name>maxBytesOffHeap</param-name>
<param-value>4G</param-value>
</init-param>
<init-param>
<param-name>rejoin</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>nonStopTimeout</param-name>
<param-value>-1</param-value>
</init-param>
<init-param>
<param-name>concurrency</param-name>
<param-value>0</param-value>
</init-param>
<!-- End of optional init-params. -->
</filter>
<filter-mapping>
<!-- Must match filter name from above. -->
<filter-name>terracotta</filter-name>
<url-pattern>/*</url-pattern>
<!-- Enable all available dispatchers. -->
<dispatcher>ERROR</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-name> can contain a string of your choice. However, the value of <filter>/<filter-name> must match <filter-mapping>/<filter-name>.
Choose the appropriate value for <filter-class> from the following table.
Container | Value of <filter-class> |
---|---|
GlassFish | org.terracotta.session.TerracottaGlassfish31xSessionFilter |
JBoss 6.1.x | org.terracotta.session.TerracottaJboss61xSessionFilter |
JBoss 7.1.x | org.terracotta.session.TerracottaJboss71xSessionFilter |
JBoss 7.2.x | org.terracotta.session.TerracottaJboss72xSessionFilter |
Jetty 8.1.x | org.terracotta.session.TerracottaJetty81xSessionFilter |
Jetty 9.0.x | org.terracotta.session.TerracottaJetty90xSessionFilter |
Resin | org.terracotta.session.TerracottaResin40xSessionFilter |
Tomcat 6.0.x | org.terracotta.session.TerracottaTomcat60xSessionFilter |
Tomcat 7.0.x | org.terracotta.session.TerracottaTomcat70xSessionFilter |
WebLogic 10.3.x | org.terracotta.session.TerracottaWeblogic103xSessionFilter |
WebLogic 12.1.x | org.terracotta.session.TerracottaWeblogic121xSessionFilter |
WebSphere 7.0.x | org.terracotta.session.TerracottaWebsphere70xSessionFilter |
WebSphere 8.0.x | org.terracotta.session.TerracottaWebsphere80xSessionFilter |
WebSphere 8.5.x | org.terracotta.session.TerracottaWebsphere85xSessionFilter |
Ensure that the Terracotta filter is the first <filter> element listed in web.xml
. Filters processed ahead of the Terracotta filter may disrupt its processing.
web.xml
should be in /WEB-INF
if you are using a WAR file.
For more information about the optional init-params, refer to the Web Sessions Reference Guide.
For Terracotta to function properly, make sure that your JAVA_HOME setting is set.
Start the Terracotta server:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/server/bin/start-tc-server.sh
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\server\bin\start-tc-server.bat
Start your management console (any JMX monitoring tool is fine) and connect it to your application server. For more information about Terracotta and JMX, refer to JMX Management and Monitoring.
The console below displays the Web Sessions MBeans.
The following table describes the Web Sessions MBeans:
MBean | Data Type | Description |
---|---|---|
Average Session Lifetime | Integer | Average local session lifetime (in seconds) @return average session lifetime, or -1 if no sessions have expired. |
Average Session Size | Long | Average local session size (in bytes). |
Concurrency | (Integer) | Number of segments for the map backing the underlying server store managed by the Terracotta Server Array. If concurrency is not explicitly set (or set to "0"), the system selects an optimized value. |
Context Path | String | Context path for this servlet context. |
Global Number Of Sessions | Long | Total number of live sessions that exist in the cluster. |
Hit Ratio | Double | Local hit ratio of the sessions cache @return hit ratio n, or NaN if unavailable. |
Max Bytes Off Heap | Long | Maximum number of bytes allowed in the off-heap tier. |
Max Bytes On Heap | Long | Maximum number of bytes allowed in the heap tier. |
Maximum Session Lifetime | Integer | Maximum local session lifetime (in seconds) @return maximum session lifetime, or -1 if no sessions have expired. |
Minimum Session Lifetime | Integer | Minimum local session lifetime (in seconds) @return minimum session lifetime, or -1 if no sessions have expired. |
Nonstop Timeout | Long | Number of milliseconds an application waits for any cache operation to return before timing out, or -1 if no timeout is configured. |
Number Of Sessions | Long | Number of session objects in local memory. |
Rejoin Enabled | Boolean | Whether client is configured to automatically rejoin its cluster if ejected. |
Session Locking | Boolean | Whether session locking is enabled. |
Session Timeout Seconds | Integer | Number of seconds a session waits before timing out, or -1 if no timeout is configured. |
Sessions Created Count | Long | Number of sessions created locally since initial startup. |
Sessions Creation Rate | Long | Rate of local session creation since initial startup. This number represents the number sessions created in the previous minute. |
Synchronous Write | Boolean | Whether configured to synchronously flush enclosed changes to the Terracotta Server Array, blocking the unlocking thread until changes have been acknowledged as committed. |
Total Session Size | Long | Total local session size (in bytes). |
This step shows you how to run clients and servers on separate machines and add failover (High Availability). You will expand the Terracotta cluster and add High Availability by doing the following:
These tasks bring your cluster closer to a production architecture.
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-8.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>
</servers>
<!-- Sets where the generated client logs are saved on clients. -->
<clients>
<logs>%(user.home)/terracotta/client-logs</logs>
</clients>
</tc:tc-config>
tc-config.xml
.tc-config.xml
to a location accessible to the Terracotta servers.Edit web.xml
on each application server to list both Terracotta servers:
<param-value>server.1.ip.address:9510,server.2.ip.address:9510</param-value>
Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in tc-config.xml
:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/server/bin/start-tc-server.sh -f <path/to/tc-config.xml> \
-n Server1
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\server\bin\start-tc-server.bat -f <path\to\tc-config.xml> ^
-n Server1
If you configured a second server, start that server in the same way on its machine, entering its name after the -n
flag. The second server to start up becomes the hot standby, or PASSIVE. Any other servers you configured will also start up as standby servers.
To learn more about working with a Terracotta cluster, see the following documents:
tc-config.xml
is propagated and loaded in a Terracotta cluster in different environments.