|
Note: Except where noted, this chapter pertains to the 11g Release 1 Patch Set 3 (10.3.4), or later of Oracle WebLogic Server. |
This chapter contains the following sections:
Coherence*Web provides session state persistence and management. It is a session management module that uses Coherence caches for storing and managing session data. This chapter describes how to set up and deploy Coherence*Web so that it can be used by applications running on WebLogic Server.
Coherence*Web is an alternative to the WebLogic Server in-memory HTTP state replication services. Consider using Coherence*Web if you are encountering any of these situations:
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
|
New for 3.7.1: The |
The Coherence*Web Service Provider Interface (SPI) consists of the coherence-web-spi.war file. To use functionality provided by the coherence-web-spi.war, the coherence.jar classes must also be available to the Web application.
In Coherence*Web, the following default cache configurations are defined:
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.
Coherence cache configurations and services used by Coherence*Web SPI are defined in the session-cache-config.xml file, which can be found in the coherence-web.jar file. The default cache and services configuration defined in the session-cache-config.xml file should satisfy most Web applications.
Coherence*Web provides several session locking modes to control concurrent access of sessions. Both Coherence*Web and the Coherence*Web SPI employ Last Write Wins locking by default. See "Session Locking Modes" for more information about locking modes.
By itself, the Coherence*Web SPI does not require a load balancer to run in front of the WebLogic Server tier. However, a load balancer will improve performance. It is required if the same session will be used concurrently and locking is not enabled. The default load balancer enforces HTTP session JVM affinity, however, other load balancing alternatives are available. WebLogic Server ships with several different proxy plug-ins which enforce JVM session stickiness. Documentation for configuring the WebLogic Server proxy plug-in is available at this URL:
http://download.oracle.com/docs/cd/E17904_01/web.1111/e13709/load_balancing.htm
Coherence*Web includes a deployable shared library that contains a native plug-in to the WebLogic Server HTTP Session Management interface. The following steps summarize how to prepare your deployments to use Coherence*Web with applications running on WebLogic Server:
Download Oracle Coherence to your file system. See "Download Oracle Coherence".
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."
(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".
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".
All of the files needed by Coherence*Web, including the coherence-web-spi.war file, are included in the Coherence distribution.
By default, Coherence 3.6 is installed with WebLogic Server 10.3.4. The default location of the Coherence directory is C:\Oracle\Middleware\coherence_3.6. If you are using WebLogic Server 10.3.4, you can download Coherence 3.7 and save it to your file system. Ensure that your applications reference coherence-web-spi.war, coherence.jar, and other library files that are in the Coherence 3.7 distribution.
Similarly, if you are working with WebLogic Server 10.3.3, you might already have Coherence installed in a coherence_3.5 directory. Again, you can download Coherence 3.7 and save it to your file system. Ensure that your applications reference coherence-web-spi.war, coherence.jar, and other library files that are in the Coherence 3.7 distribution.
If you are using WebLogic Server 10.3.2 or earlier, simply download the Coherence distribution to your file system.
Applying Required Software Patches
Some older versions of WebLogic Server require you to apply software patches before you can work with Coherence and Coherence*Web. Table 2-1 identifies the versions of WebLogic Server and their associated patches.
Table 2-1 Required Software Patches for WebLogic Server
| WebLogic Server 9.2 MP1 | WebLogic Server 9.2 MP3 | WebLogic Server 10.3 | WebLogic Server 11g (10.3.1 and later) | |
|---|---|---|---|---|
|
WebLogic Smart Update |
Patch ID: 616G |
Patch ID: LP7B |
Patch ID: 6W2W |
No Patch Required |
You can obtain the patches either through the Smart Update utility in the WebLogic Server Administration Console or by going to My Oracle Support.
To use Smart Update, see the instructions in the WebLogic Server Administration Console. For production environments, you should review the Smart Update production installation notes.
To use My Oracle Support, go to the My Oracle Support web site.
Select the Patches tab, click on the Simple Search link, and on the subsequent screen submit a search for a Patch Number/Name with the appropriate value (for example, 11399293). Download the patch zip file from the displayed results. Instructions for applying the Coherence patch are located in the README.txt included in the patch zip file.
The Coherence*Web SPI provides a default configuration that should satisfy most Web applications. Table 2-2 describes only those Coherence*Web context parameters where the default for the SPI version is different from the non-SPI version. Table 2-3 describes the compatibility mode context parameter which is supplied by the SPI. For complete descriptions of all Coherence*Web parameters, see Appendix A, "Coherence*Web Context Parameters."
You can also configure the context parameters on the command line as system properties. The system properties have the same name as the context parameters, but the dash (-) is replaced with a period (.). For example, to declare a value for the context parameter coherence-enable-sessioncontext on the command line, enter it like this:
-Dcoherence.enable.sessioncontext=true
If both a system property and the equivalent context parameter are configured, the value from the system property is used.
Table 2-2 Coherence*Web Context Parameters Configured by the SPI
| Parameter Name | Description |
|---|---|
|
|
Coherence*Web uses the value of this parameter to determine the name of the application that uses the application name + ! + Web module name The application name is the name of the application that uses the For example, if you have an EAR file named 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 |
|
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 |
|
|
This value specifies the class name of the optional Valid values include:
The default set by the Coherence*Web SPI is |
Table 2-3 describes the coherence-session-weblogic-compatibility-mode context parameter which is specifically provided by the Coherence*Web SPI.
Table 2-3 Context Parameter Provided by the Coherence*Web SPI
| Parameter Name | Description |
|---|---|
|
This parameter is provided by the SPI version of Coherence*Web. If its value is set to This parameter defaults to |
Table 2-4 describes the coherence-factory-class context parameter. The default value, which is set by the Coherence*Web SPI, should not be changed.
Table 2-4 Context Parameter Value that Should Not be Changed
| Parameter Name | Description |
|---|---|
|
The fully qualified name of the class that implements the |
If you are using Coherence*Web SPI, then WebLogic Server generates and parses the session cookie. In this case, any native Coherence*Web session cookie configuration parameters will be ignored. To configure the session cookies, use the WebLogic-generated HTTP session cookie parameters in the weblogic.xml or weblogic-application.xml files. Table 2-5 describes these parameters.
In this table, Updatable? indicates whether the value of the parameter can be changed while the server is running. Not applicable indicates that there is no corresponding Coherence session cookie parameter.
Table 2-5 WebLogic-Generated HTTP Session Cookie Parameters
| This Session Cookie Parameter... | Replaces this Coherence*Web Cookie Parameter | Description |
|---|---|---|
|
|
Not applicable |
Specifies the comment that identifies the session tracking cookie in the cookie file. The default is Updatable? Yes |
|
|
|
Specifies the domain for which the cookie is valid. For example, setting The domain name must have at least two components. Setting a name to If not set, this attribute defaults to the server that issued the cookie. For more information, see The default is Updatable? Yes |
|
|
|
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 Updatable? Yes |
|
|
|
Defines the session-tracking cookie name. Defaults to The default is Updatable? Yes |
|
|
|
Defines the session-tracking cookie path. If not set, this attribute defaults to a slash (" The default is Updatable? Yes |
|
|
|
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 WebLogic Server generates the session cookie. The default is Updatable? Yes |
|
|
|
Enables use of session cookies by default and is recommended, but you can disable them by setting this property to The default is Updatable? Yes |
|
|
Not applicable |
Enables the debugging feature for HTTP sessions. Support it by enabling The default value is Updatable? Yes |
|
|
Not applicable |
Is set to WebLogic Server generates the HTTP response. The default value is Updatable? Yes |
|
|
Not applicable |
When set to WebLogic Server generates the HTTP response. The default value is Updatable? Yes |
|
|
|
Sets the size of the session ID. The minimum value is 8 bytes and the maximum value is 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 The default is 52. Updatable? No |
|
|
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 Updatable? No |
|
|
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 The default is Updatable? No |
|
|
Not applicable |
Enables session tracking between HTTP requests. WebLogic Server generates the HTTP response. The default is Updatable? No |
|
|
|
Enables URL rewriting, which encodes the session ID into the URL and provides session tracking if cookies are disabled in the browser and the
WebLogic Server generates the HTTP response. The default is Updatable? Yes |
A Coherence cache server (also known as a data node) is responsible for storing and managing all cached data. It can be either a dedicated JVM or run within a WebLogic Server instance. The senior node (which is the first node) in a Coherence data cluster can take several seconds to start; the startup time required by subsequent nodes is minimal.
Whether you start the cache servers first or the WebLogic Server instances first, depends on the server topology you are employing:
If you are using an In-Process topology (all storage-enabled WebLogic Server instances), then it does not matter if you start the cache servers first or WebLogic Server instances first.
If you are using an Out-of-Process topology (storage-disabled WebLogic Server instances and standalone Coherence cache servers), then start the cache servers first, followed by the WebLogic Server instances. This will ensure that there is minimal (measured in milliseconds) startup time for applications using Coherence. Any additional Web applications that use Coherence are guaranteed not to be the senior data member, so they will have minimal impact on WebLogic Server startup.
In this topology, if you do not start the cache servers first, Coherence will respond with an error message similar to the following:
No storage-enabled nodes exist for service ...
Follow these steps to start a standalone Coherence data node:
Create a script for starting a Coherence data node. The following is a very simple example of a script that starts a storage-enabled cache server. This example assumes that you are using a Sun JVM. See "JVM Tuning" in Developer's Guide for Oracle Coherence for more information.
java -server -Xms512m -Xmx512m -cp <Coherence installation dir>/lib/coherence-web.jar:<Coherence installation dir>/lib/coherence.jar -Dtangosol.coherence.management.remote=true -Dtangosol.coherence.cacheconfig=cache_configuration_file -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
You must include coherence-web.jar and coherence.jar on the classpath. The cache_configuration_file represents the absolute path to the cache configuration file on your file system. For Coherence*Web, this will be the session-cache-config.xml file. Note that the cache configuration defined for the cache server must match the cache configuration defined for the application servers which run on the same Coherence cluster.
If you have additional Coherence caches running on Coherence*Web, then you must merge the cache configuration information (typically defined in the coherence-cache-config.xml file) with the session configuration contained in the session-cache-config.xml file. The cache and session configuration must be consistent across WebLogic Server and Coherence cache servers.
For more information on merging these files, see "Merging Coherence Cache and Session Information" in Integration Guide for Oracle Coherence.
Start one or more Coherence data nodes using the script described in the previous step.
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 data node. 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.
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.
The session management provided by Coherence*Web can have application server-scope, EAR-scope, or WAR-scope. Like Coherence clusters, scoping of Coherence*Web depends on the placement of the coherence.jar file in the classloader's hierarchy. You can find detailed information about each of the scopes in "Cluster Node Isolation".
WebLogic Server, versions 10.3.3 and later, provides several features, collectively known as ActiveCache, that allow your applications to more easily interact with the Coherence cache. For a complete discussion of these features see the Using ActiveCache guide.
Some earlier versions of WebLogic Server (such as version 10.3.1 and earlier) might need a software patch to use Coherence and Coherence*Web. To find out if your version of WebLogic Server requires a patch, see "Applying Required Software Patches".
The following sections describe how you can configure the different cluster node configurations to run Coherence*Web:
|
Note: Consider the use of the application server-scoped cluster configuration very carefully. Do not use it in environments where application interaction is unknown or unpredictable. An example of such an environment might be a deployment where multiple application teams are deploying applications written independently, without carefully coordinating and enforcing their conventions and naming standards. With this configuration, all applications are part of the same cluster—the likelihood of collisions between namespaces for caches, services, and other configuration settings is quite high and could lead to unexpected results. For these reasons, Oracle Coherence strongly recommends that you use EAR-scoped and WAR-scoped cluster node configurations. If you are in doubt regarding which deployment topology to choose, or if this warning applies to your deployment, then do not choose the application server-scoped cluster node configuration. |
If you are adding Coherence*Web for session management to a Coherence cluster, follow these steps:
Edit your WebLogic Server system classpath to include the coherence.jar file or copy the JAR file to your $DOMAIN_HOME/lib directory.
Use the WebLogic Server Administration Console or the command line to deploy coherence-web-spi.war file as a shared library.
Enable Coherence*Web in your Web application.
Add the library reference code illustrated in Example 2-1 to the weblogic.xml file in each WAR file deployed in the WebLogic Server that intends to use Coherence*Web.
If you are using Coherence*Web for session management in EAR-scoped cluster nodes, and your applications are running on WebLogic Server 10.3.2 or earlier, follow these steps:
Use the WebLogic Server Administration Console to deploy the coherence.jar and coherence-web-spi.war files as shared libraries to all of the target servers where the application will be deployed. See "Install a Java EE Library" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help for more information.
If you receive an error when you attempt to deploy coherence.jar through the WebLogic Server Administration Console, you can use WLST commands. See Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help for more information.
Reference the coherence.jar file in the weblogic-application.xml file. Store the file in the EAR's META-INF directory.
Example 2-2 illustrates a weblogic-application.xml file.
Reference the coherence-web-spi.war file in the weblogic.xml file.
Example 2-3 illustrates a weblogic.xml file.
If you are using Coherence*Web for session management in WAR-scoped cluster nodes, follow these steps:
Use the WebLogic Server Administration Console or the command line to deploy the coherence-web-spi.war file as a shared library to all of the target servers where the application will be deployed. See "Install a Java EE Library" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.
Add the coherence.jar file to the application. You can do this in any of the following ways:
Import coherence.jar file as an optional package in the manifest.mf file of each module that will be using Coherence. Example 2-4 illustrates a manifest.mf file.
Copy the coherence.jar file to the WAR file's WEB-INF/lib directory.
If you deploy the coherence-web-spi.war file as a shared library, you must also create a shared library reference by adding the stanza illustrated in Example 2-5 to the weblogic.xml file in the WAR file's WEB-INF directory.
WebLogic Server and Coherence*Web handle session scoping and the session lifecycle in different ways. This can impact your decision to implement a single sign-on (SSO) strategy for your applications.
By default, WebLogic Server uses the same session ID in every Web application for a given client, and sets the session cookie path to a slash (/). This is a requirement of the WebLogic Server default thin SSO implementation, which is enabled by default. By generating a session cookie with a path of "/", clients always return the same session ID in every request to the server. In WebLogic Server, a single session ID can be mapped to multiple session objects. Each Web application will have a different session object instance even though the session ID is identical (unless session sharing is enabled).
In contrast, Coherence*Web maps a session ID to a single session instance. This means that the behavior of having multiple session instances mapped to the same ID is not replicated by default if an application uses Coherence*Web. Because the session cookie is mapped to "/" by default, a single Coherence*Web session is shared across all Web applications. The default configuration in Coherence*Web is that all session attributes are scoped to a Web application. For most purposes, this single session approach is transparent. The major difference of having a single session across all Web applications is the impact of session invalidation. If Coherence*Web is enabled and you invalidate a session in one Web application, then you invalidate that session in all Web applications that use that session instance. If your Web applications do not use thin SSO, then you can avoid this issue by scoping the session cookie to the Web application path.
Therefore, you have the following options regarding SSO:
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.
If you are running Coherence*Web on WebLogic Server and on other application servers within a single cluster, then the session cookies created by WebLogic Server will not be decoded correctly by Coherence*Web on the other servers. This is because WebLogic Server adds a session affinity suffix to the cookie which is not part of the session ID stored in Coherence*Web. The other application servers must remove the WebLogic session affinity suffix from the session cookie value for Coherence*Web to be able to retrieve the session from the Coherence cache.
To strip the WebLogic session affinity suffix from the session cookie, add the coherence-session-affinity-token context parameter to the web.xml file used in the other application servers. Set the parameter value to an exclamation point (!), as illustrated in Example 2-6. The session affinity suffix will be removed from the session cookie when it is processed by the other application server.
Example 2-6 Removing Session Affinity Suffix
... <context-param> <param-name>coherence-session-affinity-token</param-name> <param-value>!</param-value> </context-param> ...
See Appendix A, "Coherence*Web Context Parameters" for more information on the coherence-session-affinity-token context parameter.