3 Using Coherence*Web on Other Application Servers
Note:
Consult Supported Web Containers to see if you must perform any application server-specific integration steps.
This chapter includes the following sections:
- Integrating Coherence*Web Using the WebInstaller
Coherence*Web can be enabled for Jakarta EE applications on several different Web containers. - Coherence*Web WebInstaller Ant Task
The Coherence*Web WebInstaller Ant task enables you to run the utility from within your existing Ant build files. - Testing HTTP Session Management
Coherence comes with a lightweight software load balancer intended only for testing purposes. - How the Coherence*Web WebInstaller Instruments a Jakarta EE Application
Coherence*Web WebInstaller performs many tasks as a part of the inspection step. - Integrating Coherence*Web with Applications Using Jakarta Security
Coherence*Web can be integrated with applications that use Jakarta Security. - Preventing Cross-Site Scripting Attacks
Use thecoherence-session-cookie-httponlycontext parameter to append theHttpOnlyattribute to the session cookie. TheHttpOnlyattribute limits script access to the cookie. It helps protect the cookie value if script injection occurs, but does not prevent cross-site scripting or authorize a request. - Selecting CoherenceWeb Artifacts and Container APIs
Match the module, Servlet API, class loader and release before installing or instrumenting an application.
Integrating Coherence*Web Using the WebInstaller
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 Jakarta 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:
- General Instructions for Integrating Coherence*Web Session Management Module
- Deploying and Running Applications In Process
- Deploying and Running Applications Out-of-Process
- Migrating to Out-of-Process Topology
- Deploying and Running Applications Out-of-Process with Coherence*Extend
- Enabling Sticky Sessions for Apache Tomcat Servers
- Integrating with IBM WebSphere Liberty
Parent topic: Using Coherence*Web on Other Application Servers
General Instructions for Integrating Coherence*Web Session Management Module
Complete the following steps to integrate Coherence*Web with a Jakarta EE application on any of the Web containers listed under Supported Web Containers.
If you are integrating Coherence*Web with a Jakarta 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 Jakarta EE application on an IBM WebSphere Server, see also Integrating with IBM WebSphere Liberty for additional instructions.
To integrate Coherence*Web for the Jakarta EE application you are deploying:
Parent topic: Integrating Coherence*Web Using the WebInstaller
Deploying and Running Applications In Process
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:
- Start the application server in storage-enabled mode. Add the system property
coherence.session.localstorage=trueto the Java options of your application server startup script. - Deploy the
coherence.jarandcoherence-web.jarfiles as shared libraries. - Deploy and run your application.
Parent topic: Integrating Coherence*Web Using the WebInstaller
Deploying and Running Applications Out-of-Process
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.cacheconfigsystem property to the cache server startup script to locate the file configuration file. You must also include the system propertycoherence.session.localstorage=trueto enable storage for the cache server. -
Add the
coherence.jarandcoherence-web.jarfiles 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):
Parent topic: Integrating Coherence*Web Using the WebInstaller
Migrating to Out-of-Process Topology
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.
Parent topic: Integrating Coherence*Web Using the WebInstaller
Deploying and Running Applications Out-of-Process with Coherence*Extend
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.xmlfile 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=falseto disable local storage. -
coherence.session.proxy=trueto indicate that a proxy service is being used. -
coherence.session.proxy.localhostto indicate the host name or IP address of the NIC to which the proxy will bind. -
coherence.session.proxy.localportto indicate a unique port number to which the proxy will bind.
Parent topic: Integrating Coherence*Web Using the WebInstaller
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
Parent topic: Integrating Coherence*Web Using the WebInstaller
Integrating with IBM WebSphere Liberty
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 thecloneIdsystem property in thebootstrap.propertiesfile as explained in the WebSphere Liberty documentation cited above.
Parent topic: Integrating Coherence*Web Using the WebInstaller
Coherence*Web WebInstaller Ant Task
This section includes the following topics:
- Using the Coherence*Web WebInstaller Ant Task
- Configuring the WebInstaller Ant Task
- WebInstaller Ant Task Examples
Parent topic: Using Coherence*Web on Other Application Servers
Using the Coherence*Web WebInstaller Ant Task
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 Jakarta EE application from an Ant build:
-
Build your Jakarta EE application as you ordinarily would.
-
Run the Coherence*Web Ant task with the
operationsattribute set toinspect. -
Make any necessary changes to the generated Coherence*Web XML descriptor file.
-
Run the Coherence*Web Ant task with the
operationsattribute set toinstall.
Performing Iterative Development
If you are performing iterative development on your application, such as modifying Jakarta Server Pages (JSPs), Servlets, static resources, and so on, use the following integration process:
-
Run the Coherence*Web Ant task with the
operationsattribute set touninstall, thefailonerrorattribute set tofalse, and thedescriptorattribute 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 Jakarta EE application as you ordinarily would.
-
Run the Coherence*Web Ant task with the
operationsattribute set toinspect, and theinstallanddescriptorattributes 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 Jakarta EE Application
If you must change the Coherence*Web configuration settings of a Jakarta EE application that is using Coherence*Web, follow these steps:
-
Run the Coherence*Web Ant task with the
operationsattribute set touninstalland thedescriptorattribute set to the location of the Coherence*Web XML descriptor file for the Jakarta EE application. -
Change the necessary configuration parameters in the Coherence*Web XML descriptor file.
-
Run the Coherence*Web Ant task with the
operationsattribute set toinstalland thedescriptorattribute set to the location of the modified Coherence*Web XML descriptor file (from Step 2 of Using the Coherence*Web WebInstaller Ant Task).
Parent topic: Coherence*Web WebInstaller Ant Task
Configuring the 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 Jakarta 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 Jakarta EE application. This attribute defaults to the directory that contains the Jakarta 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 Jakarta 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 |
Parent topic: Coherence*Web WebInstaller Ant Task
WebInstaller Ant Task Examples
The following list provides sample commands for the WebInstaller Ant task.
-
Inspect the
myWebApp.warWeb application and generate a Coherence*Web XML descriptor file calledmy-coherence-web.xmlin the current working directory:<cwi app="myWebApp.war" operations="inspect" descriptor="my-coherence-web.xml"/>
-
Integrate Coherence*Web into the
myWebApp.warWeb application using the Coherence*Web XML descriptor file calledmy-coherence-web.xmlfound in the current working directory:<cwi app="myWebApp.war" operations="install" descriptor="my-coherence-web.xml"/>
-
Remove Coherence*Web from the
myWebApp.warWeb application:<cwi app="myWebApp.war" operations="uninstall"/>
-
Integrate Coherence*Web into the
myWebApp.warWeb application located in the/dev/myWebApp/builddirectory using the Coherence*Web XML descriptor file calledmy-coherence-web.xmlfound in the/dev/myWebApp/srcdirectory, and place a backup of the original Web application in the/dev/myWebApp/workdirectory:<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.warWeb application located in the/dev/myWebApp/builddirectory using the Coherence*Web XML descriptor file calledcoherence-web.xmlfound in the/dev/myWebApp/builddirectory. If the Web application has not already been inspected (that is,/dev/myWebApp/build/coherence-web.xmldoes 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.warWeb application located in the/dev/myWebApp/builddirectory, using the Coherence*Web XML descriptor file calledmy-coherence-web.xmlfound in the/dev/myWebApp/srcdirectory:<cwi app="/dev/myWebApp/build/myWebApp.war" operations="uninstall,install" descriptor="/dev/myWebApp/src/my-coherence-web.xml"/>
Parent topic: Coherence*Web WebInstaller Ant Task
Testing HTTP Session Management
Follow these steps to test HTTP session management with the lightweight load balancer:
Parent topic: Using Coherence*Web on Other Application Servers
How the Coherence*Web WebInstaller Instruments a Jakarta EE Application
Coherence*Web WebInstaller performs many tasks as a part of the inspection step.
The following are the tasks:
-
Generates a template
coherence-web.xmlconfiguration 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.localstoragetofalse).If an existing
coherence-web.xmlconfiguration 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 Jakarta EE application and adds information about each JSP to the
coherence-web.xmlconfiguration file. -
Enumerates the TLDs from each Web application in the target Jakarta EE application and adds information about each TLD to the
coherence-web.xmlconfiguration file. - Scans the web application and all classes contained within, for annotations and
generates markup that is inserted into the appropriate
web.xmlorweb-fragment.xml. - For each ServletContainerInitializer found, create a custom ServletContainerInitializer that will invoke the application’s initializer when the context starts. This allows Coherence*Web to enact properly on dynamically registered Servlet artifacts.
During the integration step, the Coherence*Web WebInstaller performs the following tasks:
-
Creates a backup of the original Jakarta 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.xmldescriptor file of each Web application contained in the target Jakarta EE application. -
Unregisters any application-specific
ServletContextListener,ServletContextAttributeListener,ServletRequestListener,ServletRequestAttributeListener,HttpSessionListener, andHttpSessionAttributeListenerclasses (including those registered by TLDs) from each Web application. -
Registers a Coherence*Web
ServletContextListenerclass in eachweb.xmldescriptor file. At run time, the Coherence*WebServletContextListenerclass propagates eachServletContextEventevent to each application-specificServletContextListenerlistener. -
Registers a Coherence*Web
ServletContextAttributeListenerlistener in eachweb.xmldescriptor file. At run time, the Coherence*WebServletContextAttributeListenerpropagates eachServletContextAttributeEventevent to each application-specificServletContextAttributeListenerlistener. -
Wraps each application-specific
Servletdeclared in eachweb.xmldescriptor file with a Coherence*WebSessionServlet. At run time, each Coherence*WebSessionServletdelegates to the wrappedServlet. -
Adds the following directive to each JSP enumerated in Step 2 of the inspection step:
<%@ page extends="com.tangosol.coherence.servlet.api22.JspServlet" %>
Note:
The presence of duplicate page extends in JSP may cause errors after Coherence*Web is integrated with the Jakarta EE application. Therefore, remove the replicated page extends. You do not need to add page extends explicitly because the Coherence*Web WebInstaller utility adds page extends for the Coherence servlet context by default.During the uninstallation step, the Coherence*Web WebInstaller replaces the instrumented Jakarta EE application with the backup of the original version created in Step (1) of the integration process.
Parent topic: Using Coherence*Web on Other Application Servers
Integrating Coherence*Web with Applications Using Jakarta Security
Coherence*Web can be integrated with applications that use Jakarta Security.
To integrate Coherence*Web with an application that uses Jakarta 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
Parent topic: Using Coherence*Web on Other Application Servers
Preventing Cross-Site Scripting Attacks
Use the coherence-session-cookie-httponly context parameter to append the HttpOnly attribute to the session cookie. The HttpOnly attribute limits script access to the cookie. It helps protect the cookie value if script injection occurs, but does not prevent cross-site scripting or authorize a request.
Configure HTTPS and the Secure cookie attribute, appropriate SameSite/path/domain policy and application output encoding/CSRF protection through the container/application. This context parameter is available for instrumented applications only.
Parent topic: Using Coherence*Web on Other Application Servers
Selecting CoherenceWeb Artifacts and Container APIs
Match the module, Servlet API, class loader and release before installing or instrumenting an application.
Choose the Coherence*Web module for the actual container Servlet API and the matching Coherence distribution. All modules in the deployment must use compatible release/patch versions; do not combine artifacts just because both use jakarta packages.
Table 3-4 Jakarta Coherence*Web module selection
| Module | Platform/API baseline | Placement requirement |
|---|---|---|
coherence-web-ee9 |
Jakarta EE 9 / Servlet 5.0 | Use the documented container integration and keep one compatible servlet API supplied by the container. |
coherence-web-ee10 |
Jakarta EE 10 / Servlet 6.0 | Use the matching module/dependencies; do not place a duplicate servlet implementation in the application. |
coherence-web-ee11 |
Jakarta EE 11 / Servlet 6.1 | Use the matching container/integration; a Java baseline alone does not certify a container version. |
This table describes the module API targets, not a blanket certification of every container at those levels. WebLogic uses its integrated distribution and supported domain patch procedure. For other servers, follow the selected container instructions, WebInstaller alias or native Tomcat integration and the actual artifact layout.
- Record server/container, Java, Coherence and module versions before deployment. Confirm the supported combination using the distribution certification/release information.
- Keep application session attribute classes, serializers/POF resources and generated trust metadata visible to all session-deserializing tiers.
- Preserve an original WAR/EAR and inspect the instrumented output before deployment. Do not repeatedly instrument an already modified archive without the documented uninstall/reinstall workflow.
- Test create/read/update/invalidate, authentication ID change, failover and restart with representative attributes and listeners. Check the actual class loader on both application and storage tiers.
Use Preparing a Release-Matched WebLogic Deployment for WebLogic and Upgrading and Operating a Secured Deployment for first-start checks.
Parent topic: Using Coherence*Web on Other Application Servers