This page provides a list of the different web containers on which Coherence*Web can be enabled. It also provides instuctions on how to install and test Coherence*Web for Java EE applications on each of the containers.

Before Proceeding... With the Coherence*Web installation make sure to consult the Coherence*Web Support Matrix to determine if there are any application server specific installation steps necessary. When deploying Coherence*Web on WebLogic Server you now have two options: Using the WebInstaller approach detailed on this page; Using the new SPI-based installation for WebLogic Server 10.3 or later.   When deploying Coherence*Web on WebLogic Portal 10.3 or later, the only option is the SPI-based approach. Please see the Coherence Web and WebLogic Server and Coherence Web and WebLogic Portal respectively for the SPI based installation instructions.

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 (recommended) through the automated Coherence*Web Installer prior to 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 WebInstaller 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 later in this page. For Ant task-based installation, see the Coherence*Web WebInstaller Ant Task page.

Coherence*Web Session Management Module: Supported Web Containers

The following table summarizes the web containers supported by the Coherence*Web Session Management Module. It also provides links to the information required to install the Coherence*Web Session Management Module on them. You will notice that all of the web containers share the same general installation instructions. A few, such as Oracle^® OC4J, Caucho^® , and WebLogic^TM , require extra, container-specific steps that you must complete before starting the general installation instructions.

Notes:
^* The server type alias passed to the Coherence*Web WebInstaller via the -server command line option.

Application Server-Specific Installation Instructions

A few of the web containers require additional, container-specific installation steps that you must complete before starting the general installation instructions.

• Oracle WebLogic 10.x
• Caucho Resin 3.1.x

Installing Coherence*Web Session Management Module on Oracle^® WebLogic^TM 10.x

The following are additional steps to take when installing the Coherence*Web Session Management Module into an Oracle WebLogic 10.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 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
   

2. For each WebLogic 10.x install 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 typed in 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
   

3. Follow the general installation steps for the Coherence*Web Session Management Module, specifying WebLogic/10.x for the server type.

Installing Coherence*Web Session Management Module on Caucho Resin^® 3.1.x

The following are additional steps to take when installing 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 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
   

2. For each Resin install 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 typed in 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
   

3. Follow the general installation steps for the Coherence*Web Session Management Module, specifying Resin/3.1.x for the server type.

General Instructions for Installing Coherence*Web Session Management Module

You must complete the following steps if you are installing Coherence*Web for a Java EE application on any of the web containers listed in the previous table.

A few of the web containers, such as Oracle^® OC4J, Caucho^® , and WebLogic^TM , require additional, container-specific installation steps that you must complete before starting the general installation instructions. These container-specific installation steps are described in earlier sections on this page.

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

• Make sure that the application directory, .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 the Java command will run.
• Complete the application inspection step by running the following command and specifying the full path to your application and the name of your server found in the chart above (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. Please see Configuring Coherence*Web for a complete listing of options in the coherence-web.xml configuration descriptor. You may proceed to the install step or review and modify the settings, based on your requirements, prior to running the install step. For example, you can enable certain features by setting the "context-param" options in the coherence-web.xml configuration descriptor:
  
  

  • This setting 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:

    param-name	coherence-servletcontext-clustered
    param-value	true

  • This setting 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:

    param-name	coherence-enable-sessioncontext
    param-value	true

  • This setting allows 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:

    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 following option to enable it:

    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.
    
    

• Go through the Coherence*Web application installation step by running the following command and specifying the full path to your application (replacing the <app-path> with it in the command line below):
  
  

            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. Please remember that the load balancer is intended only for testing and should not be used in a production environment.

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 useful when testing functionality such as Session Management and is very easy to use.

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 the paths are configured so that the Java command 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, which is port 80):
   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.
   The following command line options are supported:

   -backlog	Sets the TCP/ IP accept backlog option to the specified value, for example: -backlog=64
   -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
   -roundrobin	Specifies the use of a round-robin load-balancing algorithm
   -random	Specifies the use of a random load-balancing algorithm (default)

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

How the Coherence*Web WebInstaller 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 (for more information please reference the Configuring Coherence*Web page). 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.
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 add 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. Add 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 runtime, the Coherence*Web ServletContextListener will propagate each ServletContextEvent to each application-specific ServletContextListener.
5. Registers a Coherence*Web ServletContextAttributeListener in each web.xml descriptor. At runtime, the Coherence*Web ServletContextAttributeListener will propagate 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 runtime, each Coherence*Web SessionServlet will delegate 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.