Skip Headers
Oracle® Coherence User's Guide for Oracle Coherence*Web
Release 3.7.1

E22620-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 Using Coherence*Web with WebLogic Server

Note:

Except where noted, this chapter pertains to the 11g Release 1 Patch Set 3 (10.3.4), or later of Oracle WebLogic Server.

This chapter contains the following sections:

Coherence*Web provides session state persistence and management. It is a session management module that uses Coherence caches for storing and managing session data. This chapter describes how to set up and deploy Coherence*Web so that it can be used by applications running on WebLogic Server.

Coherence*Web is an alternative to the WebLogic Server in-memory HTTP state replication services. Consider using Coherence*Web if you are encountering any of these situations:

New for 3.7.1:

The session-cache-config.xml file has been moved from the coherence-web-spi.war file to the coherence-web.jar file. The coherence-web.jar file can be found in the coherence\lib directory.

2.1 Overview of the Coherence*Web SPI

The Coherence*Web Service Provider Interface (SPI) consists of the coherence-web-spi.war file. To use functionality provided by the coherence-web-spi.war, the coherence.jar classes must also be available to the Web application.

In Coherence*Web, the following default cache configurations are defined:

Coherence cache configurations and services used by Coherence*Web SPI are defined in the session-cache-config.xml file, which can be found in the coherence-web.jar file. The default cache and services configuration defined in the session-cache-config.xml file should satisfy most Web applications.

Coherence*Web provides several session locking modes to control concurrent access of sessions. Both Coherence*Web and the Coherence*Web SPI employ Last Write Wins locking by default. See "Session Locking Modes" for more information about locking modes.

By itself, the Coherence*Web SPI does not require a load balancer to run in front of the WebLogic Server tier. However, a load balancer will improve performance. It is required if the same session will be used concurrently and locking is not enabled. The default load balancer enforces HTTP session JVM affinity, however, other load balancing alternatives are available. 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 at this URL:

http://download.oracle.com/docs/cd/E17904_01/web.1111/e13709/load_balancing.htm

2.2 Configuring and Deploying Coherence*Web—Main Steps

Coherence*Web includes a deployable shared library that contains a native plug-in to the WebLogic Server HTTP Session Management interface. The following steps summarize how to prepare your deployments to use Coherence*Web with applications running on WebLogic Server:

  1. Download Oracle Coherence to your file system. See "Download Oracle Coherence".

  2. Modify the web.xml file in the WAR deployment if your application requires advanced configuration for Coherence*Web. "Configure Coherence*Web" describes the parameters that can be configured for Web applications. The entire set of Coherence*Web parameters are described in Appendix A, "Coherence*Web Context Parameters."

  3. (Optional) Configure the WebLogic-generated HTTP session cookie parameters in the weblogic.xml or weblogic-application.xml file. See "Configure the Session Cookies".

  4. (Optional for testing; strongly suggested for production) Start a Cache Server Tier in a separate JVM from the one running WebLogic Server. See "Start a Cache Server".

  5. Determine the appropriate packaging based on your deployment requirements and follow the packaging instructions. Depending on your version of WebLogic Server, see "Configure Cluster Nodes".

2.2.1 Download Oracle Coherence

All of the files needed by Coherence*Web, including the coherence-web-spi.war file, are included in the Coherence distribution.

By default, Coherence 3.6 is installed with WebLogic Server 10.3.4. The default location of the Coherence directory is C:\Oracle\Middleware\coherence_3.6. If you are using WebLogic Server 10.3.4, you can download Coherence 3.7 and save it to your file system. Ensure that your applications reference coherence-web-spi.war, coherence.jar, and other library files that are in the Coherence 3.7 distribution.

Similarly, if you are working with WebLogic Server 10.3.3, you might already have Coherence installed in a coherence_3.5 directory. Again, you can download Coherence 3.7 and save it to your file system. Ensure that your applications reference coherence-web-spi.war, coherence.jar, and other library files that are in the Coherence 3.7 distribution.

If you are using WebLogic Server 10.3.2 or earlier, simply download the Coherence distribution to your file system.

Applying Required Software Patches

Some older versions of WebLogic Server require you to apply software patches before you can work with Coherence and Coherence*Web. Table 2-1 identifies the versions of WebLogic Server and their associated patches.

Table 2-1 Required Software Patches for WebLogic Server


WebLogic Server 9.2 MP1 WebLogic Server 9.2 MP3 WebLogic Server 10.3 WebLogic Server 11g (10.3.1 and later)

WebLogic Smart Update

Patch ID: 616G

Patch ID: LP7B

