Coherence*Web and WebLogic Server

Introduction

New in this release of Coherence*Web is a deployment option on the WebLogic Server platform that enables a tighter integration with WebLogic Server. The installation and configuration options described here only apply to WebLogic Server 10.3 deployments. It should be noted that the configuration of Coherence*Web for WebLogic Server is likely to change in future releases as Coherence*Web is even more tightly integrated into the WebLogic Server.

Overview of Coherence*Web SPI

Coherence*Web is not a replacement for WebLogic Server's in-memory HTTP state replication services. However, Coherence*Web should be considered when an application has large Http Session State objects, when running into memory constraints due to storing Http Session object data, and/or have existing Coherence Cluster and would like to offload Http Session storage to a Coherence Cluster.

The most significant change introduced by this new deployment option is that applications deployed using the Coherence*Web SPI module no longer require an application to be instrumented by the Coherence*Web WebInstaller.

Installation

Location of the WebLogic Server Coherence*Web SPI in Coherence Distribution

The Weblogic Server Coherence*Web SPI consists of the coherence-web-spi.war file, located in the coherence\lib directory in the Coherence distribution. The coherence.jar file, located in the same directory, is also necessary for enabling Coherence*Web functionality in WebLogic Server.

Requirements for using Coherence*Web SPI

The Coherence*Web SPI for Weblogic Server requires that a load balancer which enforces http session JVM affinity is running in front of the WebLogic Server tier. WebLogic Server ships with several different proxy plug-ins which will enforce JVM session stickiness. Documentation for configuring the WebLogic Server proxy plug-in is available here.

Overview Of Configuration and Deployment

The Coherence*Web distribution includes a deployable shared library that contains a native plugin to WebLogic Server's Http Session Management interface. To enable Coherence*Web on WebLogic Server for a web application, you must complete the following steps:

1. Apply WebLogic Server publically available Patch ID N41D to all WebLogic Server instances that are hosting the web application(s) that will leverage Coherence*Web. Please see the instructions for using Smart Update to install WebLogic Server patches. For production environments it is recommended that you review the Smart Update production installation notes.
   1. Login in using your Support ID and Password.
      
   2. Download and apply patch N41D. Restart WebLogic Server.
      
2. Optionally modify the session-cache-config.xml to customize the Cache topology for Coherence*Web. This configuration file is located in the /WEB-INF/classes directory within the coherence-web-spi.war file. If this file is modified, it should be updated in coherence-web-spi.war.
3. Start a Cache Server Tier in a seperate JVM from the one running WebLogic Server per the instructions below.
4. Determine the appropriate packaging based on your deployment requirements and follow the appropriate packaging instructions.
5. Optionally modify the web.xml and weblogic.xml files in the WAR deployment if advanced configuration is required for a web application using Coherence*Web.

   If you are deploying Coherence*Web in a WebLogic Portal environment please see the Coherence*Web and WebLogic Portal page for installation instructions.

Coherence*Web WebLogic SPI-Specific Configurations

There are two differences between the default cache configuration for the Coherence*Web SPI for WebLogic Server and Coherence*Web:

1. The Coherence*Web SPI for WebLogic Server is configured with local-storage disabled. This means a Coherence Cache Server must be running in its own JVM, separate from the JVM running WebLogic Server.
2. The timeout for requests to the cache server to respond is 30 seconds. If a request to the cache server has not responded in 30 seconds, a com.tangosol.net.RequestTiemoutException exception is thrown.

The Coherence caches used by the Coherence*Web SPI is configured by the session-cache-config.xml file. The session-cache-config.xml file is located inside the coherence-web-spi.war file under the WEB-INF\classes directory. Any cache configuration change should be put inside session-cache-config.xml, and then should be repackaged inside coherence-web-spi.war.

To Configure and Start a Cache Server

A Cache Server JVM is a dedicated Coherence JVM that is responsible for storing and managing all cached data (in this case, HttpSession state). One or more Cache Server JVMs must be started before the WLS/WLP JVMs can be started.

1. Create a script for starting a Cache Server JVM. The following is an very simple example of a script that starts a storage-enabled Cache Server for use with Coherence*Web. This example assumes that you are using a Sun JVM. See this page for information on tuning your particular JVM.
   
   java -server -Xms512m -Xmx512m -cp <Coherence installation dir>/lib/coherence.jar:<Coherence installation dir>/lib/coherence-web-spi.war -Dtangosol.coherence.management.remote=true -Dtangosol.coherence.cacheconfig=WEB-INF/classes/session-cache-config.xml -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
   
   
2. Start one or more Cache Server JVMs using the script described above.

Packaging and Configuration Considerations

As part of the Coherence*Web SPI for WebLogic Server you will find the coherence.jar and coherence-web-spi.war located in the /lib directory of the Coherence 3.4.2 distribution.

Coherence cluster nodes are class loader scoped. Therefore, controlling the number of unique Coherence cluster nodes in a Coherence*Web deployment needs to be decided prior to packaging the application(s). The different options are listed below and are described in detail on the Cluster Node Isolation in Coherence*Web page:

