2 Installing Coherence*Web on WebLogic Server 9.2 MP1 and 10.3

The current release of Coherence*Web provides a deployment option on the WebLogic Server platform that enables a tighter integration with WebLogic Server. The installation and configuration options described in this chapter apply only to WebLogic Server 9.2 MP1 and 10.3 deployments.

2.1 Overview of the 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, or if you have an existing Coherence cluster and want to off-load 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.

2.1.1 Location of the Coherence*Web SPI

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.

2.1.2 Requirements for Using the 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 enforce JVM session stickiness. Documentation for configuring the WebLogic Server proxy plug-in is available here:


2.1.3 Coherence*Web SPI Configurations for the WebLogic Server

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

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

  • 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.RequestTimeoutException exception is thrown.

The Coherence caches used by the Coherence*Web SPI are configured by the session-cache-config.xml file. This 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 repackaged inside coherence-web-spi.war.

2.2 Overview Of Configuration and Deployment

The Coherence*Web distribution includes a deployable shared library that contains a native plug-in to WebLogic Server's HTTP Session Management interface. To enable Coherence*Web on WebLogic Server for a Web application, complete the following steps:

  1. Apply the WebLogic Server publicly available patch to all WebLogic Server instances that are hosting the Web applications that will use Coherence*Web. Table 2-1 lists the appropriate patches for your version of WebLogic Server and Coherence release level.

    Table 2-1 Required WebLogic Server and Coherence Patch Release Levels

    WebLogic Server 9.2 MP1 WebLogic Server 10.3

    WebLogic Smart Update

    Patch ID: AJQB

    Patch ID: 6W2W

    Minimum Coherence Release Level/MetaLink Patch ID

    3.4.2 Patch2 - Patch ID: 8429415

    3.4.2 Patch6 - Patch ID: 11399293

    The patches can be downloaded by using either the MetaLink Web site or the WebLogic Server's Smart Update utility.

    To Download from MetaLink: 

    1. Go to the Metalink Web site to manually locate the patch.


    2. Select the Patches tab and click the Simple Search link. On the subsequent screen, submit a search for a Patch Number/Name with the appropriate value (for example, 11399293).

    3. Download the patch zip file from the displayed results.

    4. See the README.txt included in the patch zip file for instructions for applying the Coherence patch.

    To Download with Smart Update: 

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


    2. Select Start>All Programs>Oracle WebLogic>Smart Update to open the log in dialog box. Use your Support ID and Password to log in.

      Figure 2-1 WebLogic Smart Update Login Dialog Box

      WebLogic Smart Update Login Dialog Box
    3. Download and apply the appropriate patch for your version of the WebLogic Server: 6W2W for WLS 10.3, AJQB for WLS 9.2 MP1). Restart the WebLogic Server. Figure 2-2 illustrates the 6W2W patch selected in the Smart Update browser.

      Figure 2-2 WebLogic Smart Update Tree Browser

      WebLogic Smart Update Tree Browser
  2. (Optional) modify the session-cache-config.xml file 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 you modify this file, then it should be updated in coherence-web-spi.war.

    See Appendix B, "Session Cache Configuration File" for a description of the default configuration of the session-cache-config.xml file.

  3. Start a Cache Server Tier in a separate JVM from the one running WebLogic Server.

    See "Configuring and Starting a Cache Server" for more information.

  4. Determine the appropriate packaging based on your deployment requirements and follow the packaging instructions.

    See "Packaging Applications and Configuring Cluster Nodes" for more information.

  5. (Optional) Modify the web.xml and weblogic.xml files in the WAR deployment if advanced configuration is required for a Web application using Coherence*Web.

    Coherence Web parameters that can be configured for Web applications running on the WebLogic Server are described in "Configuring Web Applications for Coherence*Web". The entire set of Coherence*Web parameters are described in Appendix A, "Coherence*Web Configuration Parameters."


If you are deploying Coherence*Web in a WebLogic Portal environment, see Chapter 5, "Installing Coherence*Web on WebLogic Portal" for installation instructions.