Patch ID: 6W2W

No Patch Required


You can obtain the patches either through the Smart Update utility in the WebLogic Server Administration Console or by going to My Oracle Support.

To use Smart Update, see the instructions in the WebLogic Server Administration Console. For production environments, you should review the Smart Update production installation notes.

To use My Oracle Support, go to the My Oracle Support web site.

https://support.oracle.com/

Select the Patches tab, click on the Simple Search link, and on the subsequent screen submit a search for a Patch Number/Name with the appropriate value (for example, 11399293). Download the patch zip file from the displayed results. Instructions for applying the Coherence patch are located in the README.txt included in the patch zip file.

2.2.2 Configure Coherence*Web

The Coherence*Web SPI provides a default configuration that should satisfy most Web applications. Table 2-2 describes only those Coherence*Web context parameters where the default for the SPI version is different from the non-SPI version. Table 2-3 describes the compatibility mode context parameter which is supplied by the SPI. For complete descriptions of all Coherence*Web parameters, see Appendix A, "Coherence*Web Context Parameters."

You can also configure the context parameters on the command line as system properties. The system properties have the same name as the context parameters, but the dash (-) is replaced with a period (.). For example, to declare a value for the context parameter coherence-enable-sessioncontext on the command line, enter it like this:

-Dcoherence.enable.sessioncontext=true

If both a system property and the equivalent context parameter are configured, the value from the system property is used.

Table 2-2 Coherence*Web Context Parameters Configured by the SPI

Parameter Name Description

coherence-application-name

Coherence*Web uses the value of this parameter to determine the name of the application that uses the ApplicationScopeController interface to scope attributes. The value for this parameter should be provided in the following format:

application name + ! + Web module name

The application name is the name of the application that uses the ApplicationScopeController interface and Web module name is the name of the Web module in which it appears.

For example, if you have an EAR file named test.ear and a Web-module named app1 defined in the EAR file, then the default value for the coherence-application-name parameter would be test!app1.

If this parameter is not configured, then Coherence*Web uses the name of the class loader instead. Also, if the parameter is not configured and the ApplicationScopeController interface is configured, then a warning is logged saying that the application name was not configured. See "Session Attribute Scoping" for more information.

coherence-reaperdaemon-assume-locality

This setting allows the session reaper to assume that the sessions that are stored on this node (for example, by a distributed cache service) are the only sessions that this node must check for expiration.

The default is false.

coherence-scopecontroller-class

This value specifies the class name of the optional com.tangosol.coherence.servlet.HttpSessionCollection$AttributeScopeController interface implementation.

Valid values include:

The default set by the Coherence*Web SPI is com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController.


Table 2-3 describes the coherence-session-weblogic-compatibility-mode context parameter which is specifically provided by the Coherence*Web SPI.

Table 2-3 Context Parameter Provided by the Coherence*Web SPI

Parameter Name Description

coherence-session-weblogic-compatibility-mode

This parameter is provided by the SPI version of Coherence*Web. If its value is set to true, it determines that a single session ID (with the cookie path set to "/") will map to a unique Coherence*Web session instance in each Web application. If it is false, then the standard behavior will apply: a single session ID will map to a single session instance using the Coherence*Web SPI in WebLogic Server. All other session persistence mechanisms in WebLogic use a single session ID in each Web application to refer to different session instances.

This parameter defaults to true unless the global scope controller is specified. If this controller is specified, then the parameter defaults to false.


Table 2-4 describes the coherence-factory-class context parameter. The default value, which is set by the Coherence*Web SPI, should not be changed.

Table 2-4 Context Parameter Value that Should Not be Changed

Parameter Name Description

coherence-factory-class

The fully qualified name of the class that implements the SessionHelper.Factory factory class. The Coherence*Web SPI sets the default value to weblogic.servlet.internal.session.WebLogicSPIFactory. This value should not be changed.


2.2.3 Configure the Session Cookies

If you are using Coherence*Web SPI, then WebLogic Server generates and parses the session cookie. In this case, any native Coherence*Web session cookie configuration parameters will be ignored. To configure the session cookies, use the WebLogic-generated HTTP session cookie parameters in the weblogic.xml or weblogic-application.xml files. Table 2-5 describes these parameters.

In this table, Updatable? indicates whether the value of the parameter can be changed while the server is running. Not applicable indicates that there is no corresponding Coherence session cookie parameter.

Table 2-5 WebLogic-Generated HTTP Session Cookie Parameters

This Session Cookie Parameter... Replaces this Coherence*Web Cookie Parameter Description

cookie-comment

Not applicable

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

