10 Using Coherence*Web with WebLogic Portal

This chapter describes how Coherence*Web can be used in a WebLogic Portal environment to provide session state management based on Coherence. Coherence*Web allows for more advanced deployment models, session models, and locking modes in a clustered environment. For more information about these features, see Chapter 5, "Coherence*Web Session Management Features."

This chapter contains the following sections:

Downloading Required Patches (Optional)
Using Coherence*Web with WebLogic Portal—Main Steps
Using the Coherence Cache Provider with WebLogic Portal

10.1 Downloading Required Patches (Optional)

Note:

Oracle WebLogic Server releases 10.3.1 or later do not require a patch. If you are using release 10.3.1 or later, you can skip this section.

If you are using WebLogic Server 10.3 or earlier, apply the appropriate software patch to all WebLogic Server instances that are hosting the Web applications that will use Coherence*Web. Table 10-1 lists the appropriate patches for your version of WebLogic Server and Coherence release level.

Table 10-1 Required WebLogic Server and Coherence Patch Release Levels

	WebLogic Server 9.2 MP1	WebLogic Server 10.3	WebLogic Server 10.3.1 and later
WebLogic Smart Update	Patch ID: AJQB	Patch ID: 6W2W	No patch required.

The patches can be downloaded by using either the MyOracleSupport Web site or the WebLogic Server's Smart Update utility.

To Download from MyOracleSupport:

Go to the MyOracleSupport Web site to manually locate the patch.

http://support.oracle.com/
Select the Patches tab and click the Simple Search link. On the subsequent screen, submit a search for a Patch Number/Name with the appropriate value (for example, 11399293).
Download the patch zip file from the displayed results.
See the README.txt included in the patch zip file for instructions for applying the Coherence patch.

To Download Using Smart Update:

Review the instructions in the Smart Update Guide for using Smart Update to install WebLogic Server patches.

For production environments, Oracle recommends that you review the Smart Update production installation.

You can find the Smart Update Guide at this URL:

http://download.oracle.com/docs/cd/E14759_01/doc.32/e14143/toc.htm
Select Start then All Programs then Oracle WebLogic then Smart Update to open the login dialog box. Use your support ID and password to log in.

Figure 10-1 Oracle Smart Update Login Dialog Box

Description of "Figure 10-1 Oracle Smart Update Login Dialog Box"
Download and apply the appropriate patch for your release of WebLogic Server. Figure 10-2 illustrates the Oracle Smart Update browser.

Figure 10-2 Oracle Smart Update Browser

Description of "Figure 10-2 Oracle Smart Update Browser"

10.2 Using Coherence*Web with WebLogic Portal—Main Steps

Follow these steps to use Coherence*Web with WebLogic Portal:

Start a Cache Server
Modify the Session Configuration (Optional)
Enable a P13N (Personalization) Cache Provider (Optional)
Locate the Coherence JAR File
Reference the SPI in the Portal Application
Enable Coherence*Web Sessions
Create and Deploy the Application

10.2.1 Start a Cache Server

A cache server JVM is a dedicated Coherence JVM that is responsible for storing and managing all cached data (in this case, the HTTP Session state). One or more cache server JVMs must be started before the WebLogic Server or WebLogic Portal JVMs can be started. Follow these steps to start a cache server:

Create a script for starting a Cache Server JVM. The following is an example of a script that starts a storage-enabled cache server for use with Coherence*Web. See "JVM Tuning" in Oracle Fusion Middleware Developing Applications with Oracle Coherence for more information about tuning your particular JVM.
```
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=C:\Coherence1212\coherence\default-session-cache-config.xml -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
```
This command assumes that you have extracted the default-session-cache-config.xml file from the coherence-web.jar file and stored it in the C:\Coherence1212\coherence\ directory.
Start one or more cache server JVMs using the script described in the previous step.

10.2.2 Modify the Session Configuration (Optional)

Modify the default-session-cache-config.xml file (if necessary) to customize the cache topology for Coherence*Web. Save the file as session-cache-config.xml.

See Appendix C, "Session Cache Configuration File" for a description of the default configuration of the default-session-cache-config.xml file.

10.2.3 Enable a P13N (Personalization) Cache Provider (Optional)

If you want to use the Coherence P13N (Personalization) cache provider, then copy the coherence-wlp.jar file into the APP-INF\lib directory of the portal enterprise application.

See Oracle Fusion Middleware Integrating Oracle Coherence for more information about the P13N CacheProvider SPI implementation and Web Services for Remote Portlets (WSRP)-federated portals.

If you want to use the Coherence P13N cache as the default cache provider, add the following line before the first <cache> element to the META-INF\p13n-cache-config.xml file in the portal enterprise application:

<default-provider-id>com.tangosol.coherence.weblogic</default-provider-id>

10.2.4 Locate the Coherence JAR File

