2 Using Coherence*Web with WebLogic Server

This chapter describes how to configure and deploy Coherence*Web, the session state persistence and management module, for use with WebLogic Server. The functionality that allows Coherence*Web to be used with this application server is contained in the Coherence*Web.

This chapter also provides an overview of Managed Coherence Servers and Grid Archive (GAR) format for packaging Coherence applications for the grid. A detailed discussion of Managed Coherence Servers and the GAR format is beyond the scope of this document. For more information, see Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server.

This chapter contains the following sections:

Overview of Coherence*Web
Overview of Managed Coherence Servers
Configuring and Deploying Coherence*Web: Main Steps
Coherence MBean Attributes for Coherence*Web
Scoping the Session Cookie Path
Updating the Session ID
Sharing Coherence*Web Sessions with Other Application Servers
WebLogic Server and Coherence: Compatibility

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

2.1 Overview of Coherence*Web

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 files can be found in the coherence\lib directory.

In WebLogic Server 12c (12.1.3) and later, the coherence-web.jar and the coherence.jar files appear on the WebLogic Server system classpath. The coherence-web.jar will load application classes with the appropriate classloader in WebLogic Server. This means that you do not have to include the coherence.jar or coherence-web.jar files in the web application's classpath.

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. For more information 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 the 12c (12.1.3) release of WebLogic Server have application server-scope. In this configuration, all deployed applications become part of one Coherence node. See "Cluster Node Isolation" for more information about cluster node scope.

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" for more information about 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

2.2 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, for example:

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 Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server.

2.3 Configuring and Deploying Coherence*Web: Main Steps

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

Install WebLogic Server and Oracle Coherence. See "Installing WebLogic Server and Oracle Coherence".
(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 Appendix A, "Coherence*Web Context Parameters."
(Optional) Configure the WebLogic-generated HTTP session cookie parameters in the weblogic.xml or weblogic-application.xml file. See "Configure the Session Cookies".
(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".
Set the Coherence*Web storage mode. See "Configure Coherence*Web Storage Mode".
Deploy the application to WebLogic Server. See "Deploying Applications to WebLogic Server".

2.3.1 Installing WebLogic Server and Oracle Coherence

WebLogic Server is installed by executing the fmw_version_wls.jar. This installer provides the full install and allows you to individually select the components to install (bits, examples, Javadoc). 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.

Use the java command to run the installer on the target computer, for example:

java -jar fmw_version_wls.jar

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

For detailed instructions on installing WebLogic Server, see Installing Oracle WebLogic Server.

2.3.2 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 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-1 Context Parameters Configured by Coherence*Web

Parameter Name Description

Parameter Name	Description
`coherence-application-name`	CoherenceWeb 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 CoherenceWeb 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`.

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

Parameter Name	Description
`coherence-session-weblogic-compatibility-mode`	This parameter is provided by CoherenceWeb. 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 CoherenceWeb 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`.

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.

2.3.3 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`.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.3.4 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 can contain only a single Coherence cluster. Managed servers that are configured as Coherence cluster members are referred to as managed Coherence servers.

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.

For more information on Coherence clusters in a WebLogic server environment, see "Configuring and Managing Coherence Clusters" in Administering Clusters for Oracle WebLogic Server. For more information on Coherence applications in a WebLogic Server environment, see Oracle Fusion Middleware Developing Oracle Coherence Applications 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

2.3.4.1 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. For more information on this flag, 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 -Dtangosol.coherence.session.localstorage=true system property to the startup command.

Coherence session caches automatically start with the WebLogic Server cluster. For an example of working with Coherence cache servers in the WebLogic Server Administration Console, see "Caching Sessions with Managed Coherence Servers" in Oracle Fusion Middleware Tutorial for Oracle Coherence.

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

Configure the Coherence Cluster.

For detailed information, see "Configuring and Managing Coherence Clusters" in Administering Clusters for Oracle WebLogic Server.
Configure WebLogic Servers and clusters that will be associated with the Coherence cluster.

For detailed information, see "Configuring and Managing Coherence Clusters" in Administering Clusters for Oracle WebLogic Server.
Enable Coherence*Web for the selected WebLogic Servers or clusters.

For detailed information, see "Enabling the Coherence Session Cache in Weblogic Server Administration Console".

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

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

2.3.4.2.1 To Start a Standalone Coherence Cache Server

Follow these steps to start a standalone Coherence cache server:

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 Oracle Fusion Middleware 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 -Dtangosol.coherence.management.remote=true 
-Dtangosol.coherence.cacheconfig=session_cache_configuration_file 
-Dtangosol.coherence.session.localstorage=true -Dtangosol.coherence.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 Oracle Fusion Middleware 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 tangosol.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.
Start one or more Coherence cache servers using the script described in the previous step.

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

Create a script for starting a Coherence cache server. This can be similar to the script described in the previous section.
Include the command-line property to enable local storage, -Dtangosol.coherence.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.

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

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

For information about configuring and deploying standalone GAR files and embedded GAR files, see "Deploying Coherence Applications to WebLogic Server" in Oracle Fusion Middleware Administering Oracle Coherence and "Creating Coherence Applications for WebLogic Server" in Developing Oracle Coherence Applications for Oracle WebLogic Server.

2.4 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

Attribute	Description
isCoherenceWebLocalStorageEnabled	If this attribute is set to `true` in `CoherenceTierMBean`, it indicates that a cluster is acting as a storage tier for CoherenceWeb. CoherenceWeb cache services will start with storage enabled when the server starts. When deploying a CoherenceWeb-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 CoherenceWeb. CoherenceWeb cache services will start with storage enabled when the server starts. When deploying a CoherenceWeb-enabled application, there must be a running WebLogic cluster in the domain which has this attribute enabled. Default: `false`

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

2.4.1 Enabling the Coherence Session Cache in Weblogic Server Administration Console

The Coherence Web Local Storage Enabled checkbox in the WebLogic Server Administration Console corresponds to the isCoherenceWebLocalStorageEnabled attribute described in the previous section. The checkbox indicates whether the cluster is acting as a storage tier for Coherence*Web. To navigate to this checkbox:

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

Figure 2-1 illustrates the Coherence Web Local Storage Enabled checkbox in the WebLogic Server Administration Console Settings for cluster page.

Figure 2-1 Coherence Web Local Storage Enabled Checkbox

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

2.5 Using a Custom Session Cache Configuration File

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 Push Replication, 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:

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

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
```
For more information on the packaging requirements for a GAR file, see "Packaging Coherence Applications for WebLogic Server" in Oracle Fusion Middleware 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>
```
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 tangosol.coherence.session.localstorage to true.
For information on deploying GAR files, see "Deploying Coherence Applications To a WebLogic Server Domain" in Oracle Fusion Middleware Administering Oracle Coherence. and "Deploying Coherence Applications in WebLogic Server" in Developing Oracle Coherence Applications for Oracle WebLogic Server.

2.6 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 for more information.
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.

2.7 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

2.8 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 Appendix A, "Coherence*Web Context Parameters" for more information on the coherence-session-affinity-token context parameter.

2.9 WebLogic Server and Coherence: Compatibility

Coherence*Web for 12.1.3 is compatible with a number of different application servers. In the case of WebLogic Server, WebLogic Server and Coherence must be on the same versions when using Coherence*Web. Weblogic Server 12.1.3 is not compatible with earlier versions of Coherence*Web. For information on the compatibility between earlier versions of Coherence*Web and WebLogic Server, see "Using Coherence*Web with WebLogic Server" in Administering HTTP Session Management with Oracle Coherence*Web (12.1.2).