9/15

# 3 Installing Coherence*Web on Other Application Servers

This chapter provides instructions on how to use the Coherence*Web WebInstaller to install Coherence*Web for Java EE applications on a variety of different application servers.

Before Proceeding:

Consult the "Supported Web Containers" to see if you must perform any application server-specific installation steps.

When deploying Coherence*Web on WebLogic Server you now have two options:

- Use the WebInstaller approach described in this chapter

- Use the SPI-based installation for WebLogic Server 11gR1 or later. See Chapter 2, "Using Coherence*Web with WebLogic Server."

## 3.1 Installing Coherence*Web Using the WebInstaller

Coherence*Web can be enabled for Java EE applications on several different Web containers. To do this, you must run the ready-to-deploy application through the automated Coherence*Web WebInstaller before deploying it. The automated installer prepares the application for deployment. It performs the installation process in two discrete steps: an inspect step and an install step. For more information on what the installer does during these steps, see "How the Coherence*Web Installer Instruments a Java EE Application".

The installer can be run either from the Java command line or from Ant tasks. The following sections describe the Java command line method. For Ant task-based installation, see "Coherence*Web WebInstaller Ant Task".

### 3.1.1 Application Server-Specific Installation Instructions

All of the Web containers listed in "Supported Web Containers" that can be installed with the WebInstaller share the same general installation instructions. These instructions are described in "General Instructions for Installing Coherence*Web Session Management Module".

A few of the Web containers, such as Caucho Resin, and WebLogic 10.x, require extra, container-specific steps that you must complete before starting the general installation procedure. The following sections describe application server-specific installation steps.

- Installing on Oracle WebLogic 10.x

- Installing on Caucho Resin 3.1.x

#### 3.1.1.1 Installing on Oracle WebLogic 10.x

Complete the following steps to install the Coherence*Web Session Management Module into an Oracle WebLogic 10-10.2 server:

1. From within the Coherence library directory, extract the `coherence-web.jar` from the `webInstaller.jar`:

       jar -xvf webInstaller.jar web-install/coherence-web.jar

   This command extracts the `coherence-web.jar` file into a subdirectory named `web-install`. Use the following commands to move the `coherence-web.jar` file up one level into the library directory:

   On Windows:

       move web-install\coherence-web.jar .
       rmdir web-install

   On UNIX:

       mv web-install/coherence-web.jar .
       rmdir web-install

2. For each WebLogic 10.x installation that will be running in the server cluster, update the libraries using the following command:

       java -cp coherence.jar;coherence-web.jar com.tangosol.coherence.servlet.WebPluginInstaller <wls-home-path> -install

   For example, on Windows:

       java -cp coherence.jar;coherence-web.jar com.tangosol.coherence.servlet.WebPluginInstaller C:\bea\weblogic\wlserver_10 -install

3. Follow the instructions described in "General Instructions for Installing Coherence*Web Session Management Module" to complete the installation. Use the value `WebLogic/10.x` for the server type.

#### 3.1.1.2 Installing on Caucho Resin 3.1.x

Complete the following steps to install the Coherence*Web Session Management Module into a Caucho Resin 3.1.x server:

1. From within the Coherence library directory, extract the `coherence-web.jar` from the `webInstaller.jar`:

       jar -xvf webInstaller.jar web-install/coherence-web.jar

   This command extracts the `coherence-web.jar` file into a subdirectory named `web-install`. Use the following commands to move the `coherence-web.jar` file up one level into the library directory:

   On Windows:

       move web-install\coherence-web.jar .
       rmdir web-install

   On UNIX:

       mv web-install/coherence-web.jar .
       rmdir web-install

2. For each Resin installation that will be running in the server cluster, update the libraries using the following command:

       java -cp coherence.jar;coherence-web.jar
       com.tangosol.coherence.servlet.WebPluginInstaller <resin-home-path> -install

   For example, on Windows:

       java -cp coherence.jar;coherence-web.jar
       com.tangosol.coherence.servlet.WebPluginInstaller C:\opt\resin31 -install

3. Follow the instructions described in "General Instructions for Installing Coherence*Web Session Management Module" to complete the installation. Use the value `Resin/3.1.x` for the server type.

### 3.1.2 General Instructions for Installing Coherence*Web Session Management Module

Complete the following steps to install Coherence*Web for a Java EE application on any of the Web containers listed under "Supported Web Containers".

