使用Coherence*Web选项对WebLogic Server的Session进行复制

Note:

Except where noted, this chapter pertains to the 11g Release 2 (10.3.3) of WebLogic Server.

Coherence*Web provides session state persistence and management. It is a session management module that uses Coherence 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 WebLogic Server's 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 off-load HTTP session storage to an existing Coherence cluster

• you want to share session state across EAR files.

2.1 Overview of the Coherence*Web SPI

The Coherence*Web Service Provider Interface (SPI) consists of the coherence-web-spi.war file. You also need the coherence.jar to enable Coherence*Web functionality.

2.1.1 Coherence*Web SPI Configurations

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

• The Coherence*Web SPI 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.

The Coherence caches used by the Coherence*Web SPI are configured by the session-cache-config.xml file. This file is located inside the coherence-web-spi.war file under the WEB-INF\classes directory. Any cache configuration change should be put inside session-cache-config.xml, and then repackaged inside coherence-web-spi.war.

Coherence*Web provides several session locking modes to control concurrent access of sessions. Both Coherence*Web and the Coherence*Web SPI employ Optimistic locking by default. This allows concurrent access to a session by multiple threads in a single JVM or multiple JVMs while prohibiting concurrent modification. 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, you will require a load balancer if you employ sticky session optimization with any of the non-Optimistic locking modes. 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 here:

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

2.2 Configuring And Deploying Coherence*Web—Main Steps

Coherence*Web includes a deployable shared library that contains a native plug-in to WebLogic Server's 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 weblogic.xml or weblogic-application.xml. 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 (Weblogic Server 10.3.3 and Later)" or "Configure Cluster Nodes (Weblogic Server 10.3.2 and Earlier)".

2.2.1 Download Oracle Coherence

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

By default, Coherence 3.5 is installed with WebLogic Server 10.3.3. If you are using Weblogic Server 10.3.3, you must replace the contents of the coherence directory that was installed with the server with the contents of the Coherence 3.6 distribution. The default location of the Coherence directory is C:\Oracle\Middleware\coherence_3.5.

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

2.2.2 Configure Coherence*Web

The Coherence*Web SPI provides a default configuration that should satisfy most Web applications. Table 2-1 lists only those Coherence*Web context parameters where the default for the SPI version is different from the non-SPI version. For a full 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 honored.

Table 2-1 Coherence*Web SPI Context Parameters

Parameter Name	Description
coherence-application-name	Coherence*Web uses the value of this parameter to determine the name of the application that uses ApplicationScopeController to scope attributes. The value for this parameter should be provided in the following format: application name + ! + Web module name where application name is the name of the application that uses ApplicationScopeController and Web module name is the name of the Web module in which it appears. For example, if you have an EAR named test.ear and a Web-module named app1 defined in the EAR, then the default value for coherence-application-name 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 ApplicationScopeController is configured, then a warning is logged saying that the application name was not configured. See "Session Attribute Scoping" for more information.
coherence-factory-class	The fully qualified class name of the SessionHelper.Factory to use. Other possible values include com.tangosol.coherence.servlet.apiXX.DefaultFactory where XX is 22, 23, 24, or 25 for Servlet 2.2, 2.3, 2.4, or 2.5 containers respectively. Default is weblogic.servlet.internal.session.WebLogicSPIFactory
coherence-reaperdaemon-assume-locality	This setting allows the 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 expiry. This value must be set to false if the session storage cache is being managed by nodes that are not running a reaper, for example if cache servers are being used to manage the session storage cache. If cache servers are being used, select the "split" model and run the session overflow storage in a separate distributed cache service that is managed entirely by the cache servers. Leave the session storage cache itself in a distributed cache service that is managed entirely by the application server JVMs so they can take advantage of this "assume locality" feature. Default is false.
coherence-scopecontroller-class	This value specifies the class name of the optional com.tangosol.coherence.servlet.HttpSessionCollection$AttributeScopeController interface implementation to use. Valid values include: com.tangosol.coherence.servlet.AbstractHttpSessionCollection$SimpleScopeController com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController (default) com.tangosol.coherence.servlet.AbstractHttpSessionCollection$GlobalScopeController Default is com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController
coherence-session-weblogic-compatibility-mode	This parameter is available only for 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-app. 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. All other session persistence mechanisms in WebLogic use a single session ID in each web-app to refer to different session instances. Defaults to true unless the global scope controller is specified. If the controller is specified, then it defaults to false.

