Using Coherence*Web on Other Application Servers

3 Using Coherence*Web on Other Application Servers

You can configure and deploy Coherence*Web, the session state persistence and management module, for use with a variety of application servers. The functionality that allows Coherence*Web to be used with these application servers is provided by running the automated Coherence*Web WebInstaller.

Note:

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

This chapter includes the following sections:

Integrating Coherence*Web Using the WebInstaller
Coherence*Web can be enabled for Java EE applications on several different Web containers.
Coherence*Web WebInstaller Ant Task
The Coherence*Web WebInstaller Ant task enables you to run the utility from within your existing Ant build files.
Testing HTTP Session Management
Coherence comes with a lightweight software load balancer intended only for testing purposes.
How the Coherence*Web WebInstaller Instruments a Java EE Application
Coherence*Web WebInstaller performs many tasks as a part of the inspection step.
Integrating Coherence*Web with Applications Using Java EE Security
Coherence*Web can be integrated with applications that uses Java EE security.
Preventing Cross-Site Scripting Attacks
Use the coherence-session-cookie-httponly context parameter to append the HttpOnly attribute to the session cookie.

Integrating Coherence*Web Using the WebInstaller

Coherence*Web can be enabled for Java EE applications on several different Web containers.

To enable the Coherence*Web, you must run the ready-to-deploy application through the automated Coherence*Web WebInstaller before deploying it. This utility prepares the application for deployment. It performs the integration process in two discrete steps: an inspection step and an integration step. See How the Coherence*Web WebInstaller Instruments a Java EE Application.

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

This section includes the following topics:

Parent topic: Using Coherence*Web on Other Application Servers

General Instructions for Integrating Coherence*Web Session Management Module

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

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

If you are integrating Coherence*Web with a Java EE application on an IBM WebSphere Server, see also Integrating with IBM WebSphere Liberty for additional instructions.

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