If you are installing Coherence*Web for a Java EE application on an Apache Tomcat Server, see also "Enabling Sticky Sessions for Apache Tomcat Servers" for additional instructions.

If you are installing Coherence*Web for a Java EE application on IBM WebSphere Server, see also "Decoding URL Session IDs for IBM WebSphere 7.x Servers" for additional instructions.

To install Coherence*Web for the Java EE application you are deploying:

1. Make sure that the application directory and the `.ear` file or `.war` file are not being used or accessed by another process.

2. Change the current directory to the Coherence library directory (%COHERENCE_HOME%`\lib` on Windows and $COHERENCE_HOME`/lib` on UNIX).

3. Make sure that the paths are configured so that Java commands will run.

4. Complete the application inspection step by running the following command. Specify the full path to your application and the name of your server found in Table 1-1 (replacing the `<app-path>` and `<server-type>` with them in the command line below):

       java -jar webInstaller.jar <app-path> -inspect -server:<server-type>

   The system will create (or update, if it already exists), the `coherence-web.xml` configuration descriptor file for your Java EE application in the directory where the application is located. This configuration descriptor contains the default Coherence*Web settings for your application recommended by the installer.

5. If necessary, review and modify the Coherence*Web settings based on your requirements.

   You can modify the Coherence*Web settings by editing the `coherence-web.xml` descriptor. Appendix A, "Coherence*Web Context Parameters," describes the Coherence*Web settings that can be modified. Use the `param-name` and `param-value` subelements of `context-param` to enable the features you want. The following list provides some examples of different settings:

   - The setting inTable 3-1 will cluster all `ServletContext` ("global") attributes so that servers in a cluster share the same values for those attributes, and also receive the events specified by the Servlet Specification when those attributes change:

     Table 3-1 Settings to Cluster ServletContext Attributes

     Parameter | Value
     --- | ---
     `param-name` | `coherence-servletcontext-clustered`
     `param-value` | `true`

   - The setting in Table 3-2 allows an application to enumerate all of the sessions that exist within the application, or to obtain any one of those sessions to examine or manipulate:

     Table 3-2 Settings to Enumerate All Sessions in the Application

     Parameter | Value
     --- | ---
     `param-name` | `coherence-enable-sessioncontext`
     `param-value` | `true`

   - The setting in Table 3-3 enables you to increase the length of the `HttpSession` ID, which is generated using a `SecureRandom` algorithm; the length can be any value, although in practice it should be small enough to fit into a cookie or a URL (depending on how session IDs are maintained.) Increasing the length can decrease the chance of a session being purposefully hijacked:

     Table 3-3 Settings to Increase Length of HTTPSession ID

     Parameter | Value
     --- | ---
     `param-name` | `coherence-session-id-length`
     `param-value` | `32`

   - By default, the `HttpSession` ID is managed in a cookie. If the application supports URL encoding, set the option described in Table 3-4 to enable it:

     Table 3-4 Settings to Support URI Encoding

     Parameter | Value
     --- | ---
     `param-name` | `coherence-session-urlencode-enabled`
     `param-value` | `true`

6. Complete the Coherence*Web application installation step by running the following command, replacing `<app-path>` with the full path to your application:

       java -jar webInstaller.jar <app-path> -install

   The installer requires a valid `coherence-web.xml` configuration descriptor to reside in the same directory as the application.

7. Deploy the updated application and verify that everything functions as expected, using the lightweight load balancer provided with the Coherence distribution. Remember that the lightweight load balancer is not a production-ready utility, in contrast to the load balancer provided by WebLogic Server.

Enabling Sticky Sessions for Apache Tomcat Servers

If you want to employ sticky sessions for the Apache Tomcat Server, you must configure the `jvmRoute` attribute in the server's `server.xml` file. You can find more information on this attribute at this URL:

`http://tomcat.apache.org/connectors-doc/reference/workers.html`

Decoding URL Session IDs for IBM WebSphere 7.x Servers

If set to `true`, the `coherence-session-urldecode-bycontainer` context parameter allows the container to decode the URL. This context parameter must be set to `false` if you are installing Coherence*Web for a Java EE application on release 7.x of the IBM WebSphere application server. Instead of the WebSphere application server, Coherence*Web will handle the decoding of session IDs.

