This chapter describes how to configure and deploy Coherence*Web, the session state persistence and management module, for use with GlassFish Server. The functionality that allows Coherence*Web to be used with this application server is contained in the ActiveCache for GlassFish feature.
This chapter contains the following sections:
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.
The current releases of Oracle Coherence and Oracle GlassFish Server provide 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.
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 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 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.
The following steps summarize how to prepare your deployments to use Coherence*Web with applications running on GlassFish Server:
Download Oracle Coherence to your file system. See "Download Oracle Coherence".
Set the session persistence type to coherence-web
for the Web application in glassfish-web.xml
file. See "Set the Session Persistence Type".
(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".
Make the coherence-web.jar
file available to the Web application. See "Copy the ActiveCache for GlassFish and Session Cache Files to the Application".
Edit the web.xml
file to make your Web application available to a server cluster. See "Make Your Web Applications Distributable".
(Optional) Edit the web.xml
file in the WAR deployment if your application requires advanced configuration for Coherence*Web. See "Configure Coherence*Web".
(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".
Package the application. Coherence*Web can be configured for EAR-scoped or WAR-scoped cluster nodes on GlassFish Server. See "Configure Cluster Nodes".
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
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:
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".
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.
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.
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 |
---|---|
|
The default is ServletContext path + ServletContext name A consistent and unique string to represent the Web application name. |
|
The default is Because all Coherence nodes start when the Web application starts, they should also shutdown the Coherence node when the Web application stops. |
|
The default is Sessions can be stored on standalone cache servers. |
|
The default is |
|
The default is Session locking is disabled by default. This configuration enables a "last writer wins" policy. |
|
The default is Session locking is disabled by default. This configuration enables a "last writer wins" policy. |
|
The default is
|
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 |
---|---|
|
The value for GlassFish Server is |
|
GlassFish Server caches nonserializable user data in the session. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie. |
|
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. |
|
This parameter is not valid because ActiveCache for GlassFish automatically registers session event listeners registered in |
|
This parameter is not valid because Coherence*Web does not support a clustered ServletContext in ActiveCache for GlassFish. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie. |
|
This parameter is not valid because GlassFish Server is responsible for generating and parsing the session cookie, as well as encoding and decoding URLs. |
|
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. |
|
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 |
---|---|
|
GlassFish generates the session cookie. |
|
GlassFish generates the session cookie. |
|
GlassFish generates the session cookie. |
|
GlassFish generates the session cookie. |
|
GlassFish generates the session cookie. |
|
GlassFish Server generates the session cookie. |
|
GlassFish Server generates the session cookie. |
|
This parameter must be set to |
|
This value sets the |
|
This value sets the |
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 |
---|---|
|
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. |
|
Coherence*Web always flushes session data to the cache at the end of a request (although it might do so asynchronously). |
|
This parameter is relevant only for the |
|
This parameter is relevant only for the |
|
This parameter is relevant only for the GlassFish 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
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 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 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.
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> ...
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.
To use Coherence*Web in EAR-scoped cluster nodes:
Copy the coherence.jar
and coherence-web.jar
files to the WEB-INF/lib
directory of each WAR in the EAR file.
Set the session persistence type to coherence-web
in the glassfish-web.xml
file, as illustrated in Example 3-2.
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.
To use Coherence*Web in WAR-scoped cluster nodes:
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.
Set the session persistence type to coherence-web
in the glassfish-web.xml
file. See Example 3-2.
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.