Ensure that the application directory and the EAR file or WAR file are not being used or accessed by another process.
Change the current directory to the Coherence library directory (%COHERENCE_HOME%\lib on Windows and $COHERENCE_HOME/lib on UNIX).
Ensure that the paths are configured so that Java commands will run.
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 following command line):
```
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 file contains the default Coherence*Web settings for your application as recommended by the utility.

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 file. Coherence*Web Context Parameters, describes the Coherence*Web settings that can be modified. Use the param-name and param-value subelements of the context-param parameter to enable the features you want. Table 3-1 describes some examples of different settings.

Table 3-1 Example Context Parameter Settings for Coherence*Web

Parameter	Name	Description
`coherence-servletcontext-clustered`	true	Clusters 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. Note: This property is not applicable for IBM WebSphere Liberty.
`coherence-enable-sessioncontext`	true	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.
`coherence-session-id-length`	`32`	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 purposely hijacked.
`coherence-session-urlencode-enabled`	true	By default, the `HttpSession` ID is managed in a cookie. If the application supports URL encoding, this option enables it.

Complete the Coherence*Web application integration step by running the following command, replacing <app-path> with the full path to your application:
```
java -jar webInstaller.jar <app-path> -install
```
The coherence-web-12.2.1.4.jar file that gets added, includes the default-session-cache-config.xml file that contains the session and cache configuration information.
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.

The application can be deployed and run in any of the deployment topologies supported by Coherence: in-process, out-of-process, or out-of-process with Coherence*Extend. See the following sections for information on deploying and running your applications under these topologies. See Deployment Topologies.

Parent topic: Integrating Coherence*Web Using the WebInstaller

Deploying and Running Applications In Process

Coherence*Web can be run in-process with the application server. This is where session data is stored with the application server. See In-Process Topology for more information on this topology.

For the application server:

Start the application server in storage-enabled mode. Add the system property coherence.session.localstorage=true to the Java options of your application server startup script.
Deploy the coherence.jar and coherence-web.jar files as shared libraries.
Deploy and run your application.

Parent topic: Integrating Coherence*Web Using the WebInstaller

Deploying and Running Applications Out-of-Process

In the out-of-process deployment topology, a stand-alone cache server stores the session data and the application server is configured as a cache client. See Out-of-Process Topology.

The cache server and the application server must use the same cache and session configuration. This configuration is generated in the default-session-cache-config.xml file by the Coherence*Web WebInstaller. The WebInstaller generates the file in the WEB-INF\classes directory of the instrumented application.

For the cache server:

Add the coherence.cacheconfig system property to the cache server startup script to locate the file configuration file. You must also include the system property coherence.session.localstorage=true to enable storage for the cache server.

Add the coherence.jar and coherence-web.jar files to the classpath in the cache server startup script.

Following is a sample startup script:

java -server -Xms512m -Xmx512m 
-cp <Coherence installation dir>/lib/coherence.jar:<Coherence installation dir>/lib/coherence-web.jar -Dcoherence.management.remote=true -Dcoherence.cacheconfig=default-session-cache-config.xml 
-Dcoherence.session.localstorage=true com.tangosol.net.DefaultCacheServer

For the application server (cache client):

Deploy the coherence.jar and coherence-web.jar files as shared libraries.
The default-session-cache-config.xml file should already be present in the WEB-INF\classes directory of the instrumented application.

By default, the file should specify that local storage is disabled (if you are not sure, you can either inspect the file to confirm that the local-storage element is set to false or add the system property coherence.session.localstorage=false to the startup script).
Deploy the application to the server.

Parent topic: Integrating Coherence*Web Using the WebInstaller

Migrating to Out-of-Process Topology

If you have been running and testing your application with Coherence*Web in-process, you can easily migrate to the out-of-process topology. Simply set up your cache server and application server as described in Deploying and Running Applications Out-of-Process.

Parent topic: Integrating Coherence*Web Using the WebInstaller

Deploying and Running Applications Out-of-Process with Coherence*Extend

The out-of-process with Coherence*Extend topology is similar to the out-of-process topology except that the communication between the application server tier and the cache server tier is over Coherence*Extend (TCP/IP). Coherence*Extend consists of two components: an extend client (or proxy) running outside the cluster and an extend proxy service running in the cluster hosted by one or more cache servers. See Out-of-Process with Coherence*Extend Topology.

In these deployments, there are three types of participants:

Cache servers (storage servers), which are used to store the actual session data in memory.
Web (application) servers, which are the Extend clients in this topology. They are not members of the cluster; instead, they connect to a proxy node in the cluster that will issue requests to the cluster on their behalf.
Proxy servers, which are storage-disabled members (nodes) of the cluster that accept and manage TCP/IP connections from Extend clients. Requests that arrive from clients will be sent into the cluster, and responses will be sent back through the TCP/IP connections.

For the cache server:

Follow the instructions for configuring the cache server in Deploying and Running Applications Out-of-Process. Also, edit the cache server's copy of the default-session-cache-config.xml file to add the system properties coherence.session.proxy=false and coherence.session.localstorage=true.

See Configure the Cache for Proxy and Storage JVMs for more information and an example of a default-session-cache-config.xml file with these context parameters.

For the Web tier (application) server:

Follow the instructions for configuring the application server in Deploying and Running Applications Out-of-Process. Also, complete these steps:

Ensure that Coherence*Web is configured to use the Optimistic Locking mode. Optimistic locking is the default locking mechanism for Coherence*Web (see Optimistic Locking).
Edit the application server's copy of the default-session-cache-config.xml file to add the proxy JVM host names, IP addresses and ports. To do this, add a <remote-addresses> section to the file. In most cases, you should include the host name and IP address, and port of all proxy JVMs for load balancing and failover.

See Configure the Cache for Web Tier JVMs.

For the proxy server:

With a few changes, the proxy server can use the same cache and session configuration as the application server and the cache server. Edit the default-session-cache-config.xml file to add these system properties:

coherence.session.localstorage=false to disable local storage.
coherence.session.proxy=true to indicate that a proxy service is being used.
coherence.session.proxy.localhost to indicate the host name or IP address of the NIC to which the proxy will bind.
coherence.session.proxy.localport to indicate a unique port number to which the proxy will bind.

See Configure the Cache for Proxy and Storage JVMs.

Parent topic: Integrating Coherence*Web Using the WebInstaller

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

Parent topic: Integrating Coherence*Web Using the WebInstaller

Integrating with IBM WebSphere Liberty

HTTP session affinity may need to be explicitly configured when integrating with WebSphere Liberty. Coherence*Web needs to be passed the Clone ID of the Liberty server as well as the affinity separator. If the Clone ID is defined by the user, as explained in the liberty documentation at https://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/twlp_admin_session_persistence.html, and if the affinity separator is the colon character (:) character, then no additional configuration is required. If that is not the case, then the following system properties can be used during server startup:

coherence.web.liberty.suffix.separator – The affinity suffix separator. The default value is :.
coherence.web.liberty.suffix – The clone id of the server. The default value is the value configured for the cloneId system property in the bootstrap.properties file as explained in the WebSphere Liberty documentation cited above.

Parent topic: Integrating Coherence*Web Using the WebInstaller

Coherence*Web WebInstaller Ant Task

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

This section includes the following topics:

Parent topic: Using Coherence*Web on Other Application Servers

Using the Coherence*Web WebInstaller Ant Task

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

<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 integrating Coherence*Web with a Java EE application from an Ant build:

Build your Java EE application as you ordinarily would.
Run the Coherence*Web Ant task with the operations attribute set to inspect.
Make any necessary changes to the generated Coherence*Web XML descriptor file.
Run the Coherence*Web Ant task with the operations attribute set to install.

Performing Iterative Development

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

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 file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).
Build your Java EE application as you ordinarily would.
Run the Coherence*Web Ant task with the operations attribute set to inspect, and the install and descriptor attributes set to the location of the previously generated Coherence*Web XML descriptor file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).

Changing the Coherence*Web Configuration Settings of a Java EE Application

If you must change the Coherence*Web configuration settings of a Java EE application that is using Coherence*Web, follow these steps:

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 file for the Java EE application.
Change the necessary configuration parameters in the Coherence*Web XML descriptor file.
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 file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).

Parent topic: Coherence*Web WebInstaller Ant Task

Configuring the WebInstaller Ant Task

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

Table 3-2 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 file. This attribute defaults to the `coherence-web.xml` file in the directory that contains the target Java EE application.	No
`failonerror`	Stops the Ant build if the Coherence*Web WebInstaller exits with a status other than 0. The default is `true`.	No
`nowarn`	Suppresses 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`	Touches JSPs and TLDs that are modified by the Coherence*Web WebInstaller. This attribute can be either `true`, `false`, or `M/d/y h:mm a`' The default is `false`.	No
`verbose`	Displays verbose output. This attribute can be either `true` or `false`. The default is `false`.	No

