2 Using Coherence*Web with WebLogic Server

The Coherence*Web module for WebLogic Server simplifies session state persistence deployment, configuration, and management. This chapter provides an overview of Managed Coherence Servers and the Grid Archive (GAR) format for packaging Coherence applications. A detailed discussion of Managed Coherence Servers and the GAR format is beyond the scope of this document. See Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server.

This chapter includes the following sections:

• Overview of Coherence*Web
  Coherence*Web provides session state persistence and management. It is a session management module that uses Coherence caches for storing and managing session data.
• Overview of Managed Coherence Servers
  Oracle WebLogic Server and Coherence have defined Managed Coherence Servers which provide Coherence applications with the same benefits as other Java EE applications that are hosted on WebLogic Server.
• Configuring and Deploying Coherence*Web: Main Steps
  You can configure and deploy Coherence*Web with applications running on WebLogic Server.
• Coherence MBean Attributes for Coherence*Web
  WebLogic Server defines a cluster MBean (weblogic.management.configuration.ClusterMBean) which represents a cluster in the domain.
• Enabling the Coherence Session Cache in Weblogic Server Administration Console
  The Coherence Web Local Storage Enabled and Coherence Web Federated Storage Enabled checkboxes in the WebLogic Server Administration Console can be used to indicate whether the cluster is acting as a storage tier for Coherence*Web.
• Using a Custom Session Cache Configuration File
  Custom session cache configuration files must be packaged in a GAR file for deployment.
• Scoping the Session Cookie Path
  WebLogic Server and Coherence*Web handle session scoping and the session lifecycle in different ways.
• Updating the Session ID
  When a user successfully authenticates a protected resource, the session ID is changed for security purposes.
• 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.

Overview of Coherence*Web

Coherence*Web provides session state persistence and management. It is a session management module that uses Coherence caches for storing and managing session data.

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:

• Your application works with large HTTP session state objects

• You run into memory constraints, due to storing HTTP session object data

• You want to offload HTTP session storage to an existing Coherence cluster

• You want to share session state across enterprise applications and Web modules

The classes that define the Coherence*Web are contained in the coherence-web.jar file. To use the functionality provided by Coherence*Web, the coherence.jar classes must also be available to the Web application. Both of these libraries are on the WebLogic Server system classpath and are automatically loaded at runtime. The coherence-web.jar loads application classes with the appropriate classloader in WebLogic Server.

Note:

WebLogic Server and Coherence must be on the same versions when using Coherence*Web.

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

You can create your own custom session cache configuration by packaging a file named session-cache-config.xml in your Web application. See, Using a Custom Session Cache Configuration File.

When Coherence*Web is started on WebLogic Server, it first looks for a file named session-cache-config.xml. For example, the file can be placed in a WAR file's WEB-INF/classes directory, or packaged in a JAR file and placed in an EAR file's APP-INF/lib directory. If no custom session cache configuration XML resource is found, then it will use the default-session-cache-config.xml file packaged in coherence-web.jar.

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

• Coherence*Web for WebLogic Server is configured with local-storage disabled. The server will serve requests and will not be used to host data. 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.

All Coherence*Web-enabled applications running on WebLogic Server have application server-scope. In this configuration, all deployed applications become part of one Coherence node. See Cluster Node Isolation.

Coherence*Web provides several session locking modes to control concurrent access of sessions. Both Coherence*Web employs Last Write Wins locking by default. See Session Locking Modes.

By itself, Coherence*Web 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

Overview of Managed Coherence Servers

Oracle WebLogic Server and Coherence have defined Managed Coherence Servers which provide Coherence applications with the same benefits as other Java EE applications that are hosted on WebLogic Server.

The following are the examples of Coherence applications functioning similar to Java EE applications:

• Coherence applications can be deployed in a manner similar to other Java EE applications.

• Coherence applications in the grid can be managed by using WebLogic Server Console and WLST.

• Coherence clusters can be configured by using WebLogic configuration.

• Coherence Grid Archives can be integrated into Enterprise Archives (EAR files).

