4.1 Web Sessions Express Installation

4.1.3a Jetty, WebLogic, and WebSphere

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. -->

    <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>&lt;tc:tc-config ... &lt;/tc:tc-config&gt;</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 if you are using a WAR file.

4.1.3b JBoss AS and Tomcat

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="&lt;tc:tc-config ... &lt;/tc:tc-config&gt;">

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.

UNIX/Linux

[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh &

Microsoft Windows

[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat

• 2. Start the application servers.
• 3. Start the Terracotta Developer Console:

UNIX/Linux

[PROMPT] ${TERRACOTTA_HOME}/bin/dev-console.sh &

Microsoft Windows

[PROMPT] ${TERRACOTTA_HOME}\bin\dev-console.bat

• 4. Connect to the Terracotta cluster.

Click Connect... in the Terracotta Developer Console.

• 5. Click the Topology node in the cluster navigation window to see the Terracotta servers and clients (application servers) in the Terracotta cluster.

Your console should have a similar appearance to the following figure.

4.1.5a Procedure:

• 1. Shut down the Terracotta cluster.
• 2. 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-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>

<!-- If using more than one server, add an <ha> section. -->

    <ha>

       <mode>networked-active-passive</mode>

       <networked-active-passive>

               <election-time>5</election-time>

       </networked-active-passive>

    </ha>

  </servers>

  <!-- Sets where the generated client logs are saved on clients. -->  

  <clients>

    <logs>%(user.home)/terracotta/client-logs</logs>

  </clients>

</tc:tc-config>

• 3. Install Terracotta 3.2.1 on a separate machine for each server you configure in tc-config.xml .
• 4. Copy the tc-config.xml to a location accessible to the Terracotta servers.
• 5. Perform Step 2: Install the Terracotta Sessions JAR on each application node you want to run in the cluster.

Be sure to install your application and any application servers on each node.

• 6. Edit web.xml or context.xml on each application server to list both Terracotta servers:

<param-value>server.1.ip.address:9510,server.2.ip.address:9510</param-value>

or

tcConfigUrl="server.1.ip.address:9510,server.2.ip.address:9510"

• 7. Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in 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 &