2 Installing Coherence*Web on the WebLogic Server 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 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 instrumentation 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 will enforce JVM session stickiness. Documentation for configuring the WebLogic Server proxy plug-in is available here:

https://download.oracle.com/docs/cd/E12840_01/wls/docs103/cluster/load_balancing.html#wp1026940

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.RequestTiemoutException 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:

Apply the WebLogic Server publicly available patch ID N41D to all WebLogic Server instances that are hosting the Web applications that will use Coherence*Web.

See the instructions for using Smart Update to install WebLogic Server patches.

https://download.oracle.com/docs/cd/E11035_01/smartUpdate31/guide/install.html#wp1091614

For production environments it is recommended that you review the Smart Update production installation:

https://download.oracle.com/docs/cd/E12840_01/common/smartupdate/guide/remote.html#wp1071859
1. Log in to Smart Update using your Support ID and Password.
  
  Figure 2-1 WebLogic Smart Update Login Dialog Box
  
  Description of "Figure 2-1 WebLogic Smart Update Login Dialog Box"
2. Download and apply patch N41D. Restart the WebLogic Server.
  
  Figure 2-2 WebLogic Smart Update Tree Browser
  
  Description of "Figure 2-2 WebLogic Smart Update Tree Browser"
(Optional) modify the session-cache-config.xml file to customize the Cache topology for Coherence*Web.

See Appendix B, "Session Cache Configuration File" for a description of the default configuration of the session-cache-config.xml file.
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.
Determine the appropriate packaging based on your deployment requirements and follow the packaging instructions.

See "Packaging Applications and Configuring Cluster Nodes" for more information.
(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, "Configuration Parameters for Coherence*Web."

Note:

If you are deploying Coherence*Web in a WebLogic Portal environment, see Chapter 5, "Installing Coherence*Web on WebLogic Portal 10.3" 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.

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.

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

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:

Packaging and Configuring Application Server-Scoped Cluster Nodes
Packaging and Configuring EAR-Scoped Cluster Nodes
Packaging and Configuring WAR-Scoped Cluster Nodes

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

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.

Note:

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 as to which deployment topology to choose, or if this warning applies to your deployment, then do not choose the application server-scoped cluster node configuration.

2.2.2.1 Packaging and Configuring Application Server-Scoped Cluster Nodes

Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
Edit your WebLogic Server system classpath to include coherence.jar or copy the JAR to your $DOMAIN_HOME/lib directory.
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>
     ...
      <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>

2.2.2.2 Packaging and Configuring EAR-Scoped Cluster Nodes

Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
Place coherence.jar in the EAR's APP-INF/lib directory.

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

2.2.2.3 Packaging and Configuring WAR-Scoped Cluster Nodes

Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
Place coherence.jar in the WAR's WEB-INF/lib directory.
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

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

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 need to 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-1 lists the Coherence*Web parameters and identifies whether they have a WebLogic-specific default. For full descriptions of the parameters, see Appendix A, "Coherence*Web Configuration Parameters."

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

Parameter	WebLogic-Specific Default
coherence-factory-class	No WebLogic-specific default.
coherence-sessioncollection-class	If unspecified, defaults to `com.tangosol.coherence.servlet.SplitHttpSessionCollection`.
coherence-cluster-owned	No WebLogic-specific default.
coherence-contextless-session-retain-millis	No WebLogic-specific default.
coherence-reaperdaemon-cluster-coordinated	No WebLogic-specific default.
coherence-reaperdaemon-sweep-modulo	No WebLogic-specific default.
coherence-reaperdaemon-assume-locality	If unspecified, defaults to `false`
coherence-reaperdaemon-cycle-second	No WebLogic-specific default.
coherence-reaperdaemon-priority	No WebLogic-specific default.
coherence-session-cachename	No WebLogic-specific default.
coherence-session-deathcert-cachename	No WebLogic-specific default.
coherence-session-management-cachename	No WebLogic-specific default.
coherence-session-expire-seconds	No WebLogic-specific default.
coherence-shutdown-delay-seconds	No WebLogic-specific default.
coherence-session-member-locking	If unspecified, defaults to `true`
coherence-session-thread-locking	No WebLogic-specific default.
coherence-session-strict-spec	No WebLogic-specific default.
coherence-sticky-sessions	If unspecified, defaults to `true`
coherence-distributioncontroller-class	If unspecified, defaults to `com.tangosol.coherence.servlet.AbstractHttpSessionCollection.HybridController`
coherence-scopecontroller-class	If unspecified, defaults to `com.tangosol.coherence.servlet.AbstractHttpSessionCollection.ApplicationScopeController`
coherence-preserve-attributes	If unspecified, defaults to `true`
coherence-local-session-cachename	No WebLogic-specific default.
coherence-local-attribute-cachename	No WebLogic-specific default.
coherence-session-overflow-cachename	No WebLogic-specific default.
coherence-attribute-overflow-threshold	No WebLogic-specific default.

Table 2-2 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-2 HTTP Session Cookie Parameters

Parameter Name	Default	Description
`cookie-comment`	null	Specifies the comment that identifies the session tracking cookie in the cookie file.
`cookie-domain`	null	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.
`cookies-enabled`	true	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.
`cookie-max-age-secs`	-1	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.
`cookie-path`	null	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.
`cookie-secure`	false	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.
`id-length`	52	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-3 are not controlled by Coherence*Web and must be specified as outlined in the table.

Table 2-3 Coherence*Web Configuration Parameters which Must be Specified

Parameter	Alternative configuration setting to be used
coherence-servletcontext-clustered	Not Supported.
coherence-servletcontext-cachename	Not Supported.
coherence-eventlisteners	Not Supported.
coherence-enable-sessioncontext	Not Supported.
coherence-session-cookies-enabled	This value is set by the WebLogic session-descriptor `cookies-enabled` element in `weblogic.xml` or `weblogic-application.xml`.
coherence-session-cookie-domain	This value is set by the WebLogic session-descriptor `cookie-domain` element in `weblogic.xml` or `weblogic-application.xml`.
coherence-session-cookie-path	This value is set by the WebLogic session-descriptor `cookie-path` element in `weblogic.xml` or `weblogic-application.xml`.
coherence-session-cookie-max-age	This value is set by the WebLogic session-descriptor `cookie-max-age-secs` element in `weblogic.xml` or `weblogic-application.xml`.
coherence-session-urlencode-enabled	Not Supported.
coherence-session-urlencode-name	Not Supported.
coherence-session-urldecode-bycontainer	Not Supported.
coherence-session-urlencode-bycontainer	Not Supported.
coherence-session-id-length	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.

Backup the existing saml2.war in the WebLogic Server installation.
Un-jar the saml2.war into a temporary directory.

The saml2.war is located in the $WL_SERVER_HOME/server/lib directory.
Create a lib directory and a classes directory under the WEB-INF directory.
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.
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.
Place the coherence.jar in the appropriate location, based on the cluster node scoping you selected: application server-, EAR-, or WAR-scoped.

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"?>
     <web-app>
     ...
     <context-param>
          <param-name>coherence-web-sessions-enabled</param-name>
          <param-value>true</param-value>
     </context-param>
     ...
     </web-app>

Re-assemble the saml2.war by using the jar command, for example:
```
jar cvf saml2.war $tempdir
```
Backup the existing saml2.war in the WebLogic Server installation.
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

<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 work-around will 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 "/".