• Coherence applications can integrate with existing Coherence-based functionality.

Note:

Using multiple Coherence clusters in a single WebLogic Server domain is not recommended.

For more information on Managed Coherence Servers, see Creating Coherence Applications for WebLogic Server in Developing Oracle Coherence Applications for Oracle WebLogic Server.

Configuring and Deploying Coherence*Web: Main Steps

You can configure and deploy Coherence*Web with applications running on WebLogic Server.

This section includes the following topics:

• Summary of Configuring and Deploying Coherence*Web
  
• Installing WebLogic Server and Oracle Coherence
  
• Configure Coherence*Web
  
• Configure the Session Cookies
  
• Start a Cache Server
  
• Configure Coherence*Web Storage Mode
  
• Deploying Applications to WebLogic Server
  

Summary of Configuring and Deploying Coherence*Web

The following steps summarize how to prepare your deployments to use Coherence*Web with applications running on WebLogic Server:

1. Install WebLogic Server and Oracle Coherence. See Installing WebLogic Server and Oracle Coherence.

2. (Optional) Modify the web.xml file in the 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 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. Set the Coherence*Web storage mode. See Configure Coherence*Web Storage Mode.

6. Deploy the application to WebLogic Server. See Deploying Applications to WebLogic Server.

Installing WebLogic Server and Oracle Coherence

WebLogic Server is installed by executing its installer. The installer provides the full installation and allows you to individually select the components to install (bits, examples, Javadoc, and so on). The installer supports both a graphical mode using the Oracle Universal Installer (OUI) and a silent mode. Installing Coherence is an option in the WebLogic Server installer.

WebLogic Server is always installed to the ORACLE_HOME/wlserver directory; Coherence is always installed to the ORACLE_HOME/coherence directory.

See Installing and Configuring Oracle WebLogic Server and Coherence.

Configure Coherence*Web

Coherence*Web provides a default configuration that should satisfy most Web applications. Table 2-1 describes the context parameters configured by Coherence*Web. Table 2-2 describes the compatibility mode context parameter. For complete descriptions of all Coherence*Web parameters, see 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-1 Context Parameters Configured by Coherence*Web

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: com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController (default) com.tangosol.coherence.servlet.AbstractHttpSessionCollection$GlobalScopeController The default set by Coherence*Web is com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController.

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

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

Parameter Name

Description

coherence-session-weblogic-compatibility-mode

This parameter is provided by 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 Coherence*Web 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-3 describes the coherence-factory-class context parameter. The default value, which is set by Coherence*Web, should not be changed.

Table 2-3 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. Coherence*Web sets the default value to weblogic.servlet.internal.session.WebLogicSPIFactory. This value should not be changed.

Configure the Session Cookies

If you are using Coherence*Web, 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-4 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-4 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.example.com returns cookies to any server in the *.example.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. 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. See URL Rewriting and Wireless Access Protocol in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server The default is 52. Updatable? No
invalidation-interval-secs	coherence-reaperdaemon-cycle-seconds	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

Note:

The default for WebLogic HTTP Session parameter invalidation-interval-secs of 60 seconds overrides the Coherence*Web Session Cookie parameter coherence-reaperdaemon-cycle-seconds default of 5 minutes.

Start a Cache Server

A Coherence cache server is responsible for storing and managing all cached data. Coherence is integrated within WebLogic Server as a container subsystem. The use of a container aligns the lifecycle of a Coherence cluster member with the lifecycle of a managed server: starting or stopping a managed server JVM starts and stops a Coherence cluster member. Managed servers that are cluster members are referred to as managed Coherence servers.

Coherence clusters are different than WebLogic Server clusters. They use different clustering protocols and are configured separately. Multiple WebLogic Server clusters can be associated with a Coherence cluster and a WebLogic Server domain should only contain a single Coherence cluster. Managed Coherence servers can be explicitly associated with a Coherence cluster or they can be associated with a WebLogic Server cluster that is associated with a Coherence cluster. WebLogic Server managed servers that are members of a Coherence cluster and are storage-enabled, act as cache servers. See Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server.

