Skip Headers
Oracle® Coherence User's Guide for Oracle Coherence*Web
Release 3.6.1

Part Number E15829-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Installing Coherence*Web on Other Application Servers

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 must perform any application server-specific installation steps.

When deploying Coherence*Web on WebLogic Server you now have two options:

3.1 Installing Coherence*Web Using the WebInstaller

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 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 following sections describe the Java command line method. For Ant task-based installation, see "Coherence*Web WebInstaller Ant Task".

3.1.1 Application Server-Specific Installation Instructions

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.x, require extra, container-specific steps that you must complete before starting the general installation procedure. The following sections describe application server-specific installation steps.

3.1.1.1 Installing on Oracle WebLogic 10.x

Complete the following steps to install the Coherence*Web Session Management Module into an Oracle WebLogic 10-10.2 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 command extracts 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
    
  2. For each WebLogic 10.x 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
    

    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 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.

3.1.1.2 Installing on Caucho Resin 3.1.x

Complete the following steps to install 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 command extracts 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
    
  2. For each 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 
    

    For example, on Windows:

    java -cp coherence.jar;coherence-web.jar 
    com.tangosol.coherence.servlet.WebPluginInstaller C:\opt\resin31 -install
    
  3. 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.

3.1.2 General Instructions for Installing Coherence*Web Session Management Module

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.x Servers" for additional instructions.

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

  1. Make sure that the application directory and the .ear file or .war file are not being used or accessed by another process.

  2. Change the current directory to the Coherence library directory (%COHERENCE_HOME%\lib on Windows and $COHERENCE_HOME/lib on UNIX).

  3. Make sure that the paths are configured so that Java commands will run.

  4. 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.

  5. 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. Appendix A, "Coherence*Web Context 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. The following list provides some examples of different settings:

    • The setting inTable 3-1 will cluster 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:

      Table 3-1 Settings to Cluster ServletContext Attributes

      Parameter Value

      param-name

      coherence-servletcontext-clustered

      param-value

      true


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

      Table 3-2 Settings to Enumerate All Sessions in the Application

      Parameter Value

      param-name

      coherence-enable-sessioncontext

      param-value

      true


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

      Table 3-3 Settings to Increase Length of HTTPSession ID

      Parameter Value

      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 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


  6. 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 to reside in the same directory as the application.

  7. 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.

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

Decoding URL Session IDs for IBM WebSphere 7.x Servers

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.x 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.x application server type, will automatically set this parameter to false unless you explicitly set it to true.

3.1.3 Coherence*Web WebInstaller Ant Task

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:

3.1.3.1 Using the WebInstaller Ant task

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.

  1. Build your Java EE application as you normally would.

  2. Run the Coherence*Web Ant task with the operations attribute set to inspect.

  3. Make any necessary changes to the generated Coherence*Web XML descriptor.

  4. 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:

  1. 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).

  2. Build your Java EE application as you normally would.

  3. 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 has Coherence*Web installed, use this procedure:

  1. 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.

  2. Change the necessary configuration parameters in the Coherence*Web XML descriptor.

  3. 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).

3.1.3.2 Configuring the WebInstaller Ant Task

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

Table 3-5 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. This attribute defaults to coherence-web.xml in the directory that contains the target Java EE application.

No

failonerror

Stop the Ant build if the Coherence*Web installer exits with a status other than 0. The default is true.

No

nowarn

Suppress 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

Touch JSPs and TLDs that are modified by the Coherence*Web installer. This attribute can be either true, false, or M/d/y h:mm a' The default is false.

No

verbose

Show verbose output. This attribute can be either true or false. The default is false.

No


3.1.3.3 WebInstaller Ant Task Examples

  • 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 exist), 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 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"/>
    

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

  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 paths are configured so that Java commands 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 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-6 describes the command line options for the load balancer:

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


3.1.5 How the Coherence*Web Installer 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. See Appendix A, "Coherence*Web Context 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.

  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 adds 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. 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.

  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 run time, the Coherence*Web ServletContextListener propagates each ServletContextEvent to each application-specific ServletContextListener.

  5. Registers a Coherence*Web ServletContextAttributeListener in each web.xml descriptor. At run time, the Coherence*Web ServletContextAttributeListener propagates 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 run time, each Coherence*Web SessionServlet delegates 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.

3.1.6 Installing Coherence*Web into Applications using Java EE Security

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. For instructions on using the SPI implementation, see Chapter 2, "Using Coherence*Web with WebLogic Server."

If you want to install Coherence*Web into an application that uses Java EE security, follow these additional steps during installation:

  1. Enable Coherence*Web session cookies.

    See the coherence-session-cookies-enabled configuration element in Table A-1 for additional details.

  2. 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.

  3. 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 which contains all session data created by the Web application.

  • A session created by the Web container during authentication which only stores information necessary to identify the user.

3.2 Enabling Coherence*Web for ColdFusion Applications

Note:

This section applies only to application servers that do not use the Coherence*Web SPI.

Oracle Coherence*Web can be employed as the session management module for ColdFusion applications. Follow these steps to enable Coherence*Web with for your application server.

  1. In the ColdFusion installer, create a WAR version of ColdFusion.

  2. Follow the provided instructions for configuring your J2EE container for ColdFusion.

    If you run Caucho Resin as your application server, run the Coherence WebInstaller on the container. See "Installing on Caucho Resin 3.1.x" for more information.

  3. Instrument the generated cfusion.war using the Coherence WebInstaller.

    See "General Instructions for Installing Coherence*Web Session Management Module" for the additional steps to install Coherence*Web for a Java EE application.

  4. Deploy cfusion.war to the Web container.

  5. Configure ColdFusion MX to use J2EE session management.

    1. Access the ColdFusion administration page at the following URL:

      http://<host>:<port>/coldfusion-context-root/CFIDE/administrator
      
    2. Select Memory Variables under Server Sessions and enable the Use J2EE session variables check box.

  6. Add your ColdFusion application.

    The application must have a Application.cfm file that specifies sessionmanagement="Yes", but should not configure the session using ColdFusion configuration (otherwise, exceptions are thrown). The Application.cfm should contain the following line:

    <cfapplication sessionmanagement="Yes">