2.2.1 Configuring and Starting 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 JVM Tuning in the Developer's Guide for Oracle Coherence for more information. (The following command should be entered on one line but is wrapped here for ease of reading.)

    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.session.localstorage=true com.tangosol.net.DefaultCacheServer
  2. Start one or more cache server JVMs using the script described in the previous step.

2.2.2 Packaging Applications and Configuring Cluster Nodes

Coherence cluster nodes are class loader scoped. Therefore, you must configure the number of unique Coherence cluster nodes in a Coherence*Web deployment before packaging the application(s). The packing and configuration options are described in the following sections:

You can find detailed information about each of the options under "Cluster Node Isolation".

You will find the coherence.jar and coherence-web-spi.war files located in the /lib directory of the Coherence distribution.


The application server-scoped cluster configuration should be considered very carefully and never used in environments where application interaction is unknown or unpredictable.

An example of such an environment may be a deployment where multiple application teams are deploying applications written independently, without carefully coordinating and enforcing their conventions and naming standards. 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, Oracle Coherence strongly recommends that you use EAR-scoped and WAR-scoped cluster node configurations. If you are in doubt regarding which deployment topology to choose, or if this warning applies to your deployment, then do not choose the application server-scoped cluster node 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 your WebLogic Server system classpath to include coherence.jar or copy the JAR to your $DOMAIN_HOME/lib directory.

  3. Enable Coherence*Web in your Web application.

    Add the library reference stanza illustrated in Example 2-1 to the weblogic.xml in each WAR file deployed in the WebLogic server that intends to use Coherence*Web.

Example 2-1 Library Reference for Each WAR File

</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. Enable Coherence*Web.

    Create a shared library reference in each Web application in the EAR by adding the stanza illustrated in Example 2-2 to the weblogic.xml file:

    Example 2-2 Library Reference for Each Web Application in the EAR

    </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. Enable Coherence*Web.

    Create a shared library reference by adding the stanza illustrated in Example 2-3 to the weblogic.xml file in the Web application's WEB-INF directory.

Example 2-3 Library Reference for the Web Application


2.2.3 Configuring Web Applications for Coherence*Web

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.

The Coherence*Web SPI ships with a configuration that should be sufficient for most Web applications. If you must make any changes to the configuration or override any previous settings, you can apply any of the Coherence*Web parameters described in Appendix A, "Coherence*Web Configuration Parameters," You can apply these parameters by using the <context-param> element in the web.xml file.

Table 2-2 lists only those Coherence*Web parameters which have a WebLogic-specific default. For full descriptions of all Coherence*Web parameters, see Appendix A, "Coherence*Web Configuration Parameters."

Table 2-2 Parameters that can be Configured in web.xml

Parameter WebLogic-Specific Default


If unspecified, defaults to com.tangosol.coherence.servlet.SplitHttpSessionCollection.


If unspecified, defaults to false


If unspecified, defaults to true


If unspecified, defaults to true.


If unspecified, defaults to true


If unspecified, defaults to com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController


If unspecified, defaults to true

Table 2-3 describes the generated HTTP session cookie parameters that can be configured in weblogic.xml or weblogic-application.xml file using the <session-descriptor> element.

Table 2-3 HTTP Session Cookie Parameters

Parameter Name Default Description



Specifies the comment that identifies the session tracking cookie in the cookie file.



Specifies the domain for which the cookie is valid. For example, setting cookie-domain to.mydomain.com returns cookies to any server in the *.mydomain.com domain.

The domain name must have at least two components. Setting a name to *.com or *.net is not valid.

If not set, this attribute defaults to the server that issued the cookie.

For more information, see Cookie.setDomain() in the Servlet specification from Sun Microsystems.



Use of session cookies is enabled by default and is recommended, but you can disable them by setting this property to false. You might turn this option off to test.



Sets the life span of the session cookie, in seconds, after which it expires on the client.

The default value is -1 (unlimited).