• Application Server Scoped Cluster Nodes
• EAR Scoped Cluster Nodes
• WAR Scoped Cluster Nodes

  Be Careful The Application Server Scoped Cluster Nodes configuration should be considered very carefully and never used in environments where application interaction is unknown or unpredictable. An example of such environment may be a deployment where multiple development teams are deploying independently written applications without coordinating and enforcing their conventions and naming standards carefully. With this configuration, all applications are part of the same cluster and the likelihood of collisions between namespaces for caches, services and other configuration settings is quite high and may lead to unexpected results. For these reasons we strongly recommend either the EAR Scoped or WAR Scoped cluster node configurations. If you are in doubt as to which deployment topology to choose or if this warning applies to your deployment, please do not choose this configuration.

Packaging and Configuring Application Server Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
2. Edit you WebLogic Server system classpath to include coherence.jar or copy coherence.jar to you $DOMAIN_HOME/lib directory.
3. Enable Coherence*Web in your web application by adding the following to stanza in the weblogic.xml in each WAR file deployed in the WebLogic Server that intends to leverage Coherence*Web:
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
           	<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   
   
   </weblogic-web-app>

Packaging and Configuring EAR Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
2. Place coherence.jar in the EAR's APP-INF/lib directory.
3. To enable Coherence*Web create a shared library reference in each web application in the EAR by adding the following stanza weblogic.xml:
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
   		<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   </weblogic-web-app>

Packaging and Configuring WAR Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server
2. Place coherence.jar in the WAR's WEB-INF/lib directory.
3. Create a reference to the shared library by modifying the weblogic.xml in web applications WEB-INF directory.
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
   		<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   <weblogic-web-app>

Coherence*Web Configuration Options

Since Coherence*Web is in control of the http session lifecycle, most data from the <session-descriptor> element in either weblogic.xml or weblogic-application.xml is ignored. Most of Coherence*Web configuration can be done through <context-param> in web.xml. The default configuration included in the SPI should be sufficient for most web application usages, but all configurations options can be overidden using <context-param>. 

The following Coherence*Web settings can be configured in web.xml using <context-param>:

Please see the Configuring Coherence*Web page for detailed information on each of the above parameters.

The generated Http session cookie can be configured in weblogic.xml or weblogic-application.xml using <session-descriptor>:

In WebLogic SPI module the following Coherence Web Configuration parameters are not controlled by the Coherence Web Configuration parameters and will need to be specified as outlined below instead:

Using SAML SSO

By default, WebLogic Server provides basic SSO functionality. To leverage SAML SSO functionality with Coherence*Web, the saml2.war web application must be modified.

1. Backup the existing saml2.war in the WebLogic Server installation.
2. Unjar the saml2.war into a temporary directory. The saml2.war is located in the $WL_SERVER_HOME/server/lib directory.
3. Create a lib and classes directory under the WEB-INF directory.
4. Unjar the coherence-web-spi.war to retrieve coherence-web.jar and coherence-web-spi.jar. Put these two jars in the /WEB-INF/lib directory.
5. Copy the session-cache-config.xml, located in the /WEB-INF/classes directory from the exploded coherence-web-spi.war, into the the created /WEB-INF/classes directory.
6. Place the coherence.jar in the proper location, based on the cluster node scoping you selected: Application Server, EAR or WAR scoped.
7. Add the following to the /WEB-INF/web.xml file:
   
   

   <?xml version="1.0" encoding="UTF-8"?>
   
   	<web-app>..
   
   	<context-param>
   
   		<param-name>coherence-web-sessions-enabled</param-name>
   
   		<param-value>true</param-value>
   
   	</context-param>
   
   	...
   
   	</web-app>

8. Re-assemble the saml2.war by using the jar command, e.g.:
   
   

   jar cvf saml2.war $tempdir

9. Backup the existing saml2.war in the WebLogic Server installation.
10. Replace the saml2.war in the WebLogic installation with the modified saml2.war.

Known Limitations

By default, Coherence*Web creates a single HTTP session across all web applications for each client and scopes the session attributes to a each web application. This means that if a session is invalidated in one web application, that same session is invalidated for all web applications in WebLogic Server using Coherence*Web.

This functionality requires that the session cookie path is set to "/", making the same session cookie available to all web applications. If this is not the desired behavior, a potential workaround is to reduce the scope the session cookie by adding the following entry to weblogic.xml in each web application:

<weblogic-web-app>

	...

	<session-descriptor>

		<cookie-path>[path of web-app context, for example "/mainApp/subApp"]</cookie-path>

	</session-descriptor>

	...

</weblogic-web-app>

This will ensure a unique session is created for each web application. It is also possible to scope the session to all web-applications within an EAR file by setting the session cookie path to the context root of the deployed EAR.

This workaround around will not work if you deploy an EAR or web-application with '/' as the context path, or if you require WebLogic Single Sign-On. WebLogic Single Sign-On requires that the session cookie path be set to '/'.