The content you have selected is available exclusively to Terracotta, Ehcache, and Quartz community members. If you are already a member, please login. If not, please take a moment to become one. Please sign up to join the Terracotta, Ehcache, and Quartz communities. Membership is free and only requires you to complete the form below. In addition to full documentation access, you will also be eligible to attend product briefings, download select early access product releases before the general public, post forum questions, file bug reports, submit patches and receive other member benefits still to come.
(But you're not quite done—you still need to validate your account. Please check your email!)
Thanks for joining the Terracotta and Ehcache community. You will recieve an e-mail shortly containing instructions for validating your account and downloading Ehcache EX.
After you validate your account, you will have full access to all Terracotta and Ehcache community resources, such as:
This document shows you how to cluster web sessions without the requirements imposed by Terracotta DSO, including cluster-wide locking, class instrumentation, and class portability.
Download the kit and run the installer on the machine that will host the Terracotta server.
If you cannot use Serializable classes, you must use the custom web-sessions installation. Clustering non-serializable classes is not supported with the express installation.
To cluster your application’s web sessions, add the following JAR file to your application's classpath:
where <version> is the current version of the Terracotta Sessions JAR. The Enterprise trial kit contains
terracotta-session-ee-<version>.jar
in place of
terracotta-session-<version>.jar
.
See the following table on suggestions on where to add the Terracotta Sessions JAR based on application server.
|
The table above lists the only application servers supported by the express installation. See
Platform Support
to obtain the latest versions for the listed application servers.
|
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 not started with a specified configuration 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
web.xml
or
context.xml
.
Find the configuration to use for your application server in the sections below.
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>
<!-- <param-value> of type tcConfigUrl has a <param-value> containing the URL or filepath (for example, /lib/tc-config.xml) to tc-config.xml. -->
<param-value>localhost:9510</param-value>
</init-param>
</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.
If you have customized a Terracotta configuration file and want to include its contents rather than providing an URL, use an <init-param> of type
tcConfig
:
<init-param>
<param-name>tcConfig</param-name>
<param-value><tc:tc-config ... </tc:tc-config></param-value>
</init-param>
Use URL-safe codes (also known as "URL escaping") or HTML names for all special characters such as angle brackets ("<" and ">").
Ensure that the Terracotta filter is the first <filter> element listed in
web.xml
. Filters processed ahead of the Terracotta valve may disrupt its processing.
web.xml
should be in
WEB-INF/lib
if you are using a WAR file.
Add the following to
context.xml
:
<valve className="org.terracotta.session.<container-specific-class>" tcConfigUrl="localhost:9510">
where
tcConfigUrl
contains an URL or file path (for example,
tcConfigURL="/lib/tc-config.xml"
) to
tc-config.xml
.
If you have customized a Terracotta configuration file and want to include its contents rather than providing an URL, replace tcConfigUrl with tcConfig:
<Valve className="org.terracotta.session.<container-specific-class>" tcConfig="<tc:tc-config ... </tc:tc-config>">
Use URL-safe codes (also known as "URL escaping") or HTML names for all special characters such as angle brackets ("<" and ">"). Choose the appropriate value of className from the following table.
For example, to use Tomcat 6.0, the content of
context.xml
should be similar to the following:
<Context>
<Valve className="org.terracotta.session.TerracottaTomcat60xSessionValve" tcConfigUrl="localhost:9510"/>
</Context>
Ensure that the Terracotta valve is the first <valve> element listed in
context.xml
. Valves processed ahead of the Terracotta valve may disrupt its processing.
If you are using a WAR file,
context.xml
should be in
META-INF
for Tomcat and in
WEB-INF
for JBoss Application Server.
This step shows you how to how 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.
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-5.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.Be sure to install your application and any application servers on each node.
web.xml
on each application server to list both Terracotta servers in the
tcConfigUrl
attribute:tcConfigUrl="server.1.ip.address:9510,server.2.ip.address:9510"
<param-value>localhost:9510</param-value>
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 &
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.