2.2.3 Configure the Session Cookies

If you run the Coherence*Web SPI, then WebLogic Server generates and parses the session cookie. Any native Coherence*Web session cookie configuration parameters will be ignored. Session cookies must be configured by using the session cookie parameters in weblogic.xml or weblogic-application.xml.

Table 2-2 describes the WebLogic-generated HTTP session cookie parameters that you can configure in weblogic.xml or weblogic-application.xml.

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

Table 2-2 HTTP Session Cookie Parameters

This WebLogic-Generated Session Cookie Parameter...	Replaces this Coherence*Web Cookie Parameter	Description
cookie-comment	n/a	Specifies the comment that identifies the session tracking cookie in the cookie file. 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 from Sun Microsystems. 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. 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 may set this to a more specific name for your application. Default is JSESSIONID. Updatable? Yes
cookie-path	coherence-session-cookie-path	Defines the session tracking cookie path. If not set, this attribute defaults to / (slash) where the browser sends cookies to all URLs served by WebLogic Server. You may set the path to a narrower mapping, to limit the request URLs to which the browser sends cookies. Default is null. Updatable? Yes
cookie-secure	coherence-session-cookie-secure	Tells the browser to only send the cookie back over an HTTPS connection. This ensures that the cookie ID is secure and should only be used on Web sites that use HTTPS. Session Cookies over HTTP no longer work if this feature is enabled. You should disable the url-rewriting-enabled element if you intend to use this feature. WebLogic Server generates the session cookie Default is false. Updatable? Yes
cookies-enabled	coherence-session-cookies-enabled	Use of session cookies is enabled by default and is recommended, but you can disable them by setting this property to false. You might turn this option off for testing purposes. Default is true. Updatable? Yes
debug-enabled	n/a	Enables the debugging feature for HTTP sessions. Support it by enabling HttpSessionDebug logging and the WebLogic Server trace logger. Default value is false. Updatable? Yes
encode-session-id-in-query-params	n/a	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. Default value is false. Updatable? Yes
http-proxy-caching-of-cookies	n/a	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. 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 WAP application, you must use URL rewriting because the WAP protocol does not support cookies. Also, some WAP devices have a 128-character limit on URL length (including attributes), which limits the amount of data that can be transmitted using URL re-writing. To allow more space for attributes, use this attribute to limit the size of the session ID that is randomly generated by WebLogic Server. You can also limit the length to a fixed 52 characters, and disallow special characters, by setting the WAPEnabled attribute. For more information, see "URL Rewriting and Wireless Access Protocol" in Developing Web Applications for WebLogic Server. Default is 52. Updatable? No
invalidation-interval-secs	coherence-reaperdaemon-cycle-seconds	Sets the time, in seconds, that Coherence*Web waits between doing house-cleaning 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. Default is 60. Updatable? No
timeout-secs	coherence-session-expire-seconds	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. Default is 3600 seconds. Updatable? No
tracking-enabled	n/a	Enables session tracking between HTTP requests. WebLogic Server generates the HTTP response. 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. Default is true. Updatable? Yes

2.2.4 Start a Cache Server

A Coherence data node (also known as a cache server) 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 up; the start-up 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 stand alone 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.

To Start a Stand-Alone 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 the Developer's Guide for Oracle Coherence for more information.

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

   In this example, cache_configuration_file refers to the cache configuration in the coherence-cache-config.xml file. (Note: if you are only running Coherence*Web, then cache_configuration_file is session-cache-config.xml.) The cache configuration defined for the cache server must be the same as the configuration defined for the application servers which run on the same Coherence cluster.

   If you run Coherence*Web for session management, then the information about the cache configuration should be merged with the session configuration contained in the session-cache-config.xml file. Similarly, the cache and session configuration must be consistent across WebLogic and Cache servers.