You can start a Coherence cache server or cluster either from the WebLogic Server Administration Console or from the command line, as described in the following sections.

• Starting a Coherence Cache Server from WebLogic Server Administration Console
  
• Starting a Coherence Cache Server from the Command Line
  

Starting a Coherence Cache Server from WebLogic Server Administration Console

Using the WebLogic Server Administration Console, you can enable storage for each WebLogic Server that is a member of a Coherence cluster. The Coherence session caches have a separate flag for enabling storage. See Enabling the Coherence Session Cache in Weblogic Server Administration Console.

Note:

If your managed server is a member of a Coherence cluster and is using Coherence*Web, then you can enable session storage by adding the -Dcoherence.session.localstorage=true system property to the startup command.

Coherence session caches automatically start with the WebLogic Server cluster.

The following steps summarize how to start a Coherence cluster in the WebLogic Server Administration Console.

1. Configure the Coherence Cluster.

   See Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server.

2. Configure WebLogic Servers and clusters that will be associated with the Coherence cluster.

   See Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server.

3. Enable Coherence*Web for the selected WebLogic Servers or clusters.

   See Enabling the Coherence Session Cache in Weblogic Server Administration Console.

Starting a Coherence Cache Server from the Command Line

Instead of using the WebLogic Server Administration Console, there may be situations when you might need to start a Coherence cache server or cluster from the command line. You can start the Coherence cache server from the command line either in standalone mode, or as part of a WebLogic Server instance.

This section includes the following topics:

• To Start a Standalone Coherence Cache Server
  
• To Start a Storage-Enabled or -Disabled WebLogic Server Instance
  

To Start a Standalone Coherence Cache Server

Follow these steps to start a standalone Coherence cache server:

1. Create a script for starting a Coherence cache server. The following is a simple example of a script that creates and starts a storage-enabled cache server. This example assumes that you are using a Sun JVM. See JVM Tuning in Developing Applications with Oracle Coherence for more information.

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

   You must include coherence-web.jar and coherence.jar on the classpath. The variable session_cache_configuration_file represents the absolute path to the cache configuration file on your file system. For Coherence*Web, the default session cache configuration file is named default-session-cache-config.xml. 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 your application uses additional Coherence caches, then you must merge the cache configuration information with a customized session cache configuration file. This customized session cache configuration file, typically named session-cache-config.xml, should contain the contents of default-session-cache-config.xml file and the additional caches used by your application.

   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 Integrating Oracle Coherence.

   The variable Coherence_cluster_name represents the name of the Coherence cluster. A cluster name check has been added to 10.3.6 and later versions of WebLogic Server. The coherence.cluster property must be added to the cache server because you are declaring the cluster name in the WebLogic Server application. If the Coherence servers are started in standalone mode, they must pass this property, otherwise the cluster will not form between the WLS servers and the standalone cache server.

2. Start one or more Coherence cache servers using the script described in the previous step.

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 cache server. This can be similar to the script described in the previous section.
2. Include the command-line property to enable local storage, -Dcoherence.session.localstorage=true, in the server startup command. The WebLogic Server instance will start with Coherence*Web-enabled and local storage enabled.

   To start a Coherence*Web-enabled WebLogic Server instance, omit this system property. Local storage will be disabled by default.

See weblogic.Server Command-Line Reference in Command Reference for Oracle WebLogic Server.

Configure Coherence*Web Storage Mode

You can enable Coherence*Web session storage by specifying coherence-web as the value of the persistent-store-type attribute in the weblogic.xml session configuration. This configuration provides application server-level cluster node scoping for web applications deployed on WebLogic Server. No shared libraries need to be deployed or depended upon.

Coherence*Web is initialized only when a web application that requires session persistence is started in the WebLogic Server instance.

Example 2-1 illustrates a sample weblogic.xml file where coherence-web is the value of the persistent-store-type attribute.

Example 2-1 Coherence Web Storage Mode in weblogic.xml

<weblogic-web-app>
  ...
