Skip Headers
Oracle® Coherence User's Guide for Oracle Coherence*Web
Release 3.7.1

E22620-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Using Coherence*Web with GlassFish Server

Oracle GlassFish Server delivers a flexible, lightweight and extensible Java EE 6 platform. It provides a small footprint, fully featured Java EE application server that is completely supported for commercial deployment and is available as a standalone offering. Oracle GlassFish Server is best suited for applications requiring lightweight infrastructure and the most recent implementations of Java Enterprise Edition. This chapter describes how to set up and deploy Coherence*Web so that it can be used by applications running on GlassFish Server.

Starting with Coherence 3.7 and Oracle GlassFish Server 3.1, there is a Coherence*Web feature called ActiveCache for GlassFish. ActiveCache for GlassFish provides Coherence*Web functionality in Web applications deployed on Oracle GlassFish Servers. In previous releases, the Coherence*Web WebInstaller was required to pre-process applications before they could use Coherence*Web for session storage. With ActiveCache for GlassFish, the WebInstaller pre-processing step is not required for GlassFish 3.1 applications.

New for 3.7.1:

The session-cache-config.xml file has been moved from the coherence-web-spi.war file to the coherence-web.jar file. The coherence-web.jar file can be found in the coherence\lib folder.

3.1 Overview of ActiveCache for GlassFish

ActiveCache for GlassFish functionality is provided in the coherence-web.jar file which can be found in the coherence/lib folder. Coherence cache configurations and services used by ActiveCache for GlassFish 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.

Since Coherence*Web uses Coherence caches to store session data, the coherence.jar file must also be available to the Web application's classloader. See "Configure Cluster Nodes" for more information on configuring ActiveCache for GlassFish to run on EAR-scoped or WAR-scoped cluster nodes.

By default, the Coherence node running on GlassFish Server is configured as storage-disabled. A separate Coherence cache server must be running for the Web application to work.

Coherence*Web provides several session locking modes to control concurrent access of sessions. ActiveCache for GlassFish employs Last Write Wins 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.

The split session model (SplitHttpSessionModel), where small session attributes are stored as a single cache entry, and large attributes are stored as individual cache entries, is the default session model used by ActiveCache for GlassFish. See "Session Models" for more information.

Heap space is made available in GlassFish Server by storing session data in the Coherence data grid. Storing session data outside of GlassFish Server allows the Web application and the server to be restarted without any loss of session data. It also allows sessions to be shared across different web applications. Coherence*Web can run on GlassFish Server in either EAR-scoped or WAR-scoped cluster nodes. Application Server-scope is not supported.

3.2 Configuring And Deploying Coherence*Web on GlassFish Server—Main Steps

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

  1. Download Oracle Coherence to your file system. See "Download Oracle Coherence".

  2. Set the session persistence type to coherence-web for the Web application in glassfish-web.xml file. See "Set the Session Persistence Type".

  3. (Optional) If you must override the default Coherence*Web cache or cluster configuration, edit the session-cache-config.xml file. See "Override the Default Coherence*Web Cache or Cluster Configuration".

  4. Make the coherence-web.jar file available to the Web application. See "Copy the ActiveCache for GlassFish and Session Cache Files to the Application".

  5. Edit the web.xml file to make your Web application available to a server cluster. See "Make Your Web Applications Distributable".

  6. (Optional) Edit the web.xml file in the WAR deployment if your application requires advanced configuration for Coherence*Web. See "Configure Coherence*Web".

  7. (Optional for testing; strongly suggested for production) Start a Cache Server Tier in a JVM that is separate from the one running GlassFish Server. See "Start a Cache Server".

  8. Package the application. Coherence*Web can be configured for EAR-scoped or WAR-scoped cluster nodes on GlassFish Server. See "Configure Cluster Nodes".

3.2.1 Download Oracle Coherence

All of the files supporting Coherence*Web, including ActiveCache for GlassFish, are included in the Coherence distribution. You can get the latest release of Oracle Coherence at this URL:

http://www.oracle.com/technetwork/middleware/coherence/overview/index.html

3.2.2 Set the Session Persistence Type

Create or edit the glassfish-web.xml file in the WEB-INF directory of the Web application. Set the session persistence type for the Web application to be coherence-web, for example:

Example 3-1 Configuring the glassfish-web.xml File for Coherence*Web

<glassfish-web-app> 
   <session-config> 
       <session-manager persistence-type="coherence-web" /> 
   </session-config> 
<glassfish-web-app>

3.2.3 Override the Default Coherence*Web Cache or Cluster Configuration

The session-cache-config.xml file provides the default definition of the session caches and services which Coherence*Web uses to implement HTTP session management. The coherence-web.jar file contains a default session-cache-config.xml file which should satisfy most Web applications. If necessary, you can provide an alternate cache and cluster configuration in your own custom session-cache-config.xml and tangosol-coherence-override.xml file. You must include the file in the WEB-INF/classes directory in the Web application.

