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 need to 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 10.3 or later. This is described in Chapter 2, "Installing Coherence*Web on the WebLogic Server 10.3."
Coherence*Web can be enabled for Java EE applications on a number of different Web containers. To enable Coherence*Web, 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 Java command line method is described in the following sections. For Ant task-based installation, see "Coherence*Web WebInstaller Ant Task".
All of the Web containers listed in "Supported Web Containers" (with the exception of Oracle WebLogic Server 10.3) 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 Oracle OC4J, Caucho, and WebLogic 10.x, require extra, container-specific steps that you must complete before starting the general installation instructions. The following sections describe application server-specific installation steps.
Complete the following steps to install the Coherence*Web Session Management Module into an Oracle WebLogic 10.x server:
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 will extract the coherence-web.jar file into a sub-directory 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
For each WebLogic 10.x installation that will be running in the server cluster, update the libraries using the following command (note that it is broken up into multiple lines here only for formatting purposes; this is a single command entered on one line):
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
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.0.x server:
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 will extract 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
For each Resin installation that will be running in the server cluster, update the libraries using the following command (note that it is broken up into multiple lines only for formatting purposes; this is a single command entered on one line):
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\resin30 -install
Follow the instructions described in "General Instructions for Installing Coherence*Web Session Management Module" to complete the installation. Use the value Resin/3.0.x for the server type.
Complete the following steps to install the Coherence*Web Session Management Module into a Caucho Resin 3.1.x server:
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 will extract 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
For each Resin installation that will be running in the server cluster, update the libraries using the following command (note that it is broken up into multiple lines only for formatting purposes; this is a single command entered on one line):
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
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 the Coherence*Web Session Management Module into an Oracle OC4J 10.1.2.x server:
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 will extract 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
For each OC4J installation that will be running in the server cluster, update the libraries using the following command (note that it is broken up into multiple lines only for formatting purposes; this is a single command entered on one line):
java -cp coherence.jar;coherence-web.jar com.tangosol.coherence.servlet.WebPluginInstaller <oc4j-home-path> -install
For example, on Windows:
java -cp coherence.jar;coherence-web.jar com.tangosol.coherence.servlet.WebPluginInstaller C:\opt\oracle1012\j2ee\home
Follow the instructions described in "General Instructions for Installing Coherence*Web Session Management Module" to complete the installation. Use the value Oracle/10.1.2.x for the server type.
You must 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 Session Management Module on an Oracle OC4J, Caucho, or WebLogic container, then you must complete certain container-specific installation steps before you start the general installation instructions. These container-specific installation steps are described in "Application Server-Specific Installation Instructions".
To install Coherence*Web for the Java EE application you are deploying:
Make sure 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).
Make sure 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 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.
You may proceed to the install step (Step 6) or review and modify the Coherence*Web settings based on your requirements, before running the install step.
You modify the Coherence*Web settings by editing the coherence-web.xml descriptor. Appendix A, "Coherence*Web Configuration 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.
For example:
The setting inTable 3-1 will cluster all ServletContext ("global") attributes so that servers in a cluster will share the same values for those attributes, and will also receive the events specified by the Servlet Specification when those attributes change:
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:
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:
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 |
After double-checking that these changes have been made, save the file and exit the editor. Remember to return back to the Coherence library directory if you are working from a shell or command line.
Perform 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 for its use in the same directory in which the application is located.
Deploy the updated application and verify that everything functions as expected, using the load balancer if necessary. Remember that the load balancer is intended only for testing and should not be used in a production environment.
Coherence comes with a light-weight software load balancer; it is intended only for testing purposes. The load balancer is very useful when testing functionality such as session management and is very easy to use.
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).
Make sure 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, which is 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-5 describes the command line options for the load balancer:
Table 3-5 Load Balancer Command Line Options
| Option | Description |
|---|---|
|
backlog |
Sets the TCP/ IP accept backlog option to the specified value, for example: |
|
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: |
During the inspect 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 Configuration 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.
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.
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:
Creates a backup of the original Java EE application so that it can be restored during the uninstall step.
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.
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 in each web.xml descriptor. At run time, the Coherence*Web ServletContextListener will propagate each ServletContextEvent to each application-specific ServletContextListener.
Registers a Coherence*Web ServletContextAttributeListener in each web.xml descriptor. At run time, the Coherence*Web ServletContextAttributeListener will propagate each ServletContextAttributeEvent to each application-specific ServletContextAttributeListener.
Wraps each application-specific Servlet declared in each web.xml descriptor with a Coherence*Web SessionServlet. At run time, each Coherence*Web SessionServlet will delegate to the wrapped Servlet.
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.
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.If you want to install Coherence*Web into an application that uses Java EE security, you must 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 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.
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 will cause two sessions to be associated with a given authenticated user:
A Coherence*Web session which will contain all session data created by the Web application.
A session created by the Web container during authentication which will only store information necessary to identify the user.
The Coherence*Web WebInstaller Ant task allows 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 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.
Build your Java EE application as you normally 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.
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:
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).
Build your Java EE application as you normally would.
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 already has Coherence*Web installed, use this procedure:
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.
Change the necessary configuration parameters in the Coherence*Web XML descriptor.
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).
Table 3-6 describes the attributes that can be used with the Coherence*Web WebInstaller Ant Task.
Table 3-6 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 |
|
backup |
Path to a directory that will hold 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 |
No |
|
failonerror |
Stop the Ant build if the Coherence*Web installer exits with a status other than 0. The default is |
No |
|
nowarn |
Suppress warning messages. This attribute can be either |
No |
|
operations |
A comma- or space-separated list of operations to perform; each operation must be one of |
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 |
No |
|
verbose |
Show verbose output. This attribute can be either |
No |
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 exists), inspect the Web application prior to 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"/>