<session-descriptor>   
      <persistent-store-type>coherence-web</persistent-store-type>
</session-descriptor>  
  ...
</weblogic-web-app>

Deploying Applications to WebLogic Server

If you are using the default session cache configuration file with your web application, then you can package and deploy it like any other Java EE application. However, if you are using a custom session cache configuration file, then you must package and deploy the application in a GAR file.

GAR files deploy like any other Java EE application, except that you create a Coherence tier and nodes belonging to the tier. You can configure and deploy a standalone GAR or an embedded GAR.

See Deploying Coherence Applications to WebLogic Server in Administering Oracle Coherence and Creating Coherence Applications for WebLogic Server in Developing Oracle Coherence Applications for Oracle WebLogic Server.

Coherence MBean Attributes for Coherence*Web

WebLogic Server defines a cluster MBean (weblogic.management.configuration.ClusterMBean) which represents a cluster in the domain.

The cluster MBean defines a number of attributes, operations, and MBeans related to the management of the cluster. Among the MBeans defined by the cluster MBean are the CoherenceMemberConfigMBean and the CoherenceTierMBean MBeans.

The CoherenceMemberConfigMBean and the CoherenceTierMBean MBeans each define an isCoherenceWebLocalStorageEnabled attribute that indicates whether a cluster or member is acting as a storage tier for Coherence*Web. This attribute is defined in Table 2-5.

Table 2-5 Coherence MBean Attribute for Coherence*Web

Attribute

Description

isCoherenceWebLocalStorageEnabled

If this attribute is set to true in CoherenceTierMBean, it indicates that a cluster is acting as a storage tier for Coherence*Web. Coherence*Web cache services will start with storage enabled when the server starts. When deploying a Coherence*Web-enabled application, there must be a running WebLogic cluster in the domain which has this attribute enabled. If this attribute is set to true in CoherenceMemberConfigMBean, it indicates that this node is acting as a storage node for Coherence*Web. Coherence*Web cache services will start with storage enabled when the server starts. When deploying a Coherence*Web-enabled application, there must be a running WebLogic cluster in the domain which has this attribute enabled. Default: false

Enabling the Coherence Session Cache in Weblogic Server Administration Console

The Coherence Web Local Storage Enabled and Coherence Web Federated Storage Enabled checkboxes in the WebLogic Server Administration Console can be used to indicate whether the cluster is acting as a storage tier for Coherence*Web.

When selecting the federated storage option, the default federation topology which is configured is used. See Configuring Cache Federation in Administering Clusters for Oracle WebLogic Server and Federated Session Caches.

1. Select Environment, then Clusters in the Domain Structure Window.
2. Select a defined cluster in the Clusters table.
3. Select Configuration tab then the Coherence tab in the Settings for cluster page.

Figure 2-1 illustrates the checkboxes in the WebLogic Server Administration Console.

Figure 2-1 Coherence Web Local Storage Enabled Checkbox

Description of "Figure 2-1 Coherence Web Local Storage Enabled Checkbox"

Using a Custom Session Cache Configuration File

Custom session cache configuration files must be packaged in a GAR file for deployment.

The coherence-web.jar file contains a default-session-cache-config.xml cache configuration file which should be sufficient for most applications. However, if you are working with technologies such as Coherence*Extend or cluster Federation, or if you have WebLogic Server nodes that are to act as storage-enabled cache servers with a custom session cache configuration, then you must provide a custom session cache configuration file. Custom session cache configuration files must be packaged in a GAR file for deployment.

To use a custom session cache configuration file on WebLogic Server and package it in a GAR file, follow these steps for web applications and for the WebLogic Server nodes acting as cache servers:

For web applications using Coherence*Web:

1. If you are using a custom session cache configuration file (which should be named session-cache-config.xml), then package it in your web application:

   • For a WAR file, place the session cache configuration file in the WEB-INF/classes folder

   • For an EAR file, package the session cache configuration file in a JAR file and place it in the shared library (the APP-INF/lib folder) in an EAR file

   Note that you can customize the session cache configuration file name, but then you must provide the new file name as the value of the coherence-cache-configuration-path context parameter in the web.xml file.