Parent topic: Coherence*Web WebInstaller Ant Task

WebInstaller Ant Task Examples

The following list provides sample commands for the WebInstaller Ant task.

Inspect the myWebApp.war Web application and generate a Coherence*Web XML descriptor file called my-coherence-web.xml in the current working directory:
```
<cwi app="myWebApp.war" operations="inspect" descriptor="my-coherence-web.xml"/>
```
Integrate Coherence*Web into the myWebApp.war Web application using the Coherence*Web XML descriptor file called my-coherence-web.xml found in the current working directory:
```
<cwi app="myWebApp.war" operations="install" descriptor="my-coherence-web.xml"/>
```
Remove Coherence*Web from the myWebApp.war Web application:
```
<cwi app="myWebApp.war" operations="uninstall">
```
Integrate Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory using the Coherence*Web XML descriptor file 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"/>
```
Integrate Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory using the Coherence*Web XML descriptor file 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 exists); inspect the Web application before integrating Coherence*Web:
```
<cwi app="/dev/myWebApp/build/myWebApp.war" operations="inspect,install"/>
```
Reintegrate Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory, using the Coherence*Web XML descriptor file 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"/>
```

Parent topic: Coherence*Web WebInstaller Ant Task

Testing HTTP Session Management

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

Follow these steps to test HTTP session management with the lightweight load balancer:

