This chapter applies to the Coherence*Web Session Management 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 before 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.
Table 24-1 summarizes the Web containers supported by the Coherence*Web Session Management Module and the installation information specific to each supported Web container. The table also describes where you can find detailed installation instructions.
Table 24-1 Web Containers Supported by Coherence*Web
* The server type alias passed to the Coherence*Web installer by using the -server command line option.
To enable Coherence*Web in your Java EE application, you need to run a ready to deploy application (recommended) through the automated installer before deploying it. The automated installer prepares the application for deployment.
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 Table 24-1 (replacing the <app-path> and <server-type> with them in the 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 contains the default Coherence*Web settings for your application recommended by the installer. You may proceed to the install step or review and modify the settings, based on your requirements, before 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:
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:
This setting 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 following option to enable it:
Table 24-5 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.
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):
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 only intended for testing and should not be used in a production environment.
The following additional steps are required when installing the Coherence*Web Session Management Module into a BEA WebLogic 8.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 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 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\weblogic8\server -install
Follow the steps in "General Instructions for Installing the Session Management Module" and specify WebLogic/8.x for the server type.
The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA WebLogic 9.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 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 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\weblogic9\server -install
Follow the steps in "General Instructions for Installing the Session Management Module" and specify WebLogic/9.x for the server type.
The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA 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 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 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\weblogic10\server -install
Follow the steps in "General Instructions for Installing the Session Management Module" and specify WebLogic/10.x for the server type.
The following are additional steps to take when installing the Coherence*Web Session Management Module into a BEA WebLogic Portal 8.1.6+ 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 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 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\weblogic81\server -install
Follow the steps in "General Instructions for Installing the Session Management Module" on each Portal web application, and specify WebLogic/Portal/8.1.6+ for the server type.
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"/>
The following are additional steps to take when installing the Coherence*Web Session Management Module into a Caucho Resin 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 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\resin30 -install
Follow the steps in "General Instructions for Installing the Session Management Module" and specify Resin/3.0.x for the server type.
The following are additional steps to take when installing the Coherence*Web Session Management Module into a 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 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 <oc4j-home-path> -install
For example, on Windows:
java -cp coherence.jar;coherence-web.jar
com.tangosol.coherence.servlet.WebPluginInstaller
C:\opt\oracle101\j2ee\home
Follow the steps in "General Instructions for Installing the Session Management Module" and specify Oracle/10.1.2.x for the server type.
During the inspect step, the Coherence*Web Installer 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. 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 add information about each TLD to the coherence-web.xml configuration file.
During the install step, the Coherence*Web Installer performs the following tasks:
Creates a backup of the original Java EE application so that it can be restored during the uninstall step.
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.
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 runtime, the Coherence*Web ServletContextListener will propagate each ServletContextEvent to each application-specific ServletContextListener.
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.
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.
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 Installer replaces the instrumented Java EE application with the backup of the original version created in step (1) of the install process.
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 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.
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:
Table 24-6 Command Line Options to Test HTTP Session Management
| 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 |
Make sure that your application uses only relative re-directs or the address or the load-balancer.