The default is null.

Updatable? Yes

cookie-domain

coherence-session-cookie-domain

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.

The default is null.

Updatable? Yes

cookie-max-age-secs

coherence-session-max-age

Sets the life span of the session cookie, in seconds, after which it expires on the client. For more information about cookies, see "Using Sessions and Session Persistence" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

The default value is -1 (unlimited).

Updatable? Yes

cookie-name

coherence-session-cookie-name

Defines the session-tracking cookie name. Defaults to JSESSIONID if not set. You can set this to a more specific name for your application.

The default is JSESSIONID.

Updatable? Yes

cookie-path

coherence-session-cookie-path

Defines the session-tracking cookie path.

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

The default is null.

Updatable? Yes

cookie-secure

coherence-session-cookie-secure

Tells the browser that the cookie can be returned only over an HTTPS connection. This ensures that the cookie ID is secure and should be used only on Web sites that use HTTPS. Session cookies sent over HTTP will not work if this feature is enabled.

Disable the url-rewriting-enabled element if you intend to use this feature.

WebLogic Server generates the session cookie.

The default is false.

Updatable? Yes

cookies-enabled

coherence-session-cookies-enabled

Enables use of session cookies by default and is recommended, but you can disable them by setting this property to false. You might turn this option off for testing purposes.

The default is true.

Updatable? Yes

debug-enabled

Not applicable

Enables the debugging feature for HTTP sessions. Support it by enabling HttpSessionDebug logging and the WebLogic Server trace logger.

The default value is false.

Updatable? Yes

encode-session-id-in-query-params

Not applicable

Is set to true if the latest servlet specification requires containers to encode the session ID in path parameters. Certain Web servers do not work well with path parameters. In such cases, the encode-session-id-in-query-params element should be set to true.

WebLogic Server generates the HTTP response.

The default value is false.

Updatable? Yes

http-proxy-caching-of-cookies

Not applicable

When set to false, WebLogic Server adds the following header and response to indicate that the proxy caches are not caching the cookies:“Cache-control: no-cache=set-cookie

WebLogic Server generates the HTTP response.

The default value is true.

Updatable? Yes

id-length