2. If you do not want the WebLogic Server cluster members running the Coherence*Web application to act as a cache server, then ensure that the Coherence Web Local Storage Enabled checkbox in the WebLogic Server Administration Console "Settings for cluster" page is not selected for the cluster members. This will cause the custom session cache configuration file to be read.

For WebLogic Server nodes acting as cache servers:

1. If you are using a custom session cache configuration file, then construct a GAR file containing the file and a coherence-application.xml file. The GAR file has the following structure:

   my.gar
   session-cache-config.xml
   META-INF 
     coherence-application.xml
     MANIFEST.MF
   

   See Packaging Coherence Applications for WebLogic Server in Administering Oracle Coherence and Creating Coherence Applications for Oracle WebLogic Server in Developing Oracle Coherence Applications for Oracle WebLogic Server.

   1. Create the custom session cache configuration file and name it session-cache-config.xml.

      If you are deploying a GAR file, set the local-storage parameter in the custom session-cache-config.xml file to true, to configure all caches to start with storage enabled, for example:

      <local-storage>true</local-storage>

      Note:

      The local-storage parameter specifies whether a cluster node contributes storage to the cluster. In WebLogic Server, the local-storage parameter does not enable storage in Coherence*Web for WebLogic Server members that have a GAR file deployed to them.

   2. Create a coherence-application.xml file. In the file, use the cache-configuration-ref parameter to reference your custom session-cache-config.xml file, for example:

      <?xml version="1.0"?>
      <coherence-application>
         xmlns="http://xmlns.oracle.com/weblogic/coherence-application">
      <cache-configuration-ref>session-cache-config.xml</cache-configuration-ref>
      </coherence-application>
      

2. Deploy the GAR file to the WebLogic Server cluster that is to act as the storage-enabled Coherence cluster members.

   Note that storage must be enabled in either of the following ways:

   • Enable storage in the session-cache-config.xml file (see Step 1a).

   • Enable storage in the server itself either by selecting the Coherence Web Local Storage Enabled checkbox in the WebLogic Server Administration Console or by setting the JVM argument coherence.session.localstorage to true.

   See Deploying Coherence Applications To a WebLogic Server Domain in Administering Oracle Coherence and Deploying Coherence Applications in WebLogic Server in Developing Oracle Coherence Applications for Oracle WebLogic Server.

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

• Enable WebLogic Server session compatibly mode. This configuration is set with the coherence-session-weblogic-compatibility-mode parameter and mirrors all of the native WebLogic Server session persistence types: memory (single-server, non-replicated), file system persistence, JDBC persistence, cookie-based session persistence, and in-memory replication (across a cluster). By default, this mode is enabled. See Using Sessions and Session Persistence in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

• Enable thin SSO functionality. Clients will use a single session across all Web applications. This means that the session life cycle will be inconsistent with all other session persistence types.

• Disable the thin SSO functionality by scoping the session cookie path to the Web application context path. This will allow the session life cycle to be consistent with all other session persistence types.

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.

Updating the Session ID

When a user successfully authenticates a protected resource, the session ID is changed for security purposes.

In previous releases of WebLogic Server, a new session would be created, all of the session attributes from the old session would be copied into the new session, and then the old session would be invalidated. This would trigger the session listeners (if any were registered), so session lifecycle and session attribute listeners would be executed.

The current release of WebLogic Server implements the HttpServletRequest.changeSessionId method from the Java Servlet 3.1 Specification. The implementation of the changeSessionId method allows the actual session ID to be updated. This means that no session lifecycle events will be triggered and no listeners will be executed. Most users should not notice any changes in the behavior of their applications.

For more information on the HttpServletRequest.changeSessionId method, see the Java Servlet 3.1 Specification and Javadoc available from this URL:

http://jcp.org/en/jsr/detail?id=340

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-2. The session affinity suffix will be removed from the session cookie when it is processed by the other application server.

Example 2-2 Removing Session Affinity Suffix

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

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