For more information about cookies, see Using Sessions and Session Persistence.



Defines the session tracking cookie path.

If not set, this attribute defaults to / (slash), where the browser sends cookies to all URLs served by WebLogic Server. You may set the path to a narrower mapping, to limit the request URLs to which the browser sends cookies.



Tells the browser to only send the cookie back over an HTTPS connection. This ensures that the cookie ID is secure and should only be used on Web sites that use HTTPS. Session Cookies over HTTP no longer work if this feature is enabled.

You should disable the url-rewriting-enabled element if you intend to use this feature.



Sets the size of the session ID.

The minimum value is 8 bytes and the maximum value is Integer.MAX_VALUE.

If you are writing a WAP application, you must use URL rewriting because the WAP protocol does not support cookies. Also, some WAP devices have a 128-character limit on URL length (including attributes), which limits the amount of data that can be transmitted using URL re-writing. To allow more space for attributes, use this attribute to limit the size of the session ID that is randomly generated by WebLogic Server.

You can also limit the length to a fixed 52 characters, and disallow special characters, by setting the WAPEnabled attribute. For more information, see URL Rewriting and Wireless Access Protocol in Developing Web Applications for WebLogic Server.

In the WebLogic SPI module, the Coherence*Web configuration parameters listed in Table 2-4 are not controlled by Coherence*Web and must be specified as outlined in the table.

Table 2-4 Unsupported Coherence*Web Configuration Parameters for WebLogic Server SPI

Parameter Alternative configuration setting to be used


Not Supported.


Not Supported.


Not Supported.


Not Supported.


This value is set by the WebLogic session-descriptor cookies-enabled element in weblogic.xml or weblogic-application.xml.


This value is set by the WebLogic session-descriptor cookie-domain element in weblogic.xml or weblogic-application.xml.


This value is set by the WebLogic session-descriptor cookie-path element in weblogic.xml or weblogic-application.xml.


This value is set by the WebLogic session-descriptor cookie-max-age-secs element in weblogic.xml or weblogic-application.xml.


Not Supported.


Not Supported.


Not Supported.


Not Supported.


This value is set by the WebLogic session-descriptor id-length element in weblogic.xml or weblogic-application.xml.

2.3 Using SAML SSO with Coherence*Web

WebLogic Server provides basic single sign-on (SSO) functionality by default. To use SAML SSO functionality with Coherence*Web, you must modify the contents of the saml2.war Web application.

  1. Backup the existing saml2.war in the WebLogic Server installation.

  2. Un-jar the saml2.war into a temporary directory.

    The saml2.war is located in the $WL_SERVER_HOME/server/lib directory.

  3. Create a lib directory and a classes directory under the WEB-INF directory.

  4. Un-jar the coherence-web-spi.war to retrieve coherence-web.jar and coherence-web-spi.jar. Copy these two jars to the /WEB-INF/lib directory.

  5. Copy the session-cache-config.xml file, located in the /WEB-INF/classes directory from the un-jarred coherence-web-spi.war, into the /WEB-INF/classes directory.

  6. Place the coherence.jar in the appropriate location, based on the cluster node scoping you selected: application server-, EAR-, or WAR-scoped.

  7. Add the code in Example 2-4 to the /WEB-INF/web.xml file:

    Example 2-4 Enabling Coherence Web Sessions in web.xml

    <?xml version="1.0" encoding="UTF-8"?>
  8. Re-assemble the saml2.war by using the jar command, for example:

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

2.4 Known Limitations

By default, Coherence*Web creates a single HTTP Session across all Web applications for each client and scopes the session attributes to 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 you do not want this behavior, a potential work-around is to reduce the scope the session cookie by adding the entry illustrated in Example 2-5 to the weblogic.xml file in each Web application.

Example 2-5 Ensuring a Unique Session for Each Web Application

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

This ensures 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 work-around does not work if you deploy an EAR or Web application with "/" as the context path, or if you require WebLogic SSO. WebLogic SSO requires that the session cookie path be set to "/".