3.2.4 Copy the ActiveCache for GlassFish and Session Cache Files to the Application

The coherence-web.jar file provides the functionality for ActiveCache for GlassFish. You must make the coherence-web.jar file available to the applications that you want to run on GlassFish Server.

Copy the coherence-web.jar file to the /WEB-INF/lib/ directory of each Web application that you intend to deploy on GlassFish Server.

3.2.5 Make Your Web Applications Distributable

Your Web application must be configured to run in a distributed environment, such as a server cluster. Add the <distributable/> element to the web.xml deployment descriptor of your Web application. The <distributable/> element is a child of the root <web-app> element. The web.xml file is located in the WEB-INF directory of your Web application.

3.2.6 Configure Coherence*Web

ActiveCache for GlassFish provides a default Coherence*Web configuration that should satisfy most Web applications. The Coherence*Web configuration is defined using <context-param> elements in the web.xml file. The default values can be overridden by adding or editing <context-params> elements in the web.xml file.

Note:

If you make any changes to the Coherence*Web configuration after a Web application has been started, then you must restart the Web application. There are no dynamically updatable configuration options in Coherence*Web.

Table 3-1 describes the default values which ActiveCache for GlassFish provides for Coherence*Web. See Appendix A, "Coherence*Web Context Parameters" for more information about these parameters.

Table 3-1 Default Context Parameter Values Provided by ActiveCache for GlassFish

Parameter Name Description and Default Value

coherence-application-name

The default is ServletContext path + ServletContext name

A consistent and unique string to represent the Web application name.

coherence-cluster-owned

The default is false

Because all Coherence nodes start when the Web application starts, they should also shutdown the Coherence node when the Web application stops.

coherence-reaperdaemon-assume-locality

The default is false

Sessions can be stored on standalone cache servers.

coherence-scopecontroller-class

The default is com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController

coherence-session-locking

The default is false

Session locking is disabled by default. This configuration enables a "last writer wins" policy.

coherence-sessioncollection-class

The default is com.tangosol.coherence.servlet.SplitHttpSessionCollection

SplitHttpSessionCollection is the recommended default model.


Coherence*Web context parameters that configure the session cookie are not honored because GlassFish Server generates and parses the session cookie. Even though Coherence*Web can be configured to enable servlet contexts to be clustered, ActiveCache for GlassFish does not support this functionality.

Table 3-2 describes the Coherence*Web context parameters that are not valid when used with ActiveCache for GlassFish. ActiveCache for GlassFish will return a warning log if these context parameters are present. See Appendix A, "Coherence*Web Context Parameters" for more information about these parameters.

Table 3-2 Coherence*Web Context Parameters that are not Valid for the GlassFish Server

Parameter Name Reason Why it is Not Valid

coherence-distributioncontroller-class

The value for GlassFish Server is com.tangosol.coherence.servlet.glassfish31.GlassFishHybridController.

coherence-preserve-attributes

GlassFish Server caches nonserializable user data in the session.

coherence-session-cookie-domain

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie.

coherence-session-cookie-max-age

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie.

coherence-session-cookie-name

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie.

coherence-session-cookie-path

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie.

coherence-session-cookies-enabled

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie, as well as encoding URLs with session id.

coherence-eventlisteners

This parameter is not valid because ActiveCache for GlassFish automatically registers session event listeners registered in web.xml.

coherence-servletcontext-clustered

This parameter is not valid because Oracle Coherence*Web does not support a clustered ServletContext in ActiveCache for GlassFish.

coherence-session-id-length

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie.

coherence-session-urldecode-bycontainer

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie, as well as encoding and decoding URLs.

coherence-session-urlencode-enabled

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie, as well as encoding URLs with session id.

coherence-session-urlencode-name

This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie, as well as encoding URLs with session id.


Table 3-3 describes the valid session configuration parameters in the glassfish-web.xml file. They are valid because GlassFish creates the session cookie and performs URL encoding in servlets.

Table 3-3 Valid GlassFish Session Configuration Parameters in glassfish-web.xml

Parameter Name Reason Why it is Valid

session-config/cookie-properties/cookieComment

GlassFish generates the session cookie.

session-config/cookie-properties/cookieMaxAgeSeconds

GlassFish generates the session cookie.

session-config/cookie-properties/cookiePath

GlassFish generates the session cookie.

session-config/cookie-properties/cookieSecure

GlassFish generates the session cookie.

session-config/cookie-properties/cookieDomain

GlassFish generates the session cookie.

session-config/session-properties/enableCookies

GlassFish Server generates the session cookie.

session-config/session-properties/enableURLRewriting

GlassFish Server generates the session cookie.

session-config/session-manager/persistence-type

This parameter must be set to coherence-web to enable Coherence*Web.