2. Start one or more Coherence data nodes 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, include the command line property -Dtangosol.coherence.session.localstorage=true in the server startup command.

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

2.2.5 Configure Cluster Nodes (Weblogic Server 10.3.3 and Later)

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-web-spi.war and coherence.jar in the classloader's hierarchy.

WebLogic Server 10.3.3 provides several features that allow your applications to more easily interact with the Coherence cache. For a complete discussion of these features see Using ActiveCache. To employ ActiveCache functionality in your applications, you must also deploy the active-cache.jar file, which you can find in the WL_HOME/common/deployable-libraries directory.

• Configuring Application Server-Scoped Cluster Nodes

• Configuring EAR-Scoped Cluster Nodes

• Configuring WAR-Scoped Cluster Nodes

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

Note:

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

An example of such an environment may be a deployment where multiple application teams are deploying applications written independently, without carefully coordinating and enforcing their conventions and naming standards. With this configuration, all applications are part of the same cluster and the likelihood of collisions between namespaces for caches, services, and other configuration settings is quite high and may lead to unexpected results.

For these reasons, Oracle Coherence strongly recommends that you use EAR-scoped and WAR-scoped cluster node configurations. If you are in doubt 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 coherence.jar, coherence-web-spi.war, and WL_HOME/common/deployable-libraries/active-cache.jar in the system classpath. The active-cache.jar should be referenced only from the deployable-libraries folder in the system classpath and should not be copied to any other location.

2. Enable Coherence*Web in your Web application.

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

   Example 2-1 Library Reference for a WAR File

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

3. (Optional) If you must configure Coherence cluster properties, create a CoherenceClusterSystemResourceMBean and reference it in the ServerMBean.

   You can use WLST to reference the MBean. See createServerScopedCoherenceSystemResource in Using ActiveCache.

2.2.5.2 Configuring EAR-Scoped Cluster Nodes

Follow these steps to use Coherence*Web for session management:

1. Use either of the following methods to deploy the coherence.jar and active-cache.jar files as shared libraries to all of the target servers where the application will be deployed.

   • Use the WebLogic Server Administration Console or the command line to deploy coherence.jar, active-cache.jar and coherence-web-spi.war as shared libraries. See "Install a Java EE Library" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.

   • Copy coherence.jar and active-cache.jar to the EAR's APP-INF/lib folder of the application. However, the preferred way is to deploy them as shared libraries.

2. If you deploy coherence.jar and active-cache.jar files as shared libraries, then reference them in the weblogic.xml file. Example 2-2 illustrates a sample weblogic.xml configuration. Note that you could also add the library reference to a weblogic-application.xml file if you wanted all web modules to use Coherence*Web.

   Example 2-2 Coherence and Active Cache JARs Referenced in weblogic.xml

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

3. Use one of the following methods to deploy coherence-web-spi.war to all of the target servers where the application will be deployed.

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

     If you deploy the WAR file as a shared library, you must also create a shared library reference in each Web application in the EAR. Add the library-ref stanza illustrated in Example 2-3 to the weblogic.xml file in each WAR file deployed in the WebLogic server that intends to use Coherence*Web.

     Example 2-3 Library Reference for a Web Application in the EAR

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

   • Extract the coherence-web-spi.jar file from the coherence-web-spi.war, and copy the JAR directly into the application. If you use this technique, you must also include the session-descriptor stanza with coherence-web as the value of the persistent-store-type element in the application's weblogic.xml file. Example 2-4 illustrates a sample weblogic.xml configuration.

     Example 2-4 Session Persistence Type coherence-web in weblogic.xml

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

4. (Optional) If you must configure Coherence cluster properties, create a CoherenceClusterSystemResourceMBean and reference it as a coherence-cluster-ref element in weblogic.xml file. This element allows the applications to enroll in the Coherence cluster as specified by the CoherenceClusterSystemResourceMBean attributes. For more information, see Using ActiveCache.

   Example 2-5 illustrates a sample configuration. The myCoherenceCluster MBean in the example is of type CoherenceClusterSystemResourceMBean.

   Example 2-5 Identifying a Coherence Cluster for EAR-Scoped Cluster Nodes

   <weblogic-web-app>
   ...
     <coherence-cluster-ref>
       <coherence-cluster-name>
        myCoherenceCluster
       </coherence-cluster-name>
     </coherence-cluster-ref> 
   ...
   </weblogic-web-app>  
   