The Coherence*Web WebInstaller, when run for the WebSphere 7.x application server type, will automatically set this parameter to `false` unless you explicitly set it to `true`.

### 3.1.3 Coherence*Web WebInstaller Ant Task

The Coherence*Web WebInstaller Ant task enables you to run the installer from within your existing Ant build files.

This section contains the following information:

- Using the WebInstaller Ant task

- Configuring the WebInstaller Ant Task

- WebInstaller Ant Task Examples

#### 3.1.3.1 Using the WebInstaller Ant task

To use the Coherence*Web WebInstaller Ant task, add the task import statement illustrated in Example 3-1 to your Ant build file. In this example, `${``coherence.home``}` refers to the root directory of your Coherence installation.

Example 3-1 Task Import Statement for Coherence*Web WebInstaller

    <taskdef name="cwi" classname="com.tangosol.coherence.misc.CoherenceWebAntTask">
        <classpath>
            <pathelement location="${coherence.home}/lib/webInstaller.jar"/>
        </classpath>
    </taskdef>

The following procedure describes the basic process of installing Coherence*Web into a Java EE application from an Ant build.

1. Build your Java EE application as you normally would.

2. Run the Coherence*Web Ant task with the `operations` attribute set to `inspect`.

3. Make any necessary changes to the generated Coherence*Web XML descriptor.

4. Run the Coherence*Web Ant task with the `operations` attribute set to `install`.

If you are performing iterative development on your application (such as modifying JSPs, Servlets, static resources, and so on), use the following installation process:

1. Run the Coherence*Web Ant task with the `operations` attribute set to `uninstall`, the `failonerror` attribute set to `false`, and the `descriptor` attribute set to the location of the previously generated Coherence*Web XML descriptor (from Step 2 above).

2. Build your Java EE application as you normally would.

3. Run the Coherence*Web Ant task with the `operations` attribute set to `inspect`, `install` and the `descriptor` attribute set to the location of the previously generated Coherence*Web XML descriptor (from Step 2 above).

To change the Coherence*Web configuration settings of a Java EE application that has Coherence*Web installed, use this procedure:

1. Run the Coherence*Web Ant task with the `operations` attribute set to `uninstall` and the `descriptor` attribute set to the location of the Coherence*Web XML descriptor for the Java EE application.

2. Change the necessary configuration parameters in the Coherence*Web XML descriptor.

3. Run the Coherence*Web Ant task with the `operations` attribute set to `install` and the `descriptor` attribute set to the location of the modified Coherence*Web XML descriptor (from Step 2).

#### 3.1.3.2 Configuring the WebInstaller Ant Task

Table 3-5 describes the attributes that can be used with the Coherence*Web WebInstaller Ant Task.

Table 3-5 Coherence*Web WebInstaller Ant Task Attributes

Attribute | Description | Required?
--- | --- | ---
app | Path to the target Java EE application. This can be a path to a WAR file, an EAR file, an expanded WAR directory, or an expanded EAR directory. | Yes, if the `operations` attribute is set to any value other than `version`.
backup | Path to a directory that holds a backup of the original target Java EE application. This attribute defaults to the directory that contains the Java EE application. | No
descriptor | Path to the Coherence*Web XML descriptor. This attribute defaults to `coherence-web.xml` in the directory that contains the target Java EE application. | No
failonerror | Stop the Ant build if the Coherence*Web installer exits with a status other than 0. The default is `true`. | No
nowarn | Suppress warning messages. This attribute can be either `true` or `false`. The default is `false`. | No
operations | A comma- or space-separated list of operations to perform; each operation must be one of `inspect`, `install`, `uninstall`, or `version`. | Yes
server | The alias of the target Java EE application server. | No
touch | Touch JSPs and TLDs that are modified by the Coherence*Web installer. This attribute can be either `true`, `false`, or `M/d/y h:mm a`' The default is `false`. | No
verbose | Show verbose output. This attribute can be either `true` or `false`. The default is `false`. | No

#### 3.1.3.3 WebInstaller Ant Task Examples

- Inspect the `myWebApp.war` Web application and generate a Coherence*Web XML descriptor called `my-coherence-web.xml` in the current working directory:

      <cwi app="myWebApp.war" operations="inspect" descriptor="my-coherence-web.xml"/>

