Applies to Coherence 3.0 or later Please note that the following installation documentation applies to the Coherence*Web module in Coherence release 3.0 or later. This Session Management Module is very different and much more comprehensive than the module provided with Coherence releases prior to Release 2.3. Since we chose to not include the previous version's module jars and documentation in release 2.3 to avoid confusion, if you are looking for information on how to install pre-Release 2.3 module, please refer to the documentation and the User Guide included with the doc directory of the software distribution for the release level you are installing.

Coherence*Web Session Management Module: Supported Web Containers

The following table summarizes the web containers that are currently supported by the Coherence*Web Session Management Module and the installation information specific to each supported web container. For detailed installation instructions for a particular web container, click on its name.

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

General Instructions for Installing Coherence*Web Session Management Module

To enable Coherence*Web in your J2EE application, you need to run a ready to deploy application (recommended) through the automated installer prior to deploying it. The automated installer prepares the application for deployment.

To install Coherence*Web for the J2EE 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 Tangosol library directory (%TANGOSOL_HOME%\lib on Windows and $TANGOSOL_HOME/lib on Unix).
• Make sure that the paths are configured so that the Java command will run.
• Go through 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>
  

  A successful result of this step is the creation (or an update, if it already exists) of the coherence-web.xml configuration descriptor file for your J2EE application in the directory where the application is located. This configuration descriptor contains the default Coherence*Web settings for your application that the installer suggests be used in the following install step. You may at this point proceed to the install step, or review and modify the settings to fit them to your requirements prior to running the install step (which would make the install step use your modified settings). 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 Tangosol 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
  

  Please note that the installer expects to find the valid coherence-web.xml configuration descriptor for its use in the same directory 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 only intended for testing and should not be used in a production environment.

Installing Coherence*Web Session Management Module on BEA^TM WebLogic^TM 8.x

The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA WebLogic 8.x server:

• First, from within the Tangosol 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. On Windows, use the following commands to move the coherence-web.jar file up one level into the library directory:

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

  On Unix:

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

• Second, for each WebLogic 8.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 tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller <wls-home-path> -install
  

  For example, on Windows:

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

• Finally, follow the general installation steps for the Coherence*Web Session Management Module, specifying WebLogic/8.x for the server type.

Installing Coherence*Web Session Management Module on BEA^TM WebLogic^TM 9.x

The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA WebLogic 9.x server:

• First, from within the Tangosol 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. On Windows, use the following commands to move the coherence-web.jar file up one level into the library directory:

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

  On Unix:

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

• Second, for each WebLogic 9.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 tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller <wls-home-path> -install
  

  For example, on Windows:

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

• Finally, follow the general installation steps for the Coherence*Web Session Management Module, specifying WebLogic/9.x for the server type.

Installing Coherence*Web Session Management Module on BEA^TM WebLogic^TM Portal 8.1.6+

The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA WebLogic Portal 8.1.6+ server:

• First, from within the Tangosol 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. On Windows, use the following commands to move the coherence-web.jar file up one level into the library directory:

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

  On Unix:

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

• Second, for each WebLogic Portal 8.1.6+ install that will be running in the server cluster, update the WebLogic server 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 tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller <wls-home-path> -install
  

  For example, on Windows:

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

• Next, follow the general installation steps for the Coherence*Web Session Management Module on each Portal web application, specifying WebLogic/Portal/8.1.6+ for the server type.
• Finally, add the following line to the netuix-config.xml file found in the WEB-INF directory in each Portal web application that has Coherence*Web installed (immediately before the <pageflow> configuration element):

            <servlet-filters-for-skeleton-jsps enable="true"/>
  

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

The following are additional steps to take when installing the Coherence*Web Session Management Module into a Caucho Resin server:

• First, from within the Tangosol 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. On Windows, use the following commands to move the coherence-web.jar file up one level into the library directory:

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

  On Unix:

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

• Second, 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 tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller <resin-home-path> -install 
  

  For example, on Windows:

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

• Finally, follow the general installation steps for the Coherence*Web Session Management Module, specifying Resin/3.0.x for the server type.

Installing Coherence*Web Session Management Module on Oracle^® OC4J 10.1.x

The following are additional steps to take when installing the Coherence*Web Session Management Module into a Oracle OC4J server:

• First, from within the Tangosol 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. On Windows, use the following commands to move the coherence-web.jar file up one level into the library directory:

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

  On Unix:

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

• Second, for each OC4J 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 tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller <oc4j-home-path> -install 
  

  For example, on Windows:

            java -cp tangosol.jar;coherence.jar;coherence-web.jar
               com.tangosol.coherence.servlet.WebPluginInstaller
               C:\opt\oracle101\j2ee\home
  

• Finally, follow the general installation steps for the Coherence*Web Session Management Module, specifying Oracle/10.1.x for the server type.

How the Coherence*Web Installer instruments a J2EE application

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

1. Generate 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. 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. Enumerate the JSPs from each web application in the target J2EE application and add information about each JSP to the coherence-web.xml configuration file.
3. Enumerate the TLDs from each web application in the target J2EE application and add information about each TLD to the coherence-web.xml configuration file.

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

1. Create a backup of the original J2EE 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 J2EE application.
3. Unregister any application-specific ServletContextListener, ServletContextAttributeListener, ServletRequestListener, ServletRequestAttributeListener, HttpSessionListener, and HttpSessionAttributeListener classes (including those registered by TLDs) from each web application.
4. Register 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. Register 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. Wrap 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. Add 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 Installer replaces the instrumented J2EE application with the backup of the original version created in step (1) of the install process.

Testing HTTP session management (without a dedicated loadbalancer)

Coherence comes with a light-weight software load balancer; it is only intended 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 Tangosol library directory (%TANGOSOL_HOME%\lib on Windows and $TANGOSOL_HOME/lib on Unix).
• Make sure that the paths are configured so that the Java command 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):
  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.