Start multiple application server processes on one or more server machines, each running your application on a unique IP address and port combination.
Open a command (or shell) window.
Change the current directory to the Coherence library directory (%COHERENCE_HOME%\lib on Windows and $COHERENCE_HOME/lib on UNIX).
Ensure that paths are configured so that Java commands will run.

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 that you use the preceding 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:

Ensure that your application uses only relative redirections or the address of the load balancer.

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

Table 3-3 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 or response thread pairs (so the total number of additional daemon threads will be two times the specified value), for example: `-threads=64`.

Parent topic: Using Coherence*Web on Other Application Servers

How the Coherence*Web WebInstaller Instruments a Java EE Application

Coherence*Web WebInstaller performs many tasks as a part of the inspection step.

The following are the tasks:

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 Coherence*Web Context Parameters.

The WebInstaller sets the servlet container to start in storage-disabled mode (that is, it sets coherence.session.localstorage to false).

If an existing coherence-web.xml configuration file exists (for example, from a previous run of the Coherence*Web WebInstaller), the context parameters in the existing file are merged with those in the generated template.
Enumerates the JSP from each Web application in the target Java EE application and adds information about each JSP to the coherence-web.xml configuration file.
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 integration step, the Coherence*Web WebInstaller performs the following tasks:

Creates a backup of the original Java EE application so that it can be restored during the uninstallation step.
Adds the Coherence*Web configuration context parameters generated in Step 1 of the inspection step to the web.xml descriptor file of each Web application contained in the target Java EE application.
Unregisters any application-specific ServletContextListener, ServletContextAttributeListener, ServletRequestListener, ServletRequestAttributeListener, HttpSessionListener, and HttpSessionAttributeListener classes (including those registered by TLDs) from each Web application.
Registers a Coherence*Web ServletContextListener class in each web.xml descriptor file. At run time, the Coherence*Web ServletContextListener class propagates each ServletContextEvent event to each application-specific ServletContextListener listener.
Registers a Coherence*Web ServletContextAttributeListener listener in each web.xml descriptor file. At run time, the Coherence*Web ServletContextAttributeListener propagates each ServletContextAttributeEvent event to each application-specific ServletContextAttributeListener listener.
Wraps each application-specific Servlet declared in each web.xml descriptor file with a Coherence*Web SessionServlet. At run time, each Coherence*Web SessionServlet delegates to the wrapped Servlet.
Adds the following directive to each JSP enumerated in Step 2 of the inspection step:
```
<%@ page extends="com.tangosol.coherence.servlet.api22.JspServlet" %>
```

Note:

The presence of duplicate page extends in JSP may cause errors after Coherence*Web is integrated with the Java EE application. Therefore, remove the replicated page extends. You do not need to add page extends explicitly because the Coherence*Web WebInstaller utility adds page extends for the Coherence servlet context by default.

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

Parent topic: Using Coherence*Web on Other Application Servers

Integrating Coherence*Web with Applications Using Java EE Security

Coherence*Web can be integrated with applications that uses Java EE security.

To integrate Coherence*Web with an application that uses Java EE security, follow these additional steps:

Enable Coherence*Web session cookies.

See the coherence-session-cookies-enabled configuration element in Table A-1 for additional details.
Change the Coherence*Web session cookie name to a name that 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.
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 that contains all session data created by the Web application
A session created by the Web container during authentication that stores only information necessary to identify the user

Parent topic: Using Coherence*Web on Other Application Servers

Preventing Cross-Site Scripting Attacks

Use the coherence-session-cookie-httponly context parameter to append the HttpOnly attribute to the session cookie.The HttpOnly attribute is used to help prevent attacks such as cross-site scripting, since it does not allow the cookie to be accessed by a client-side script such as JavaScript.

Note that not all browsers support this functionality. This context parameter is available for instrumented applications only.

Parent topic: Using Coherence*Web on Other Application Servers