3 Using Coherence*Web with GlassFish Server

This chapter describes how to configure and deploy Coherence*Web, the session state persistence and management module, for use with GlassFish Server.

This chapter contains the following sections:

• Overview of GlassFish Server

• Overview of Coherence*Web on GlassFish

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

3.1 Overview of 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.

3.2 Overview of Coherence*Web on GlassFish

Coherence*Web provides 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 the current release, the WebInstaller pre-processing step is not required for GlassFish 3.1 applications.

Functionality for GlassFish is provided in the coherence-web.jar file which can be found in the coherence/lib folder. Coherence cache configurations and services for GlassFish are defined in the default-session-cache-config.xml file, which can be found in the coherence-web.jar file. The default cache and services configuration defined in the default-session-cache-config.xml file should satisfy most Web applications.

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 Coherence*Web 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. On GlassFish Servers, Coherence*Web 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. 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.3 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 default-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 Coherence*Web 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.3.1 Download Oracle Coherence

All of the files supporting Coherence*Web 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.3.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.3.3 Override the Default Coherence*Web Cache or Cluster Configuration

The default-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 default-session-cache-config.xml file contained in the coherence-web.jar file should satisfy most Web applications. If necessary, you can provide an alternate cache and cluster configuration in your own custom session cache configuration file and tangosol-coherence-override.xml file. You must include the file in the WEB-INF/classes directory in the Web application.

For information on specifying the name of the custom session cache configuration file, see "Customizing the Name of the Session Cache Configuration File".

3.3.4 Copy the Coherence*Web and Session Cache Files to the Application

The coherence-web.jar file provides the functionality for Coherence*Web on 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.3.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.3.6 Configure Coherence*Web

Coherence*Web provides a default 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 provided for Coherence*Web on GlassFish Servers. See Appendix A, "Coherence*Web Context Parameters" for more information about these parameters.

Table 3-1 Default Context Parameter Values Provided by Coherence*Web

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-session-locking-mode	The default is none. 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, GlassFish does not support this functionality.

Table 3-2 describes the Coherence*Web context parameters that are not valid when used with GlassFish. 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 Coherence*Web on GlassFish automatically registers session event listeners registered in web.xml.
coherence-servletcontext-clustered	This parameter is not valid because Coherence*Web does not support a clustered ServletContext in Coherence*Web 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 Coherence*Web on 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.3.7 Start a Cache Server

A Coherence 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 Cache Server

1. Create a script for starting a Coherence cache server.

   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 Oracle Fusion Middleware Developing Applications with Oracle Coherence for more information.

   java -server -Xms512m -Xmx512m 
   -cp <Coherence installation dir>/lib/coherence-web.jar:<Coherence installation dir>/lib/coherence.jar -Dtangosol.coherence.management.remote=true 
   -Dtangosol.coherence.cacheconfig=default-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 default-session-cache-config.xml file as the cache configuration file. This is the file you obtained in "Copy the Coherence*Web 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 default-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 Oracle Fusion Middleware Integrating Oracle Coherence.

2. Start one or more Coherence cache servers 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 default-session-cache-config.xml file to true, for example:

...
<local-storage>true</local-storage>
...

3.3.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.3.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="coherence-web"/> 
      </session-config> 
   ...
   </glassfish-web-app>   
   

3. Copy the session cache configuration file default-session-cache-config.xml to the /WEB-INF/classes/ directory of each WAR file in the EAR file.

3.3.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 default-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.