Copy the coherence.jar file into the APP-INF\lib directory of the portal enterprise application.

10.2.5 Reference the SPI in the Portal Application

Reference the coherence-web-spi.war file by using a library reference (library-ref) in the WEB-INF\weblogic.xml file in the portal Web application:

<wls:library-ref>
   <wls:library-name>coherence-web-spi</wls:library-name>
</wls:library-ref>

10.2.6 Enable Coherence*Web Sessions

To enable Coherence*Web sessions, set the application parameter coherence-web-sessions-enabled to true in the WEB-INF\web.xml file in the portal Web application:

      <context-param>
          <param-name>coherence-web-sessions-enabled</param-name>
          <param-value>true</param-value>
      </context-param>

10.2.7 Create and Deploy the Application

In the portal domain, deploy the coherence-web-spi.war file as a library to the cluster.
Create an EAR file for the application.
In the portal domain, deploy the application EAR file to the cluster.

10.3 Using the Coherence Cache Provider with WebLogic Portal

The Coherence cache provider can be configured to provide caching services for enterprise applications that run on WebLogic Portal. To accomplish this, the cache providers and the WebLogic portal servers are set up to run in an out-of-process deployment topology.

In out-of-process topology, the WebLogic portal servers (or, WebLogic Portal server tier) are configured as cache clients with local storage disabled (that is, the tangosol.coherence.weblogic.localstorage, tangosol.coherence.distributed.localstorage, and tangosol.coherence.session.localstorage system properties are set to false) and there are dedicated JVMs running as cache servers, physically storing and managing the clustered data.

This approach has these benefits:

Session data storage is offloaded from the WebLogic Portal tier to the cache server tier. This reduces heap usage, garbage collection times, and so on.
The WebLogic Portal and cache server tiers can be scaled independently. If more application processing power is needed, start more WebLogic Portal servers. If more session storage capacity is needed, start more cache servers.

Out-of-process topology is the default recommendation of Oracle Coherence due to its flexibility. Figure 10-3 illustrates the out of process topology. Each of the WebLogic Portal servers in the portal tier maintain their own near cache. These near caches communicate with the session data cache which runs in a separate cache server tier.

See "Deploying Coherence Cache Provider for Out-of-Process Topology" for instructions on how to configure this topology.

Figure 10-3 Out-of-Process Deployment Topology for WebLogic Portal

Description of "Figure 10-3 Out-of-Process Deployment Topology for WebLogic Portal"

10.3.1 Deploying Coherence Cache Provider for Out-of-Process Topology

Obtain the session cache and portal cache configuration files:
- Extract the default-session-cache-config.xml file from the coherence-web.jar file.
- Extract the portal-cache-config.xml file from the coherence-wlp.jar file.
For the Coherence Cache Server:
1. Merge the contents of the default-session-cache-config.xml and portal-cache-config.xml files so that a set of Coherence grid nodes can support both types of objects: session and P13N cache.
  
  You will need two copies of this file: one that will be used by the Coherence cache servers and one that will be used by the WebLogic Portal managed servers. The contents of the two files will be identical, except for the values of the local-storage properties in the portal cache and the session cache sections.
  
  Example F-1 in Appendix F, "Cache Configuration for WebLogic Portal and Oracle Coherence" illustrates a merged configuration file that can be used for the WebLogic Portal managed servers. The local-storage values for the session cache and portal cache are set to false. The configuration file for the Coherence cache server can be the same as Example F-1, except the values for the local-storage system property in the session cache configuration section and portal cache configuration section must be set to true.
2. Set the merged configuration file for the Coherence caches as the cache configuration for the Coherence grid JVMs. For example, in the following system property to locate the cache configuration file, portal-session-cache-config.xml represents the merged file:
```
-Dtangosol.coherence.cacheconfig=D:\Coherence1212\coherence\temp\portal-session-cache-config.xml
```
For the Portal Server:
1. Use the merged configuration file for the WebLogic Portal managed server as the cache configuration file for the servers. For each application that will run on the WebLogic Portal managed server, copy the file to the application's APP-INF/classes directory.
2. Add the system properties to disable local storage for the WebLogic Portal managed servers and optionally specify the cache configuration file. For example, you can add the following properties to your Coherence cache server startup script:
```
-Dtangosol.coherence.weblogic.localstorage=false 
-Dtangosol.coherence.distributed.localstorage=false 
-Dtangosol.coherence.session.localstorage=false
-Dtangosol.coherence.cacheconfig=D:\Coherence1212\coherence\temp\portal-session-cache-config.xml
```
Copy the coherence.jar and coherence-wlp.jar files to the APP-INF/lib directory of your EAR file.

See the deployment instructions in "Using Coherence*Web with WebLogic Portal—Main Steps".
Start the WebLogic Portal managed servers.