coherence-session-id-length

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 Wireless Application Protocol (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 rewriting. 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.

The default is 52.

Updatable? No

invalidation-interval-secs

Not applicable

Sets the time, in seconds, that Coherence*Web waits between checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Use this element to tune WebLogic Server for best performance on high traffic sites.

The default is 60.

Updatable? No

timeout-secs

Not applicable

Sets the time, in seconds, that Coherence*Web waits before timing out a session.

On busy sites, you can tune your application by adjusting the timeout of sessions. While you want to give a browser client every opportunity to finish a session, you do not want to tie up the server needlessly if the user has left the site or otherwise abandoned the session.

This element can be overridden by the session-timeout element (defined in minutes) in web.xml.

The default is 3600 seconds.

Updatable? No

tracking-enabled

Not applicable

Enables session tracking between HTTP requests.

WebLogic Server generates the HTTP response.

The default is true.

Updatable? No

url-rewriting-enabled

coherence-session-urlencode-enabled

Enables URL rewriting, which encodes the session ID into the URL and provides session tracking if cookies are disabled in the browser and the encodeURL or encodeRedirectedURL methods are used when writing out URLs. For more information, see:

http://www.jguru.com/faq/view.jsp?EID=1045

WebLogic Server generates the HTTP response.

The default is true.

Updatable? Yes


2.2.4 Start a Cache Server

A Coherence cache server (also known as a data node) is responsible for storing and managing all cached data. It can be either a dedicated JVM or run within a WebLogic Server instance. The senior node (which is the first node) in a Coherence data cluster can take several seconds to start; the startup time required by subsequent nodes is minimal.

Whether you start the cache servers first or the WebLogic Server instances first, depends on the server topology you are employing:

  • If you are using an In-Process topology (all storage-enabled WebLogic Server instances), then it does not matter if you start the cache servers first or WebLogic Server instances first.

  • If you are using an Out-of-Process topology (storage-disabled WebLogic Server instances and standalone Coherence cache servers), then start the cache servers first, followed by the WebLogic Server instances. This will ensure that there is minimal (measured in milliseconds) startup time for applications using Coherence. Any additional Web applications that use Coherence are guaranteed not to be the senior data member, so they will have minimal impact on WebLogic Server startup.

    In this topology, if you do not start the cache servers first, Coherence will respond with an error message similar to the following:

    No storage-enabled nodes exist for service ... 
    

2.2.4.1 To Start a Standalone Coherence Data Node

Follow these steps to start a standalone Coherence data node:

  1. Create a script for starting a Coherence data node. The following is a very simple example of a script that starts a storage-enabled cache server. This example assumes that you are using a Sun JVM. See "JVM Tuning" in Developer's Guide for Oracle Coherence for more information.

    java -server -Xms512m -Xmx512m 
    -cp <Coherence installation dir>/lib/coherence-web.jar:<Coherence installation dir>/lib/coherence.jar -Dtangosol.coherence.management.remote=true 
    -Dtangosol.coherence.cacheconfig=cache_configuration_file 
    -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
    

    You must include coherence-web.jar and coherence.jar on the classpath. The cache_configuration_file represents the absolute path to the cache configuration file on your file system. For Coherence*Web, this will be the session-cache-config.xml file. Note that the cache configuration defined for the cache server must match the cache configuration defined for the application servers which run on the same Coherence cluster.

    If you have additional Coherence caches running on Coherence*Web, then you must merge the cache configuration information (typically defined in the coherence-cache-config.xml file) with the session configuration contained in the session-cache-config.xml file. The cache and session configuration must be consistent across WebLogic Server and Coherence cache servers.

    For more information on merging these files, see "Merging Coherence Cache and Session Information" in Integration Guide for Oracle Coherence.

  2. Start one or more Coherence data nodes using the script described in the previous step.

2.2.4.2 To Start a Storage-Enabled or -Disabled WebLogic Server Instance

By default, a Coherence*Web-enabled WebLogic Server instance starts in storage-disabled mode. To start the WebLogic Server instance in storage-enabled mode, follow these steps:

  1. Create a script for starting a Coherence data node. This can be similar to the script described in the previous section.

  2. Include the command-line property to enable local storage, -Dtangosol.coherence.session.localstorage=true, in the server startup command.

For more information about working with WebLogic Server through the command line, see "weblogic.Server Command-Line Reference" in Oracle Fusion Middleware Command Reference for Oracle WebLogic Server.

2.2.5 Configure Cluster Nodes

The session management provided by Coherence*Web can have application server-scope, EAR-scope, or WAR-scope. Like Coherence clusters, scoping of Coherence*Web depends on the placement of the coherence.jar file in the classloader's hierarchy. You can find detailed information about each of the scopes in "Cluster Node Isolation".

WebLogic Server, versions 10.3.3 and later, provides several features, collectively known as ActiveCache, that allow your applications to more easily interact with the Coherence cache. For a complete discussion of these features see the Using ActiveCache guide.

Some earlier versions of WebLogic Server (such as version 10.3.1 and earlier) might need a software patch to use Coherence and Coherence*Web. To find out if your version of WebLogic Server requires a patch, see "Applying Required Software Patches".

The following sections describe how you can configure the different cluster node configurations to run Coherence*Web:

Note:

Consider the use of the application server-scoped cluster configuration very carefully. Do not use it in environments where application interaction is unknown or unpredictable.

An example of such an environment might 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—the likelihood of collisions between namespaces for caches, services, and other configuration settings is quite high and could 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.

2.2.5.1 Configuring Application Server-Scoped Cluster Nodes

If you are adding Coherence*Web for session management to a Coherence cluster, follow these steps:

  1. Edit your WebLogic Server system classpath to include the coherence.jar file or copy the JAR file to your $DOMAIN_HOME/lib directory.

  2. Use the WebLogic Server Administration Console or the command line to deploy coherence-web-spi.war file as a shared library.

  3. Enable Coherence*Web in your Web application.

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

    Example 2-1 Library Reference for a WAR File

    <weblogic-web-app>
      ...
        <library-ref>
          <library-name>coherence-web-spi</library-name>
        </library-ref>
      ...
    </weblogic-web-app>
    

2.2.5.2 Configuring EAR-Scoped Cluster Nodes

If you are using Coherence*Web for session management in EAR-scoped cluster nodes, and your applications are running on WebLogic Server 10.3.2 or earlier, follow these steps:

  1. Use the WebLogic Server Administration Console to deploy the coherence.jar and coherence-web-spi.war files as shared libraries to all of the target servers where the application will be deployed. See "Install a Java EE Library" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help for more information.

    If you receive an error when you attempt to deploy coherence.jar through the WebLogic Server Administration Console, you can use WLST commands. See Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help for more information.

  2. Reference the coherence.jar file in the weblogic-application.xml file. Store the file in the EAR's META-INF directory.

    Example 2-2 illustrates a weblogic-application.xml file.

    Example 2-2 Coherence JAR Referenced in weblogic-application.xml

    <weblogic-application ...>
    ...
          <library-ref>
               <library-name>coherence</library-name>
          </library-ref>
    ...
    </weblogic-application>
    
  3. Reference the coherence-web-spi.war file in the weblogic.xml file.

    Example 2-3 illustrates a weblogic.xml file.

    Example 2-3 Coherence Web SPI WAR Referenced in weblogic.xml

    <weblogic-web-app>
    ...
          <library-ref>
               <library-name>coherence-web-spi</library-name>
         </library-ref>
    ...
    </weblogic-web-app>
    

2.2.5.3 Configuring WAR-Scoped Cluster Nodes

If you are using Coherence*Web for session management in WAR-scoped cluster nodes, follow these steps:

  1. Use the WebLogic Server Administration Console or the command line to deploy the coherence-web-spi.war file as a shared library to all of the target servers where the application will be deployed. See "Install a Java EE Library" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.

  2. Add the coherence.jar file to the application. You can do this in any of the following ways:

    • Import coherence.jar file as an optional package in the manifest.mf file of each module that will be using Coherence. Example 2-4 illustrates a manifest.mf file.

      Example 2-4 Manifest File that References the Coherence JAR File

      Manifest-Version: 1.0
      Extension-List: coherence
      coherence-Extension-Name: coherence
      
    • Copy the coherence.jar file to the WAR file's WEB-INF/lib directory.

  3. If you deploy the coherence-web-spi.war file as a shared library, you must also create a shared library reference by adding the stanza illustrated in Example 2-5 to the weblogic.xml file in the WAR file's WEB-INF directory.

    Example 2-5 Library Reference for a Web Application

    <weblogic-web-app ... >
         ...
          <library-ref>
               <library-name>coherence-web-spi</library-name>
         </library-ref>
         ...
    <weblogic-web-app>
    

2.3 Scoping the Session Cookie Path

WebLogic Server and Coherence*Web handle session scoping and the session lifecycle in different ways. This can impact your decision to implement a single sign-on (SSO) strategy for your applications.

By default, WebLogic Server uses the same session ID in every Web application for a given client, and sets the session cookie path to a slash (/). This is a requirement of the WebLogic Server default thin SSO implementation, which is enabled by default. By generating a session cookie with a path of "/", clients always return the same session ID in every request to the server. In WebLogic Server, a single session ID can be mapped to multiple session objects. Each Web application will have a different session object instance even though the session ID is identical (unless session sharing is enabled).

In contrast, Coherence*Web maps a session ID to a single session instance. This means that the behavior of having multiple session instances mapped to the same ID is not replicated by default if an application uses Coherence*Web. Because the session cookie is mapped to "/" by default, a single Coherence*Web session is shared across all Web applications. The default configuration in Coherence*Web is that all session attributes are scoped to a Web application. For most purposes, this single session approach is transparent. The major difference of having a single session across all Web applications is the impact of session invalidation. If Coherence*Web is enabled and you invalidate a session in one Web application, then you invalidate that session in all Web applications that use that session instance. If your Web applications do not use thin SSO, then you can avoid this issue by scoping the session cookie to the Web application path.

Therefore, you have the following options regarding SSO:

One advantage of enabling thin SSO with Coherence*Web is that it will work across all Web applications that are using the same Coherence cluster for Coherence*Web. The Coherence cluster is completely independent from the WebLogic Server cluster. The thin SSO functionality can even span multiple domains by enabling cross-domain trust in the WebLogic Server security layer.

2.4 Sharing Coherence*Web Sessions with Other Application Servers

If you are running Coherence*Web on WebLogic Server and on other application servers within a single cluster, then the session cookies created by WebLogic Server will not be decoded correctly by Coherence*Web on the other servers. This is because WebLogic Server adds a session affinity suffix to the cookie which is not part of the session ID stored in Coherence*Web. The other application servers must remove the WebLogic session affinity suffix from the session cookie value for Coherence*Web to be able to retrieve the session from the Coherence cache.

To strip the WebLogic session affinity suffix from the session cookie, add the coherence-session-affinity-token context parameter to the web.xml file used in the other application servers. Set the parameter value to an exclamation point (!), as illustrated in Example 2-6. The session affinity suffix will be removed from the session cookie when it is processed by the other application server.

Example 2-6 Removing Session Affinity Suffix

...
<context-param>
  <param-name>coherence-session-affinity-token</param-name>
  <param-value>!</param-value>
</context-param>
...

See Appendix A, "Coherence*Web Context Parameters" for more information on the coherence-session-affinity-token context parameter.