session-config/session-manager/manager-properties/reap-interval-in-seconds

This value sets the coherence-reaperdaemon-cycle-seconds Coherence*Web configuration parameter. The default for the GlassFish Server is 60 seconds.

session-config/session-properties/timeoutSeconds

This value sets the coherence-session-expire-seconds Coherence*Web configuration parameter. It overrides the equivalent parameter in the web.xml file.


Table 3-4 describes the configuration parameters in the glassfish-web.xml file which are not valid when using ActiveCache for GlassFish. If these parameters are configured in the glassfish-web.xml file, then they are ignored.

Table 3-4 GlassFish Context Parameters that are not Valid for Coherence*Web in glassfish.web.xml

Parameter Name Reason Why it is Not Valid

session-config/session-manager/manager-properties/maxSessions

Coherence*Web controls session management. Because sessions can be shared across applications, it is not possible to count the number of sessions for a specific application.

session-config/session-manager/manager-properties/ persistenceFrequency

Coherence*Web always flushes session data to the cache at the end of a request (although it might do so asynchronously).

session-config/session-manager/manager-properties/sessionFilename

This parameter is relevant only for the file session persistence type.

session-config/session-manager/store-properties/ directory

This parameter is relevant only for the file session persistent type.

session-config/session-manager/store-properties/ persistenceScope

This parameter is relevant only for the GlassFish Server native replicated session persistent type.


3.2.7 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 run either in a dedicated JVM (out-of-process) or within a GlassFish Server instance (in-process). 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.

If you are using an out-of-process topology (storage-disabled GlassFish Server instances and stand alone Coherence cache servers), then start the cache servers first, followed by the GlassFish 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 GlassFish Server startup.

To Start a Stand-Alone Coherence Data Node

  1. Create a script for starting a Coherence data node.

    The following is a sample script that starts a 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-web.jar:<Coherence installation dir>/lib/coherence.jar -Dtangosol.coherence.management.remote=true 
    -Dtangosol.coherence.cacheconfig=session-cache-config.xml 
    -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
    

    You must include coherence-web.jar and coherence.jar on the classpath. For Coherence*Web, use the session-cache-config.xml file as the cache configuration file. This is the file you obtained in "Copy the ActiveCache for GlassFish and Session Cache Files to the Application". 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 for the GlassFish Server and the Coherence cache servers.

    For more information on merging these files, see "Merging Coherence Cache and Session Information" in Integration Guide for Oracle Coherence.

  2. Start one or more Coherence data nodes using the script described in the previous step.

To Start a Storage-Enabled or -Disabled GlassFish Server Instance

By default, a Coherence*Web-enabled GlassFish Server instance starts in storage-disabled mode.

There are several ways to start the GlassFish Server instance in storage-enabled mode. One way is to include the command line property -Dtangosol.coherence.session.localstorage=true in the server startup command.

Another way is to set the local-storage element in the session-cache-config.xml file to true, for example:

...
<local-storage system-property="tangosol.coherence.session.localstorage">true</local-storage>
...

3.2.8 Configure Cluster Nodes

On the GlassFish Server, Coherence*Web can be configured only for EAR- or WAR-scoped cluster nodes. Because of the way that GlassFish Server class loaders work, it is not possible to configure application server-scoped cluster nodes. See "Cluster Node Isolation" for more information on application server-, EAR-, and WAR-scoped cluster nodes.

3.2.8.1 Configuring EAR-Scoped Cluster Nodes

To use Coherence*Web in EAR-scoped cluster nodes:

  1. Copy the coherence.jar and coherence-web.jar files to the WEB-INF/lib directory of each WAR in the EAR file.

  2. Set the session persistence type to coherence-web in the glassfish-web.xml file, as illustrated in Example 3-2.

    Example 3-2 Setting the Persistence Type in the glassfish-web.xml File

    <glassfish-web-app>
       ...
       <session-config>
          <session-manager persistence-type="ccherence-web"/> 
       </session-config> 
    ...
    </glassfish-web-app>   
    
  3. Copy the session cache configuration file session-cache-config.xml to the /WEB-INF/classes/ directory of each WAR file in the EAR file.

3.2.8.2 Configuring WAR-Scoped Cluster Nodes

To use Coherence*Web in WAR-scoped cluster nodes:

  1. Copy the coherence.jar and coherence-web.jar files to the /WEB-INF/lib/ directory of each Web application that you intend to deploy on GlassFish Server.

  2. Set the session persistence type to coherence-web in the glassfish-web.xml file. See Example 3-2.

  3. Copy the session cache configuration file session-cache-config.xml to the /WEB-INF/classes/ directory of each Web application that you intend to deploy on GlassFish Server.

This packaging means that each deployed WAR file will create a Coherence node in the cluster. If you package multiple WAR files in an EAR file, then each WAR file will create a Coherence node in the cluster.