2.2.5.3 Configuring WAR-Scoped Cluster Nodes

If you are using Coherence*Web for session management, follow these steps:

1. Use the WebLogic Server Administration Console or the command line to deploy coherence.jar and active-cache.jar, as shared libraries 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. Copy coherence.jar and active-cache.jar to each WAR file's WEB-INF/lib directory.

3. Use one of the following methods to deploy coherence-web-spi.war to all of the target servers where the application will be deployed.

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

     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-6 to the weblogic.xml file in the Web application's WEB-INF directory.

     Example 2-6 Library Reference for a Web Application

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

   • Extract the coherence-web-spi.jar file from the coherence-web-spi.war file and copy the JAR directly into the application. You must also include the session-descriptor stanza with coherence-web as the value of the persistent-store-type element. Example 2-7 illustrates a sample weblogic.xml configuration.

     Example 2-7 Session Persistence Type coherence-web in weblogic.xml

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

4. (Optional) If you must configure Coherence cluster properties, create a CoherenceClusterSystemResourceMBean and reference it as a coherence-cluster-ref element in weblogic.xml or weblogic-ejb-jar.xml file.illustrates a sample configuration for WAR-scoped cluster nodes in the weblogic.xml file. The myCoherenceCluster MBean is of type CoherenceClusterSystemResourceMBean. For more information, see Using ActiveCache.

   Example 2-8 illustrates a sample configuration for WAR-scoped cluster nodes in the weblogic.xml file. The myCoherenceCluster MBean is of type CoherenceClusterSystemResourceMBean.

   Example 2-8 Identifying a Coherence Cluster for EAR-Scoped Cluster Nodes

   <weblogic-web-app>
   ...
     <coherence-cluster-ref>
       <coherence-cluster-name>
        myCoherenceCluster
       </coherence-cluster-name>
     </coherence-cluster-ref> 
   ...
   </weblogic-web-app>
   

2.2.6 Configure Cluster Nodes (Weblogic Server 10.3.2 and Earlier)

Weblogic Server 10.3.2 and earlier does not support ActiveCache.

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

• Configuring Application Server-Scoped Cluster Nodes

• Configuring EAR-Scoped Cluster Nodes

• Configuring WAR-Scoped Cluster Nodes

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

Note:

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

An example of such an environment may be a deployment where multiple application teams are deploying applications written independently, without carefully coordinating and enforcing their conventions and naming standards. With this configuration, all applications are part of the same cluster and the likelihood of collisions between namespaces for caches, services, and other configuration settings is quite high and may lead to unexpected results.

For these reasons, Oracle Coherence strongly recommends that you use EAR-scoped and WAR-scoped cluster node configurations. If you are in doubt 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.6.1 Configuring Application Server-Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server.

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

3. Enable Coherence*Web in your Web application.

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

   Example 2-9 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.6.2 Configuring EAR-Scoped Cluster Nodes

1. Use either of the following methods to deploy coherence.jar and coherence-web-spi.war to all of the target servers where the application will be deployed:

   • Use the WebLogic Server Administration Console to deploy coherence.jar and coherence-web-spi.war as shared libraries. See "Install a Java EE Library" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help for more information.

   • Extract the coherence-web-spi.jar file from the coherence-web-spi.war. Copy the coherence-web-spi.jar file and the coherence.jar file directly into the EAR's APP-INF/lib folder of the application. If you use this technique, you must also include the session-descriptor stanza with coherence-web as the value of the persistent-store-type element in the application's weblogic.xml file.

     Example 2-10 Session Persistence Type coherence-web in weblogic.xml

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

2. If you deploy coherence.jar and coherence-web-spi.war as shared libraries, you must also create a shared library reference in each Web application in the EAR. Add the stanza illustrated in Example 2-11 to the weblogic.xml file in each WAR file deployed in the WebLogic server that intends to use Coherence*Web. Note that you could also add the library reference to a weblogic-application.xml file if you wanted all web modules to use Coherence*Web.

   Example 2-11 Library Reference for a Web Application in the EAR

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

