Note:
Consult Supported Web Containers to see if you must perform any application server-specific integration steps.
This chapter includes the following sections:
coherence-session-cookie-httponly
context parameter to append the HttpOnly
attribute to the session cookie.To enable the Coherence*Web, you must run the ready-to-deploy application through the automated Coherence*Web WebInstaller before deploying it. This utility prepares the application for deployment. It performs the integration process in two discrete steps: an inspection step and an integration step. See How the Coherence*Web WebInstaller Instruments a Java EE Application.
WebInstaller can be run either from the Java command line or from Ant tasks. The following sections describe the Java command-line method. For an Ant task-based environment, see Coherence*Web WebInstaller Ant Task.
This section includes the following topics:
Complete the following steps to integrate Coherence*Web with a Java EE application on any of the Web containers listed under Supported Web Containers.
If you are integrating Coherence*Web with a Java EE application on an Apache Tomcat Server, see also Enabling Sticky Sessions for Apache Tomcat Servers for additional instructions.
If you are integrating Coherence*Web with a Java EE application on an IBM WebSphere Server, see also Integrating with IBM WebSphere Liberty for additional instructions.
To integrate Coherence*Web for the Java EE application you are deploying:
Coherence*Web can be run in-process with the application server. This is where session data is stored with the application server. See In-Process Topology for more information on this topology.
For the application server:
coherence.session.localstorage=true
to the Java options of your application server startup script.coherence.jar
and coherence-web.jar
files as shared libraries.In the out-of-process deployment topology, a stand-alone cache server stores the session data and the application server is configured as a cache client. See Out-of-Process Topology.
The cache server and the application server must use the same cache and session configuration. This configuration is generated in the default-session-cache-config.xml
file by the Coherence*Web WebInstaller. The WebInstaller generates the file in the WEB-INF\classes
directory of the instrumented application.
For the cache server:
Add the coherence.cacheconfig
system property to the cache server startup script to locate the file configuration file. You must also include the system property coherence.session.localstorage=true
to enable storage for the cache server.
Add the coherence.jar
and coherence-web.jar
files to the classpath in the cache server startup script.
Following is a sample startup script:
java -server -Xms512m -Xmx512m -cp <Coherence installation dir>/lib/coherence.jar:<Coherence installation dir>/lib/coherence-web.jar -Dcoherence.management.remote=true -Dcoherence.cacheconfig=default-session-cache-config.xml -Dcoherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
For the application server (cache client):
If you have been running and testing your application with Coherence*Web in-process, you can easily migrate to the out-of-process topology. Simply set up your cache server and application server as described in Deploying and Running Applications Out-of-Process.
The out-of-process with Coherence*Extend topology is similar to the out-of-process topology except that the communication between the application server tier and the cache server tier is over Coherence*Extend (TCP/IP). Coherence*Extend consists of two components: an extend client (or proxy) running outside the cluster and an extend proxy service running in the cluster hosted by one or more cache servers. See Out-of-Process with Coherence*Extend Topology.
In these deployments, there are three types of participants:
Cache servers (storage servers), which are used to store the actual session data in memory.
Web (application) servers, which are the Extend clients in this topology. They are not members of the cluster; instead, they connect to a proxy node in the cluster that will issue requests to the cluster on their behalf.
Proxy servers, which are storage-disabled members (nodes) of the cluster that accept and manage TCP/IP connections from Extend clients. Requests that arrive from clients will be sent into the cluster, and responses will be sent back through the TCP/IP connections.
For the cache server:
Follow the instructions for configuring the cache server in Deploying and Running Applications Out-of-Process. Also, edit the cache server's copy of the default-session-cache-config.xml
file to add the system properties coherence.session.proxy=false
and coherence.session.localstorage=true
.
See Configure the Cache for Proxy and Storage JVMs for more information and an example of a default-session-cache-config.xml
file with these context parameters.
For the Web tier (application) server:
Follow the instructions for configuring the application server in Deploying and Running Applications Out-of-Process. Also, complete these steps:
Ensure that Coherence*Web is configured to use the Optimistic Locking mode. Optimistic locking is the default locking mechanism for Coherence*Web (see Optimistic Locking).
Edit the application server's copy of the default-session-cache-config.xml
file to add the proxy JVM host names, IP addresses and ports. To do this, add a <remote-addresses>
section to the file. In most cases, you should include the host name and IP address, and port of all proxy JVMs for load balancing and failover.
For the proxy server:
With a few changes, the proxy server can use the same cache and session configuration as the application server and the cache server. Edit the default-session-cache-config.xml
file to add these system properties:
coherence.session.localstorage=false
to disable local storage.
coherence.session.proxy=true
to indicate that a proxy service is being used.
coherence.session.proxy.localhost
to indicate the host name or IP address of the NIC to which the proxy will bind.
coherence.session.proxy.localport
to indicate a unique port number to which the proxy will bind.
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
HTTP session affinity may need to be explicitly configured when integrating with WebSphere Liberty. Coherence*Web needs to be passed the Clone ID of the Liberty server as well as the affinity separator. If the Clone ID is defined by the user, as explained in the liberty documentation at https://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/twlp_admin_session_persistence.html, and if the affinity separator is the colon character (:
) character, then no additional configuration is required. If that is not the case, then the following system properties can be used during server startup:
coherence.web.liberty.suffix.separator
– The affinity suffix separator. The default value is :
.
coherence.web.liberty.suffix
– The clone id of the server. The default value is the value configured for the cloneId
system property in the bootstrap.properties
file as explained in the WebSphere Liberty documentation cited above.
This section includes the following topics:
To use the Coherence*Web WebInstaller Ant task, add the task import statement illustrated below in to your Ant build file. In this example, ${
coherence.home
}
refers to the root directory of your Coherence installation.
<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 integrating Coherence*Web with a Java EE application from an Ant build:
Build your Java EE application as you ordinarily 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 file.
Run the Coherence*Web Ant task with the operations
attribute set to install
.
Performing Iterative Development
If you are performing iterative development on your application, such as modifying JavaServer Pages (JSPs), Servlets, static resources, and so on, use the following integration 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 file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).
Build your Java EE application as you ordinarily would.
Run the Coherence*Web Ant task with the operations
attribute set to inspect
, and the install
and descriptor
attributes set to the location of the previously generated Coherence*Web XML descriptor file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).
Changing the Coherence*Web Configuration Settings of a Java EE Application
If you must change the Coherence*Web configuration settings of a Java EE application that is using Coherence*Web, follow these steps:
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 file for the Java EE application.
Change the necessary configuration parameters in the Coherence*Web XML descriptor file.
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 file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).
Table 3-2 describes the attributes that can be used with the Coherence*Web WebInstaller Ant task.
Table 3-2 Coherence*Web WebInstaller Ant Task Attributes
Attribute | Description | Required? |
---|---|---|
|
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 |
|
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 |
|
Path to the Coherence*Web XML descriptor file. This attribute defaults to the |
No |
|
Stops the Ant build if the Coherence*Web WebInstaller exits with a status other than 0. The default is |
No |
|
Suppresses warning messages. This attribute can be either |
No |
|
A comma- or space-separated list of operations to perform; each operation must be one of |
Yes |
|
The alias of the target Java EE application server. |
No |
|
Touches JSPs and TLDs that are modified by the Coherence*Web WebInstaller. This attribute can be either |
No |
|
Displays verbose output. This attribute can be either |
No |
The following list provides sample commands for the WebInstaller Ant task.
Inspect the myWebApp.war
Web application and generate a Coherence*Web XML descriptor file called my-coherence-web.xml
in the current working directory:
<cwi app="myWebApp.war" operations="inspect" descriptor="my-coherence-web.xml"/>
Integrate Coherence*Web into the myWebApp.war
Web application using the Coherence*Web XML descriptor file called my-coherence-web.xml
found in the current working directory:
<cwi app="myWebApp.war" operations="install" descriptor="my-coherence-web.xml"/>
Remove Coherence*Web from the myWebApp.war
Web application:
<cwi app="myWebApp.war" operations="uninstall">
Integrate Coherence*Web into the myWebApp.war
Web application located in the /dev/myWebApp/build
directory using the Coherence*Web XML descriptor file 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"/>
Integrate Coherence*Web into the myWebApp.war
Web application located in the /dev/myWebApp/build
directory using the Coherence*Web XML descriptor file 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 before integrating Coherence*Web:
<cwi app="/dev/myWebApp/build/myWebApp.war" operations="inspect,install"/>
Reintegrate Coherence*Web into the myWebApp.war
Web application located in the /dev/myWebApp/build
directory, using the Coherence*Web XML descriptor file 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"/>
Follow these steps to test HTTP session management with the lightweight load balancer:
Coherence*Web WebInstaller performs many tasks as a part of the inspection step.
The following are the 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 Coherence*Web Context Parameters.
The WebInstaller sets the servlet container to start in storage-disabled mode (that is, it sets coherence.session.localstorage
to false
).
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.
Enumerates the JSP from each Web application in the target Java EE application and adds 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 integration 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 uninstallation step.
Adds the Coherence*Web configuration context parameters generated in Step 1 of the inspection step to the web.xml
descriptor file 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
class in each web.xml
descriptor file. At run time, the Coherence*Web ServletContextListener
class propagates each ServletContextEvent
event to each application-specific ServletContextListener
listener.
Registers a Coherence*Web ServletContextAttributeListener
listener in each web.xml
descriptor file. At run time, the Coherence*Web ServletContextAttributeListener
propagates each ServletContextAttributeEvent
event to each application-specific ServletContextAttributeListener
listener.
Wraps each application-specific Servlet
declared in each web.xml
descriptor file with a Coherence*Web SessionServlet
. At run time, each Coherence*Web SessionServlet
delegates to the wrapped Servlet
.
Adds the following directive to each JSP enumerated in Step 2 of the inspection step:
<%@ page extends="com.tangosol.coherence.servlet.api22.JspServlet" %>
During the uninstallation step, the Coherence*Web WebInstaller replaces the instrumented Java EE application with the backup of the original version created in Step (1) of the integration process.
Coherence*Web can be integrated with applications that uses Java EE security.
To integrate Coherence*Web with an application that uses Java EE security, follow these additional steps:
This configuration causes two sessions to be associated with a given authenticated user:
A Coherence*Web session that contains all session data created by the Web application
A session created by the Web container during authentication that stores only information necessary to identify the user
coherence-session-cookie-httponly
context parameter to append the HttpOnly
attribute to the session cookie. The HttpOnly
attribute is used to help prevent attacks such as cross-site scripting, since it does not allow the cookie to be accessed by a client-side script such as JavaScript.Note that not all browsers support this functionality. This context parameter is available for instrumented applications only.