- Install Coherence*Web into the `myWebApp.war` Web application using the Coherence*Web XML descriptor called `my-coherence-web.xml` found in the current working directory:

      <cwi app="myWebApp.war" operations="install" descriptor="my-coherence-web.xml"/>

- Uninstall Coherence*Web from the `myWebApp.war` Web application:

      <cwi app="myWebApp.war" operations="uninstall">

- Install Coherence*Web into the `myWebApp.war` Web application located in the `/dev/myWebApp/build` directory using the Coherence*Web XML descriptor called `my-coherence-web.xml` found in the `/dev/myWebApp/src` directory, and place a backup of the original Web application in the `/dev/myWebApp/work` directory:

      <cwi app="/dev/myWebApp/build/myWebApp.war" operations="install" descriptor="/dev/myWebApp/src/my-coherence-web.xml" backup="/dev/myWebApp/work"/>

- Install Coherence*Web into the `myWebApp.war` Web application located in the `/dev/myWebApp/build` directory using the Coherence*Web XML descriptor called `coherence-web.xml` found in the `/dev/myWebApp/build` directory. If the Web application has not already been inspected (that is, `/dev/myWebApp/build/coherence-web.xml` does not exist), inspect the Web application before installing Coherence*Web:

      <cwi app="/dev/myWebApp/build/myWebApp.war" operations="inspect,install"/>

- Reinstall Coherence*Web into the `myWebApp.war` Web application located in the `/dev/myWebApp/build` directory, using the Coherence*Web XML descriptor called `my-coherence-web.xml` found in the `/dev/myWebApp/src` directory:

      <cwi app="/dev/myWebApp/build/myWebApp.war" operations="uninstall,install" descriptor="/dev/myWebApp/src/my-coherence-web.xml"/>

### 3.1.4 Testing HTTP Session Management

Coherence comes with a light-weight software load balancer; it is intended only for testing purposes. The load balancer is very easy to use and is very useful when testing functionality such as session management.

1. Start multiple application server processes on one or more server machines, each running your application on a unique IP address and port combination.

2. Open a command (or shell) window.

3. Change the current directory to the Coherence library directory (%COHERENCE_HOME%`\lib` on Windows and $COHERENCE_HOME`/lib` on UNIX).

4. Make sure that paths are configured so that Java commands will run.

5. Start the software load balancer with the following command lines (each of these command lines makes the application available on the default HTTP port `80`).

   For example, to test load-balancing locally on one machine with two application server instances on ports `7001` and `7002`:

       java -jar coherence-loadbalancer.jar localhost:80 localhost:7001 localhost:7002

   To run the load-balancer locally on a machine named `server1` that load balances to port `7001` on `server1`, `server2`, and `server3`:

       java -jar coherence-loadbalancer.jar server1:80 server1:7001 server2:7001 server3:7001

   Assuming the above command line, an application that previously was accessed with the URL `http://server1:7001/my.jsp` would now be accessed with the URL `http://server1:80/my.jsp` or just `http://server1/my.jsp`.

   Note:

   Make sure that your application uses only relative re-directs or the address of the load-balancer.

   Table 3-6 describes the command line options for the load balancer:

   Table 3-6 Load Balancer Command Line Options

   Option | Description
   --- | ---
   backlog | Sets the TCP/ IP accept backlog option to the specified value, for example: `-backlog=64`
   random | Specifies the use of a random load-balancing algorithm (default).
   roundrobin | Specifies the use of a round-robin load-balancing algorithm
   threads | Uses the specified number of request/ response thread pairs (so the total number of additional daemon threads will be two times the specified value), for example: `-threads=64`

### 3.1.5 How the Coherence*Web Installer Instruments a Java EE Application

During the inspect step, the Coherence*Web WebInstaller performs the following tasks:

1. Generates a template `coherence-web.xml` configuration file that contains basic information about the application and target Web container along with a set of default Coherence*Web configuration context parameters appropriate for the target Web container. See Appendix A, "Coherence*Web Context Parameters" for descriptions of all possible parameters.

   If an existing `coherence-web.xml` configuration file exists (for example, from a previous run of the Coherence*Web Installer), the context parameters in the existing file are merged with those in the generated template.

2. Enumerates the JSPs from each Web application in the target Java EE application and add information about each JSP to the `coherence-web.xml` configuration file.

3. Enumerates the TLDs from each Web application in the target Java EE application and adds information about each TLD to the `coherence-web.xml` configuration file.

