This chapter describes how to 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.
Before Proceeding:
Consult "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 these 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."
Use the SPI-based installation for GlassFish Server. See Chapter 3, "Using Coherence*Web with GlassFish Server".
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.
This chapter contains the following sections:
How the Coherence*Web WebInstaller Instruments a Java EE Application
Installing Coherence*Web into Applications Using Java EE Security
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 inspection step and an installation step. For more information about what the installer does during these steps, see "How the Coherence*Web WebInstaller 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".
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.n, require extra, container-specific steps that you must complete before starting the general installation procedure. The following sections describe application server-specific installation steps:
Complete the following steps to install the Coherence*Web Session Management Module into Oracle WebLogic Server release 10 to 10.2:
Obtain the coherence-web.jar
file from the coherence/lib
directory.
For each WebLogic Server 10.n 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
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.
Complete the following steps to install the Coherence*Web Session Management Module into a Caucho Resin 3.1.n server:
Obtain the coherence-web.jar
file from the coherence/lib
directory.
For each Caucho 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
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.
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.n Servers" for additional instructions.
To install 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 installer.
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. Appendix A, "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 4-1 describes some examples of different settings.
Table 4-1 Example Context Parameter Settings for Coherence*Web
Parameter | Name | Description |
---|---|---|
|
true |
Clusters all |
|
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. |
|
|
Enables you to increase the length of the |
|
true |
By default, the |
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 file to reside in the same directory as the application. The command creates a default-session-cache-config.xml
file in the WEB-INF\classes
directory of the application archive file. This file 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. For more information on the topologies themselves, see "Deployment Topologies".
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.
Start the application server in storage-enabled mode. Add the system property tangosol.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.
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" for more information on this 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.
Add the tangosol.coherence.cacheconfig
system property to the cache server startup script to locate the file configuration file. You must also include the system property tangosol.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 -Dtangosol.coherence.management.remote=true -Dtangosol.coherence.cacheconfig=default-session-cache-config.xml -Dtangosol.coherence.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 tangosol.coherence.session.localstorage=false
to the startup script).
Deploy the application to the server.
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".
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" for more information on this 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.
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 tangosol.coherence.session.proxy=false
and tangosol.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 more information and an example of a default-session-cache-config.xml
file with a <remote-addresses>
section.
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:
tangosol.coherence.session.localstorage=false
to disable local storage.
tangosol.coherence.session.proxy=true
to indicate that a proxy service is being used.
tangosol.coherence.session.proxy.localhost
to indicate the host name or IP address of the NIC to which the proxy will bind.
tangosol.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" for more information and an example of a default-session-cache-config.xml
file with these context parameters.
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
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.n 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.n application server type, will automatically set this parameter to false
unless you explicitly set it to true
.
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:
To use the Coherence*Web WebInstaller Ant task, add the task import statement illustrated in Example 4-1 to your Ant build file. In this example, ${
coherence.home
}
refers to the root directory of your Coherence installation.
Example 4-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:
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 installation 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").
Table 4-2 describes the attributes that can be used with the Coherence*Web WebInstaller Ant task.
Table 4-2 Coherence*Web WebInstaller Ant Task Attributes
Attribute | Description | Required? |
---|---|---|
|
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 |
|
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 |
|
Path to the Coherence*Web XML descriptor file. This attribute defaults to the |
No |
|
Stops the Ant build if the Coherence*Web installer exits with a status other than 0. The default is |
No |
|
Suppresses warning messages. This attribute can be either |
No |
|
A comma- or space-separated list of operations to perform; each operation must be one of |
Yes |
|
The alias of the target Java EE application server. |
No |
|
Touches JSPs and TLDs that are modified by the Coherence*Web installer. This attribute can be either |
No |
|
Displays verbose output. This attribute can be either |
No |
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"/>
Install 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"/>
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 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"/>
Install 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 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 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"/>
Coherence comes with a lightweight 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. 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 4-3 describes the command-line options for the load balancer:
Table 4-3 Load Balancer Command-Line Options
Option | Description |
---|---|
|
Sets the TCP/ IP accept backlog option to the specified value, for example: |
|
Specifies the use of a random load-balancing algorithm (default). |
|
Specifies the use of a round-robin load-balancing algorithm |
|
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: |
During the inspection step, the Coherence*Web WebInstaller performs the following 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 Appendix A, "Coherence*Web Context Parameters" for descriptions of all possible parameters.
The WebInstaller sets the servlet container to start in storage-disabled mode (that is, it sets tangosol.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 installation 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" %>
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 installation process.
Note:
This section does not apply to the native WebLogic Server 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."
To install Coherence*Web into an application that uses Java EE security, follow these additional steps during installation:
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
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.