2.2.6.3 Configuring WAR-Scoped Cluster Nodes

1. Use either of the following methods to deploy coherence.jar and coherence-web-spi.war.

   • Use the WebLogic Server Administration Console or the command line to deploy coherence.jar and coherence-web-spi.war as shared libraries 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.

   • Extract the coherence-web-spi.jar file from the coherence-web-spi.war. Copy the coherence-web-spi.jar file and the coherence.jar file directly into the WAR's WEB-INF/lib folder of the application. If you use this technique, you must also include the session-descriptor stanza with coherence-web as the value of the persistent-store-type element in the application's weblogic.xml file. See Example 2-10.

2. If you deploy coherence.jar and coherence-web-spi.war as shared libraries, create a shared library reference by adding the stanza illustrated in Example 2-12 to the weblogic.xml file in the Web application's WEB-INF directory.

   Example 2-12 Library Reference for a Web Application

   <weblogic-web-app>
        ...
         <library-ref>
              <library-name>coherence-web</library-name>
        </library-ref>
         <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 "/". 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. Since 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 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 lifecycle 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 lifecycle 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.4 Securing Coherence*Web Deployments

To prevent unauthorized Coherence TCMP cluster members from accessing HTTP session cache servers, you can configure symmetric or asymmetric encryption filters. Coherence ships with two JCA-based encryption filters which can be used to protect the clustered communications for privacy and authenticity.

• symmetric filter, which uses symmetric encryption to protect cluster communications. The encryption key is generated from a shared password known to all cluster members. This filter is suitable for small deployments or where the maintenance and protection of a shared password is feasible.

• PKCS Encryption filter, which uses public key cryptography (asymmetric encryption) to protect the cluster join protocol, and then switches over to much faster symmetric encryption for service level data transfers. Unlike the symmetric encryption filter, there is no persisted shared secret. The symmetric encryption key is randomly generated by the cluster's senior member, and is securely transfer to authenticated cluster members as part of the cluster join protocol. This encryption filter is suitable for deployments where maintenance of a shared secret is not feasible.

See "Using Network Filters" in the Developer's Guide for Oracle Coherence for information on implementing these filters.

2.5 Enabling Coherence*Web SPI for ColdFusion Applications

If your ColdFusion applications run on WebLogic server, follow these steps to enable Coherence*Web for session management.

1. In the ColdFusion installer create a WAR version of ColdFusion.

2. Follow the provided instructions for configuring WebLogic Server for ColdFusion.

3. Extract the WAR into a directory for exploded directory deployment to WebLogic Server.

4. Create a weblogic.xml file in the /WEB-INF directory of the exploded ColdFusion WAR. Specify the Coherence SPI as a <library-ref>.

   <?xml version="1.0"?>
   <weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd">
      <library-ref>
         <library-name>coherence-web-spi</library-name>
      </library-ref>
   </weblogic-web-app>
   

5. Copy the coherence.jar to the WEB-INF/lib directory of the exploded application.

6. Copy cfusion.jar from WEB-INF/cfusion/lib to WEB-INF/.

7. Start the WebLogic Server instance. Deploy the Coherence*Web SPI to WebLogic. The SPI is located at coherence\lib\coherence-web-spi.war in the Coherence distribution.

8. Deploy the ColdFusion application to the WebLogic Server instance.

9. Configure ColdFusion MX to use J2EE session management.

   1. Access the ColdFusion administration page at the following URL:

      http://<host>:<port>/coldfusion-context-root/CFIDE/administrator. 
      

   2. Select Memory Variables under Server Sessions and enable the Use J2EE session variables checkbox.

10. Add your ColdFusion application under the exploded ColdFusion WAR.

    The application must have a Application.cfm file that specifies sessionmanagement="Yes", but should not configure the session using ColdFusion configuration (otherwise, exceptions are thrown). The Application.cfm should contain the following line:

    <cfapplication sessionmanagement="Yes">

11. http://pindao.huoban.taobao.com/tms/channel/electric.htm?pid=mm_24766140_0_0&eventid=101333