During the install step, the Coherence*Web WebInstaller performs the following tasks:

1. Creates a backup of the original Java EE application so that it can be restored during the uninstall step.

2. Adds the Coherence*Web configuration context parameters generated in Step (1) of the inspect step to the `web.xml` descriptor of each Web application contained in the target Java EE application.

3. Unregisters any application-specific `ServletContextListener`, `ServletContextAttributeListener`, `ServletRequestListener`, `ServletRequestAttributeListener`, `HttpSessionListener`, and `HttpSessionAttributeListener` classes (including those registered by TLDs) from each Web application.

4. Registers a Coherence*Web `ServletContextListener` in each `web.xml` descriptor. At run time, the Coherence*Web `ServletContextListener` propagates each `ServletContextEvent` to each application-specific `ServletContextListener`.

5. Registers a Coherence*Web `ServletContextAttributeListener` in each `web.xml` descriptor. At run time, the Coherence*Web `ServletContextAttributeListener` propagates each `ServletContextAttributeEvent` to each application-specific `ServletContextAttributeListener`.

6. Wraps each application-specific `Servlet` declared in each `web.xml` descriptor with a Coherence*Web `SessionServlet`. At run time, each Coherence*Web `SessionServlet` delegates to the wrapped `Servlet`.

7. Adds the following directive to each JSP enumerated in Step (2) of the inspect step:

       <%@ page extends="com.tangosol.coherence.servlet.api22.JspServlet" %>

During the uninstall step, the Coherence*Web WebInstaller replaces the instrumented Java EE application with the backup of the original version created in Step (1) of the install process.

### 3.1.6 Installing Coherence*Web into Applications using Java EE Security

Note:

This section does not apply to the native WebLogic SPI implementation of Coherence*Web. It applies only if you are using the WebInstaller to install Coherence*Web into an application that uses Java EE security. For instructions on using the SPI implementation, see Chapter 2, "Using Coherence*Web with WebLogic Server."

If you want to install Coherence*Web into an application that uses Java EE security, follow these additional steps during installation:

1. Enable Coherence*Web session cookies.

   See the `coherence-session-cookies-enabled` configuration element in Table A-1 for additional details.

2. Change the Coherence*Web session cookie name to a name which is different from the one used by the target Web container.

   By default, most containers use `JSESSIONID` for the session cookie name, so a good choice for the Coherence*Web session cookie name is `CSESSIONID`. See the `coherence-session-cookie-name` configuration element in Table A-1 for additional details.

3. Enable session replication for the target Web container.

   If session replication is not enabled, or the container does not support a form of session replication, then you will be forced to re-authenticate to the Web application during failover. See your Web container's documentation for instructions on enabling session replication.

This configuration causes two sessions to be associated with a given authenticated user:

- A Coherence*Web session which contains all session data created by the Web application.

- A session created by the Web container during authentication which only stores information necessary to identify the user.

## 3.2 Enabling Coherence*Web for ColdFusion Applications

Note:

This section applies only to application servers that do not use the Coherence*Web SPI.

Oracle Coherence*Web can be employed as the session management module for ColdFusion applications. Follow these steps to enable Coherence*Web with for your application server.

1. In the ColdFusion installer, create a WAR version of ColdFusion.

2. Follow the provided instructions for configuring your J2EE container for ColdFusion.

   If you run Caucho Resin as your application server, run the Coherence WebInstaller on the container. See "Installing on Caucho Resin 3.1.x" for more information.

3. Instrument the generated `cfusion.war` using the Coherence WebInstaller.

   See "General Instructions for Installing Coherence*Web Session Management Module" for the additional steps to install Coherence*Web for a Java EE application.

4. Deploy `cfusion.war` to the Web container.

5. Configure ColdFusion MX to use J2EE session management.

   1. Access the ColdFusion administration page at the following URL:

          http://<host>:<port>/coldfusion-context-root/CFIDE/administrator

   2. Select Memory Variables under Server Sessions and enable the Use J2EE session variables check box.

6. Add your ColdFusion application.

   The application must have a `Application.cfm` file that specifies `sessionmanagement="Yes"`, but should not configure the session using ColdFusion configuration (otherwise, exceptions are thrown). The `Application.cfm` should contain the following line:

       <cfapplication sessionmanagement="Yes">