Chapter 18
Configuring Session Persistence

This chapter describes how to configure session persistence for Sun^TM Open Net Environment (Sun ONE) Application Server 7, Enterprise Edition.

This chapter includes the following sections:

About Session Persistence
Creating a Session Store
Configuring JDBC Parameters for the HADB Database
Enabling Availability for an Application Server Instance
Disabling Availability for an Application Server Instance
Configuring Session Persistence Options
Specifying JNDI Name of the JDBC Resource for HADB Database
Specifying a Cluster Name for Application Server Instance
Making an Application Distributable
Default Values for Session Persistence
Clearing the Session Store

---

About Session Persistence

As an application session proceeds, there is often data that is part of the session that is not stored in a traditional database. An example of such data is the content of your shopping cart. Sun ONE Application Server provides the capability to save, or persist, this session data in a repository so that if an application server instance experiences a failure, the session state can be recovered and the session can continue without information loss.

Sun ONE Application Server supports persistence of HTTP sessions. Failover of certain J2EE object references that are stored in HTTP sessions is also supported.

The high-availability database (HADB) bundled with the Sun ONE Application Server works as the persistence store to provide high availability for applications.

Note	Appendix B, "Failover Scenarios" describes typical failover scenarios in detail.

This section includes the following topics:

Understanding Persistence Types
Configuring Session Persistence for Application Server Instances and Applications
Failover of J2EE Object References Stored in HTTP Sessions
Basic Session Persistence Configuration Steps

Understanding Persistence Types

The persistence type defines if and how HTTP session persistence and failover take place in the Sun ONE Application Server. The persistence types available are ha, memory, and file.

When you set the persistence type to ha, the HADB is used as the persistence store. The persistence type ha is the persistence type supported for production environments that require HTTP session persistence and failover capabilities.

The memory persistence type provides no failover and is the default persistence type. It is the best choice for production environments that do not require HTTP session persistence and failover capabilities.

In addition, the memory and the file persistence types are useful for development environments where a developer may want to test session persistence and failover without having to install and set up HADB.

The persistence types are described in "Setting the Persistence Type".

Configuring Session Persistence for Application Server Instances and Applications

You can configure session persistence for application server instances in a cluster through the Administration interface or through the command-line interface. These settings will apply to all applications that are deployed on the application server instance.

Note	For changes in session persistence configuration to take effect, you must manually apply the configuration and restart the application server instance. If the instance is currently serving requests, before you restart the instance, you should first quiesce the instance so that the instance gets enough time to serve the requests it is handling. For more information, see "Understanding Quiescing" and "Stopping an Application Server Instance in a Cluster".

For any application, you can specify the session persistence settings through the corresponding sun-web.xml file.

Note	Application-level session persistence configuration takes precedence over the instance-level session persistence configuration. Even if you change the instance-level configuration after an application has been deployed, the settings for the application still override the settings for the application server instance.

You may want to specify the session persistence settings for an application when, for example, the application has specific performance or reliability requirements that other applications deployed on the cluster do not have.

To illustrate, suppose one of the applications, say Application A, deployed on the cluster requires a higher guarantee than other applications that the most up-to-date session state is available. In this case, follow these steps:

Set the persistence frequency through instance-level settings to time-based (meaning that session state is saved at a regular, configurable time interval) through the Administration interface or the command-line interface.

The persistence frequency for all applications deployed on the cluster is now set to time-based.

Change the persistence frequency for Application A to web-method (meaning that the session state is saved at the end of every web request, and therefore, there is the highest guarantee that the most up-to-date session information is available) through the sun-web.xml file.

The persistence frequency for Application A is changed to web-method. The persistence frequency for all other applications remains set to time-based.

For more information on persistence frequency, see "Setting the Persistence Frequency".

Note	Session state will not be consistently failed over in a cluster unless you enable availability and set the persistence type to ha for every instance in the cluster. For more information on enabling availability for application server instances, see "Enabling Availability for an Application Server Instance". For more information on setting the persistence type, see "Setting the Persistence Type".

Note	If you make session persistence configuration changes for an application, you must redeploy the application before the changes can take effect.

Failover of J2EE Object References Stored in HTTP Sessions

Sun ONE Application Server supports failover of J2EE object references that are stored in HTTP Sessions. The Table Object Types Supported for J2EE Web Application Session State Failover provides a list of the supported J2EE object references.

The following conditions apply to the recovery of the J2EE object references:

The recovery can be done only for requests received from web clients. There is no support for failover for requests received from RMI or IIOP clients.
All user-defined objects bound into the session must implement the java.io.Serializable interface or belong to one of the supported J2EE object references types ( see the table Table 18-1).

If an object neither implements java.io.Serializable interface nor belongs to one of the supported J2EE object references types, the object is not persisted. An exception is generated and the stack trace is written to the server log.

If an application references a J2EE component or resource that is located on a different server instance, the reference may be lost.
References to open files or network connections are lost.

For information about how to work around some of these limitations, see Sun ONE Application Server Application Design Guidelines for Storing Session State.

In the following table, the left column specifies the Java Object Type and the right column specifies whether failover support is provided—Yes in the Failover support column means that failover support is provided and No in the Failover Support column means that failover support is not provided.

Table 18-1  Object Types Supported for J2EE Web Application Session State Failover 

Java Object Type	Failover Support Provided
EntityBean local home reference, local object reference	Yes
Stateful SessionBean local home reference	Yes
Stateful SessionBean local object reference	No
Stateless SessionBean local home reference, local object reference	Yes
Co-located EntityBean remote home reference, remote reference	Yes
Co-located Stateful SessionBean remote home reference	Yes
Co-located Stateful SessionBean remote reference	No
Co-located Stateless SessionBean remote home reference, remote reference	Yes
Distributed EntityBean remote home reference, remote reference	No
Distributed Stateful SessionBean remote home reference, remote reference	No
Distributed Stateless SessionBean remote home reference, remote reference	No
JNDI Context	Yes, InitialContext and java:comp/env
UserTransaction	Yes, but if the instance that fails is never restarted, any prepared global transactions are lost and may not be correctly rolled back or committed
JDBC DataSource	No
JMS ConnectionFactory, Destination	No
JavaMail Session	No
Connection Factory	No
Administered Object	No
Web service reference	No
Serializable Java types	Yes

Basic Session Persistence Configuration Steps

For successful session persistence configuration, ensure that these steps are followed in the order in which they are presented because some latter steps have one or more previous steps as prerequisites

Note	Some of these steps can be performed using the clsetup and cladmin commands. The clsetup command is used to automate the process of setting up a basic cluster in a typical configuration. For more information on using the clsetup command, see the Sun ONE Application Server Installation Guide. The cladmin command is used to streamline the process of configuring and administering application server instances in a cluster. For more information on using the cladmin command, see Chapter 19, "Using the cladmin Command.".

.

Create an HADB database for the cluster. This is explained in Chapter 20, "Administering the High-Availability Database".
Create a session store for the session data for the HADB database for each cluster. This is explained in "Creating a Session Store".
Configure the JDBC connection pool settings and specify a JDBC datasource for the HADB database so that the session state for the application server instances in each cluster can be stored correctly. This is explained in "Setting Up the JDBC Connection Pool".”
Enable availability for the application server instances that should support session persistence. This is explained in "Enabling Availability for an Application Server Instance".
Depending on whether you are using a production system and whether you need failover capabilities, specify the persistence type for application server instances or applications. Persistence type essentially defines how and where session data is stored. This is explained in "Setting the Persistence Type".
If you are using the ha persistence type, specify the persistence frequency (how frequently the session is stored) and the persistence scope (how much of the session is stored) for application server instances or applications. This is explained in "Setting the Persistence Frequency" and "Setting the Persistence Scope".
If you want to fine-tune the session persistence configuration, modify additional properties as needed (for example, configure the number of seconds between checks for expired sessions). This is explained in "Configuring Other Session Persistence Properties".
Specify the JNDI name of the JDBC resource that you created for the HADB database. This is explained in "Specifying JNDI Name of the JDBC Resource for HADB Database".
If you are using multiple clusters with a single session store, specify the name of the cluster to which the application server instance belongs. This is explained in "Specifying a Cluster Name for Application Server Instance".
Make distributable each application that should be highly available. This is explained in "Making an Application Distributable".

---

Creating a Session Store

This section explains how to create a session store. This section includes the following topics:

About Creating a Session Store
Creating Session Stores for Multiple Clusters
Using the asadmin create-session-store Command to Create a Session Store

About Creating a Session Store

If you are using HADB as the persistence store, you must create a session store for each cluster to store the session data.

Before you create the session store, you must have created an HADB database. For more information, see Chapter 20, "Administering the High-Availability Database."

Use the asadmin create-session-store command to create the session store for the cluster. This is an asadmin command that is run for the HADB database for the cluster and not for any particular application server instance. You run it only once for each cluster that you set up.

Note	You must run the create-session-store command before accessing any application that needs failover support in a clustered environment. For the create-session-store command to work correctly, the HADB must be running.

Note	The asadmin create-session-store command communicates with the HADB database and not with an application server instance.

Creating Session Stores for Multiple Clusters

If you are creating multiple clusters, create a different session store for each cluster. For more information on using multiple clusters, see "Setting up Multiple Clusters".

You can create the session stores in two ways:

Create the session stores in the same HADB database
Create the session store for each cluster in a separate HADB database

The table here summarizes the advantages and disadvantages of each approach. The left column lists the approach, the middle column lists the advantage(s) of the approach, and the right column lists the disadvantage(s) of the approach.

Table 18-2  Comparison of Approaches for Creating Session Stores for Multiple Clusters 

Approach	Advantage(s)	Disadvantage(s)
Session stores for all clusters are created in the same HADB database.	Less resources (such as machines to host HADB active nodes and spare nodes) are required.	Shutting down the database for maintenance tasks affects all the clusters. More application server instances read from and write to the same HADB database. This might result in a decrease in performance.
Session store for each cluster is created in a separate HADB database.	Shutting down one HADB database for maintenance affects only the cluster associated with that HADB database. There is no disruption in service to other clusters. Lesser number of application server instances read from and write to the same HADB database. This can result in an increase in performance.	More resources (such as machines to host HADB active nodes and spare nodes) are required.

Note	It is recommended that you do not use the same session store for two or more clusters. If, however, you choose to do this, make sure that each cluster is configured with a different cluster name. This is explained in "Specifying a Cluster Name for Application Server Instance".

Using the asadmin create-session-store Command to Create a Session Store

The syntax of the asadmin create-session-store command is as follows:

asadmin create-session-store [--storeurl persistent-store-url --storeuser username [--storepassword userpassword] [--dbsystempassword systempassword]] | [--optionsfile file-name]

This command creates a session store to be used by a particular database user.

storeurl is the URL of the HADB store. To get this URL, use the following HADB command:

hadb_install_dir/bin/hadbm get jdbcURL database_name

where hadb_install_dir is the directory where HADB has been installed and database_name is the name of the HADB store. The default value of database_name is hadb.

The URL will be of the form

jdbc:sun:hadb:host:port,host:port,...

Note	The create-session store command cannot run across firewalls. That is, for the create-session-store command to work, the application server instance and HADB must both be on the same side of a firewall.

The options of the create-session-store command are as follows:

storeuser is the name of the HADB user that has access to the session store. You can provide any name except the name of the HADB system user. The create-session-store command creates this HADB user and gives this user access to the session store.

This is the user name that the application server instance uses to connect to the HADB database through JDBC. Therefore, this is the user name that you must specify when creating the JDBC connection pool for the HADB.

storepassword is the password for the storeuser. The create-session-store command assigns this password to the storeuser when it creates the storeuser.
dbsystempassword is the password for the HADB system user. This is the same password that you specify when you create the HADB database using the command hadbm create.

For more information on using HADB commands, see Chapter 20, "Administering the High-Availability Database."

For more information on command syntax, see the command-line interface help.

For more information on using asadmin, see Appendix A, "Using the Command Line Interface".

You can also specify storeurl, storeuser, storepassword, and dbsystempassword in a file with their corresponding environment variables. You can use the name of this file as the value for the optionsfile option.

The environment variables are listed in the following table. In the table, the left column specifies the option and the right column specifies the corresponding environment variable.

Table 18-3  Environment Variables for the create-session-store Command Options  

Option	Environment Variable
storeurl	AS_ADMIN_STOREURL
storeuser	AS_ADMIN_STOREUSER
storepassword	AS_ADMIN_STOREPASSWORD
dbsystempassword	AS_ADMIN_DBSYSTEMPASSWORD

These environment variables can be set using the asadmin set command. For more information on using the asadmin set command, see Appendix A, "Using the Command Line Interface".

In general, you should be careful while using environment variables for usernames and passwords, as these can viewed by other users relatively easily. A safer approach is to provide the values for these environment variables in a file and correctly set the permissions on this file. Using a file to specify these values can be useful because in this case others cannot find out these values using, for example, commands that give details of the currently running processes.

This file can exist anywhere on your machine. The file must be a standard text file with each name=value pair on a different line. You can specify the location of this file as shown in the example later in the section. Here is an example of name=value pairs specified in a file.

AS_ADMIN_STOREURL = jdbc:sun:hadb:host1:4045,host2:4085

AS_ADMIN_STOREUSER = MyUser

AS_ADMIN_STOREPASSWORD = MyPassword

AS_ADMIN_DBSYSTEMPASSWORD = SuperUserPassword

Example: Creating a Session Store

The following command creates a session store where storeurl is jdbc:sun:hadb:myhost1:4045,myhost2:4085, storeuser is haadmin, storepassword is hapassword, and dbsystempassword is dbhapassword.

asadmin create-session-store --storeurl jdbc:sun:hadb:myhost1:4045,myhost2:4085 --storeuser haadmin --storepassword hapassword --dbsystempassword dbhapassword

Example: Creating a Session Store by Specifying Options in a File

The following command creates a session store as per the options defined in the /space/hadetails.txt file.

asadmin create-session-store --optionsfile /space/hadetails.txt

---

Configuring JDBC Parameters for the HADB Database

You must configure the JDBC connection pool settings and specify a JDBC datasource for the HADB database so that the session state for the application server instances in each cluster can be stored correctly.

For information on how to do this, see "Setting Up the JDBC Connection Pool".

---

Enabling Availability for an Application Server Instance

By default, availability is disabled for application server instances. This is because when you install the Sun ONE Application Server, you may not have configured the HADB, and you need the HADB for availability to work correctly. Once you have configured the HADB, you can enable availability for application server instances.

After you enable availability for an application server instance, session persistence for all the virtual servers and applications in that application server instance is enabled.

To enable availability for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Availability Service tab.
Check the Availability Service Enabled box.
Click the Save button.

To enable availability for the instance using the command-line interface, use the asadmin set command to set for the instance the value of the attribute availability-enabled of the element availability-service to true.

Example: Enabling Availability for an Application Server Instance

The following command enables session persistence for the application server instance server1:

asadmin set --user admin_user [--password admin_password] [--host host] [--port port] server1.availability-service.availabilityEnabled=true

Availability of Single Sign-on Session State

In a single application server instance, once a user is authenticated by an application, the user is not required to reauthenticate individually to other applications running on the same instance. This is called single sign-on. For more information on single sign-on, see "Web Application Deployment".

For this feature to continue to work even when a session fails over to another instance in a cluster, single sign-on information must be persisted to HADB. This is enabled when you enable availability for the application server instance.

Session Availability for Applications Belonging to a Single Sign-On Group

Applications that can be accessed through a single name and password combination constitute a single sign-on group.

For sessions corresponding to applications that are part of a single sign-on group, if one of the sessions times out, other sessions are not invalidated and continue to be available. This is because time out of one session should not affect the availability of other sessions.

As a corollary of this behavior, if a session times out and you try to access the corresponding application from the same browser window that was running the session, you are not required to authenticate again. However, a new session is created.

Take the example of a shopping cart application that is a part of a single sign-on group with two other applications. Assume that the session time out value for the other two applications is higher than the session time out value for the shopping cart application. If your session for the shopping cart application times out and you try to run the shopping cart application from the same browser window that was running the session, you are not required to authenticate again. However, the previous shopping cart is lost, and you will have to create a new shopping cart. The other two applications continue to run as usual even though the session running the shopping cart application has timed out.

Similarly, suppose a session corresponding to any of the other two applications times out. You are not required to authenticate again while connecting to the application from the same browser window in which you were running the session.

Note	This behavior applies only to cases where the session times out. If single sign-on is enabled and you invalidate one of the sessions using HttpSession.invalidate(), the sessions for all applications belonging to the single sign-on group are invalidated. If you try to access any application belonging to the single sign-on group, you are required to authenticate again, and a new session is created for the client accessing the application.

---

Disabling Availability for an Application Server Instance

If you disable availability for an application server instance, session persistence for all the virtual servers and applications in that application server instance is disabled. Persistence of single sign-on session state is also disabled for the application server instance.

Note	By default, session persistence is disabled for application server instances.

To disable high availability for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the server instance, open the Containers component.
Click Web Container.
Click the Availability Service tab under General.
Uncheck the Availability Service Enabled box.
Click the Save button.

To disable availability for the instance using the command-line interface, use the asadmin set command to set for the instance the value of the attribute availability-enabled of the element availability-service to false.

Example: Disabling availability for an Application Server Instance

In the following example, session persistence has been disabled for an application server instance called server1.

set server1.availability-service.availability-enabled=false

---

Configuring Session Persistence Options

You can configure session persistence for the Sun ONE Application Server to balance your particular needs for performance, reliability, and high availability. For example, every time your data is saved, you can store the entire session, or you can store the session only if the session has been modified. Or, you can configure the persistence setting so that only the modified attributes of the session are stored. Similarly you can choose whether the session is stored at the end of every web request (thus providing high availability and reliability of updated session states), or you can choose to store the session after a time interval you specify (thus providing a better performance).

You can specify the instance-level settings through the Administration interface or through the command-line configure-session-persistence command.

If you want an application to have its own session persistence settings, you can override the instance-level settings by setting the corresponding configuration for the application in the corresponding sun-web.xml file.

Note	The session persistence configuration must be identical for a given application across all instances of a cluster. Do not deploy an application with one set of settings to one segment of instances in a cluster and another set of settings to another segment of instances in the cluster.

This section includes the following topics:

About the configure-session-persistence Command
Setting the Persistence Type
Comparison of Persistence Type Options
Setting the Persistence Frequency
Comparison of Persistence Frequency Options
Setting the Persistence Scope
Comparison of Persistence Scope Options
Configuring Other Session Persistence Properties

About the configure-session-persistence Command

To specify the session persistence options for the application server instance, in addition to using the Administration interface, you can use the configure-session-persistence command. The syntax of the configure-session-persistence command is as follows:

asadmin configure-session-persistence standard-options [ --type persistence-type ] [ --frequency frequency ] [ --scope scope ] [ --store jdbc-resource-jndi-name ] [ --property name=value[:name=value]* ] instance_name

type is the persistence type that defines the location where session data is stored. Persistence type is explained in the section "Setting the Persistence Type".
frequency is the persistence frequency at which the session is stored. Persistence frequency is explained in the section "Setting the Persistence Frequency".
scope is the amount of session that is stored. Persistence scope is explained in the section "Setting the Persistence Scope".
jdbc-resource-jndi-name is the JNDI name of the JDBC resource that you specified for the HADB database. For more information, see "Configuring JDBC Parameters for the HADB Database".
property option is used to fine-tune other properties for configuring session persistence. For more information, see "Configuring Other Session Persistence Properties".
instance_name is the name of the application server instance for which you are configuring the session persistence.

For more information on command syntax, see the command-line interface help.

For more information on using the asadmin command, see Appendix , "Using the Command Line Interface," on .

Using cladmin Command to Configure Session Persistence

You can use the cladmin command to configure session persistence for all instances in the cluster as follows:

./cladmin [--instancefile instance_file_location] [--passwordfile password_file_location] configure-session-persistence [ --type persistence-type ] [ --frequency frequency ] [ --scope scope ] [ --store jdbc-resource-jndi-name ] [ --property name=value[:name=value]* ]

where:

instance_file_location is the location of the clinstance.conf file
password_file_location is the location of the clpassword.conf file

If the clinstance.conf and the clpassword.conf files are located in the configuration directory of the Sun ONE Application Server (by default etc/opt/SUNWappserver7), you can omit the instancefile and passwordfile options.

For more information on the cladmin command, see Chapter 19, "Using the cladmin Command."

Setting the Persistence Type

The persistence type setting defines the location where the session state is stored. You can choose one of the three options available:

ha
memory
file

Note	Only the ha persistence type is supported for production systems that require failover of session state.

Information about these persistence types is provided in the subsequent sections. A comparison of the persistence types and the configuration options that they support is provided in "Comparison of Persistence Type Options".

Setting the Persistence Type to ha

The persistence type ha lets you store session data in the HADB database. This is the persistence type that you must use to enable failover of session state between application server instances in a cluster. This is the only persistence type supported for production systems that require HTTP session persistence and failover of session state.

In this persistence type, the session state for each application server instance in a cluster is stored in the HADB database. The session state for each instance in a cluster is available to all other instances in the cluster. Therefore, if an instance in a cluster becomes unavailable, other instances in the cluster can continue to serve the sessions that the instance that became unavailable was serving.

Here are the details of what happens when an application server instance in a cluster becomes unavailable.

The load balancer keeps monitoring all application server instances to check if they are available. If an instance becomes unavailable, the load balancer marks the instance as unavailable.

For more information on monitoring, see "Monitoring the Load Balancer Plug-in".

The load balancer stops sending any unassigned requests to the unavailable instance. An unassigned request is a request for a new session. For more information, see "Understanding Assigned Requests and Unassigned Requests".
Requests that were sent to the application server instance but that were not serviced are lost and an error is returned to the client.
All subsequent requests for sessions assigned to the application server instance are failed over to other instances in the cluster.

For more information about clusters, see Chapter 17, "Managing Clusters."

When you use the ha persistence type, you must also configure correctly the persistence frequency (to specify the frequency at which the session data is stored) and the persistence scope (to specify how much of the session is stored). For more information on setting the persistence frequency, see "Setting the Persistence Frequency". For more information on setting the persistence scope, see "Setting the Persistence Scope".

To set the persistence type to ha for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
From the drop-down list under General, select ha.

To set the persistence type to ha using the command-line interface, specify the value ha for the type option of the configure-session-persistence command.

Example: Setting the Persistence Type to ha for an Instance

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency web-method --scope modified-session --store jdbc_hastore instance1

To set the persistence type to ha for an application, in the sun-web.xml file, set the value of the attribute persistence-type of the element session-manager to ha.

Example: Setting the Persistence Type to ha for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="ha">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Setting the Persistence Type to memory

If session persistence for the application server instance is disabled, then memory is the default persistence type.

The memory persistence type provides no session persistence in a clustered environment.

However, for a single application server instance, you can configure the memory persistence type so that before a regular shutdown of the instance, all session state is written to a file. To enable this, you must specify the directory in which you want the session state to be stored in case of shutdown. You specify the directory by providing the path of the directory as the value for the sessionFilename property of session-manager in the server.xml file. For more information on setting the value of sessionFilename, see "Configuring Other Session Persistence Properties".

If the application server instance becomes unavailable unexpectedly, the corresponding session state stored in the file is lost, and therefore, in case of unexpected shutdown of an application server instance, the instance cannot recover the session state.

Note	The limited failover capabilities offered by the memory persistence type are intended for use only in development systems. The memory persistence type is not intended—and not supported—for use in production systems where HTTP session persistence and failover capabilities are required. However, the memory persistence type is the best choice for production environments that do not require HTTP session persistence and failover capabilities.

Note	You cannot choose the configuration of persistence frequency and persistence scope for the memory persistence type.

To set the persistence type to memory for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
From the drop-down list under General, select memory.

To set the persistence type to memory for an application server instance using the command-line interface, specify the value memory for the type option of the configure-session-persistence command.

Example: Setting the Persistence Type to memory for an Instance

asadmin configure-session-persistence --user admin --password Mypassword --host localhost --port 4848 --type memory instance1

To set the persistence type to memory for an application, in the sun-web.xml file for the application, set the value of the attribute persistence-type of the element session-manager to memory.

Example: Setting the Persistence Type to memory for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Setting the Persistence Type to file

The file persistence type provides no session persistence in a clustered environment.

For an application server instance, you can use the file persistence type to store session state in a file. The Sun ONE application server stores information for each session in a separate file. You do not have to specify the path of these files. You can change the path where these files are written. For more information, see Table 18-8.

If the instance becomes unavailable and restarts, it can recover the session state that was last written to the files.

The session state is stored periodically to the files when the background thread that triggers the storage runs. This means that you may experience some loss of session data when a graceful shutdown or unexpected shutdown of the instance occurs.

You can configure the frequency at which the background thread runs by setting the reapIntervalSeconds property of the manager-properties element in the server.xml file (for instance-level configuration) or in the sun-web.xml file (for application-level configuration). For more information, see "Configuring Other Session Persistence Properties".

Note	The limited failover capabilities offered by the file persistence type are intended for use only in development systems. The file persistence type is not intended—and not supported—for use in production systems where HTTP session persistence and failover capabilities are required.

A possible use of the file persistence type is in a development environment to simulate failover during development without having to run HADB.

Note	You cannot choose the configuration of persistence frequency and persistence scope for the file persistence type.

To set the persistence type to file for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
From the drop-down list under General, select file.

To set the persistence type to file using the command-line interface, specify the value file for the type option of the configure-session-persistence command.

Example: Setting the Persistence Type to file for an Instance

asadmin configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type file instance1

To set the persistence type to file for an application, in the sun-web.xml file, set the value of the attribute persistence-type of the element session-manager to file.

Example: Setting the Persistence Type to file for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="file">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Comparison of Persistence Type Options

The table here provides a comparison of and the supported combinations for the persistence type option. The leftmost column lists the persistence type option, the next column lists whether this option is intended or supported for failover in production systems, the next column lists the typical use of the option, the next column lists the persistence frequency option(s) that the option supports, and the rightmost column lists the persistence scope option(s) that the option supports.

Table 18-4  Comparison of Persistence Type Options   

Persistence Type Option	Intended or Supported for Failover in Production Systems	Typical Use	Persistence Frequency Supported	Persistence Scope Supported
memory	No	In development systems In production systems where no failover capabilities are needed	Not applicable	Not applicable
file	No	In development systems, including to simulate failover during development without having to run HADB.	time-based	Not applicable
ha	Yes	In production systems where failover capabilities are required.	time-based web-method	session modified-session modified-attribute

If there is an invalid configuration, the persistence type is set to memory and the application continues to run. A message about the invalid configuration is logged.

Setting the Persistence Frequency

If you are using HADB to store session state, then depending on your requirements of high availability and performance, you can configure the frequency at which the session state is stored in the HADB database. You must choose one of two options available:

web-method
time-based

Note	You can choose the persistence frequency for only the ha persistence type.

Setting the Persistence Frequency to web-method

In the web-method persistence frequency, the session is stored at the end of every web request.

This mode is useful when there is a need for high availability of updated session state. This method provides the highest guarantee that session state will be available after instance failure.

To set the persistence frequency to web-method for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
Click the Properties button under Properties.
In the Name field, type the following:

persistenceFrequency

In the Value field, type the following:

web-method

To set the persistence frequency to web-method using the command-line interface, specify the value web-method for the frequency option of the configure-session-persistence command.

Example: Setting the Persistence Frequency to web-method for an Instance

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency web-method --scope modified-session --store jdbc_hastore instance1

To set the persistence frequency to web-method for an application, in the sun-web.xml file, in manager-properties, set the value of the property persistenceFrequency to web-method.

Example: Setting the Persistence Frequency to web-method for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Setting the Persistence Frequency to time-based

In the time-based persistence frequency, the session state is stored at time intervals defined in the reapIntervalSeconds property of the manager-properties element in the server.xml file (for instance-level configuration) or in the sun-web.xml file (for application-level configuration).

For more information on setting the value of reapIntervalSeconds, see "Configuring Other Session Persistence Properties".

The time-based persistence frequency provides a relatively high guarantee (but not as high as the web-method frequency type) that session state will be highly available. Because the session is stored after a configurable time interval and not after every web request, a better response time is achieved.

The trade off in using the time-based persistence frequency is that there is a small risk that any changes to session state that occurred since the last time the session was stored will be lost if an instance failure occurs.

To set the persistence frequency to time-based for an application server instance using the Administration interface:

In the Administration interface, in the left pane, for the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
Click the Properties button under Properties.
In the Name field, type the following:

persistenceFrequency

In the Value field, type the following:

time-based

To set the persistence frequency to time-based using the command-line interface, specify the value time-based for the frequency option of the configure-session-persistence command.

Example: Setting the Persistence Frequency to time-based for an Instance

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency time-based --scope modified-session --store jdbc_hastore instance1

To set the persistence frequency to time-based for an application, in the sun-web.xml file, set the value of the property persistenceFrequency of the manager-properties element to time-based.

Example: Setting the Persistence Frequency to time-based for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="time-based"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Comparison of Persistence Frequency Options

The table here summarizes the advantages and disadvantages of the persistence frequency options. The left column lists the persistence frequency option, the middle column lists the advantage of the option, and the right column lists the possible disadvantage of the option.

Table 18-5  Comparison of Persistence Frequency Options   

Persistence Frequency Option	Advantage(s)	Disadvantage(s)
web-method	Guarantees that the most up-to-date session state is available.	Potentially increased response time and reduced throughput.
time-based	Better response time and potentially better throughput.	Less guarantee than the web-method persistence frequency that the most updated session state is available after the failure of an application server instance.

Setting the Persistence Scope

If you are using HADB as the persistence store, you must set the persistence scope to configure the amount of session state that should be stored. You must choose one of the three options available:

modified-session. The session is saved only if it has been modified.
session. The entire session is saved every time session state is saved to the HADB database.
modified-attribute. Only the modified attributes of the session are saved.

These options are described in the following topics:

Setting the Persistence Scope to modified-session
Setting the Persistence Scope to session
Setting the Persistence Scope to modified-attribute

Note	You can choose the persistence scope only for the ha persistence type.

Setting the Persistence Scope to modified-session

In the modified-session mode, the session is stored only if it has been modified. Thus, if the persistence frequency is web-method, the entire session is stored at the end of every web request, just before sending a response back to the client only if the session has changed from the last time it was stored. Similarly, if the persistence frequency is time-based, the entire session is stored after each time-based frequency that you specify only if the session has changed from the last time it was stored.

A session is considered to be modified only if the setAttribute method (if the attribute was changed) or the removeAttribute method (if the attribute was removed) was invoked on the session during the execution of a web method (typically doGet or doPost).

To set the persistence scope to modified-session for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
Click the Properties button under Session Store Properties.
In the Name field, type the following:

persistenceScope

In the Value field, type the following:

modified-session

To set the persistence scope to modified-session using the command-line interface, specify the value modified-session for the scope option of the configure-session-persistence command.

Example: Setting the Persistence Scope to modified-session for an Instance

asadmin configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency web-method --scope modified-session --store jdbc_hastore instance1

To set the scope mode to modified-session for an application, in the sun-web.xml file, set the value of the property persistenceScope of the store-properties element to modified-session.

Example: Setting the Persistence Scope to modified-session for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="modified-session"/>

  </store-properties>

</session-manager>

Setting the Persistence Scope to session

In the session persistence scope, the entire session is stored every time. Thus, if the persistence frequency is web-method, the entire session is stored at the end of every web request, just before sending a response back to the client. Similarly, if the persistence frequency is time-based, the entire session is stored after each time-based frequency that you specify.

If an application does not call setAttribute or removeAttribute every time an attribute has changed, the other persistence scope options cannot be used and the persistence scope session is the only available option.

To set the persistence scope to session for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
Click the Properties button under Session Store Properties.
In the Name field, type the following:

persistenceScope

In the Value field, type the following:

session

To set the persistence scope to session using the command-line interface, specify the value session for the scope option of the configure-session-persistence command.

Example: Setting the Persistence Scope to Session

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency web-method --scope session --store jdbc_hastore instance1

To set the scope mode to session for an application, in the sun-web.xml file, set the value of the persistenceScope property of the store-properties element to session.

Example: Setting the Persistence Scope to session for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="session"/>

  </store-properties>

</session-manager>

Setting the Persistence Scope to modified-attribute

In the modified-attribute persistence scope, only those attributes are stored that have been modified (inserted, updated, or deleted) since the last time the session was stored. Using this mode can improve the throughput and response time significantly for applications for which only a small portion of the session state is modified for any given request.

Note	The persistence scope modified-attribute is not certified as a full production-quality feature. If you use this persistence scope, evaluate the performance and stability of the Sun ONE Application Server in expected peak load conditions. If exceptions are logged or the response time is more than that is acceptable, do not use this persistence scope for your production environment.

If you use the modified-attribute persistence scope, your application must follow these guidelines:

Call setAttribute or removeAttribute every time you modify the session state.
Make sure there are no cross references between attributes.

This is because the object graphs under each distinct attribute key will be serialized and stored separately and if there are any object cross reference between the objects under each separate key, they will not get serialized and deserialized correctly.

Distribute the session state across multiple attributes, or at least between a read-only attribute and a modifiable attribute.

To set the persistence scope to modified-attribute for an application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Session Manager tab.
Click the Properties button under Session Store Properties.
In the Name field, type the following:

persistenceScope

In the Value field, type the following:

modified-attribute

To set the persistence scope to modified-attribute using the command-line interface, specify the value modified-attribute for the scope option of the configure-session-persistence command.

Example: Setting the Persistence Scope to modified-attribute for an Instance

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --frequency web-method --scope modified-attribute --store jdbc_hastore instance1

To set the scope mode to modified-attribute for an application, in the sun-web.xml file, set the value of the persistenceScope property of the store-properties element to modified-attribute.

Example: Setting the Persistence Scope to modified-attribute for an Application

The example here provides extracts from a sample sun-web.xml file. The relevant portion has been highlighted.

<session-manager persistence-type="memory">

  <manager-properties>

    <property name="persistenceFrequency" value="web-method"/>

  </manager-properties>

  <store-properties>

    <property name="persistenceScope" value="modified-attribute"/>

  </store-properties>

</session-manager>

Comparison of Persistence Scope Options

The table here summarizes the advantages and disadvantages of the persistence scope options. The left column lists the persistence scope option, the middle column lists the advantage(s) of the option, and the right column lists the possible disadvantage(s) of the option.

Table 18-6  Comparison of Persistence Scope Options   

Persistence Scope Option	Advantage(s)	Disadvantage(s)
modified-session	Provides improved response time for requests that do not modify session state.	Your application must call the setAttribute method (if the attribute was changed) or the removeAttribute method (if the attribute was removed) on the session during the execution of a web method (typically doGet or doPost).
session	No constraint on applications.	Potentially degraded throughput and response time as compared to the modified-session and the modified-atttribute options.
modified-attribute	Better throughput and response time for requests in which the percentage of session state modified is low.	1.  As the percentage of session state that gets modified for a given request grows to around 60%, the throughput and the response time degrade. In such cases, the performance gets worse than the session or modified-session persistence scope because of the overhead of splitting the attributes into separate records. 2.  Your application must be written to meet the following constraints required by this mode: Call setAttribute or removeAttribute every time you modify the session state. Make sure there are no cross references between attributes. Distribute the session state across multiple attributes, or at least between a read-only attribute and a modifiable attribute.

Configuring Other Session Persistence Properties

To fine tune the session persistence behavior, you can modify properties of the manager-properties and of store-properties subelements of the session-manager element in the server.xml file (for instance-level configuration) or in the sun-web.xml file (for application-level configuration). You can modify these properties using the asadmin set command. These properties are explained here in the tables Table 18-7 and Table 18-8. In the tables, the left column specifies the name of the property, the middle column specifies the default value of the property, and the right column provides a description of the property.

Table 18-7  manager-properties properties Configurable for Session Persistence  

Name of the Property	Default Value	Description
reapIntervalSeconds	60	Specifies the number of seconds between checks for expired sessions. This is also the frequency at which passivation of sessions occurs. If the persistence type is file or ha, sessions are passivated if maxSessions has been exceeded. If persistence frequency is time-based, active sessions are stored at this interval.
maxSessions	-1	Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this limit is reached: If the persistence type is memory, an attempt to create a new session causes an IllegalStateException to be thrown. If the persistence-type is file or ha, the sessions are passivated to the persistent store.
sessionFilename	none; state is not preserved across restarts	Specifies the absolute or relative path to the directory in which the session state is preserved between application restarts, if preserving the state is possible. A relative path is relative to the temporary directory for this application. Applicable only if the persistence-type is memory.

Table 18-8  store-properties Configurable for Session Persistence 

Property Name	Default Value	Description
directory	instance_dir/generated/jsp/j2ee-apps/appname/appname_war	Specifies the absolute or relative path to the directory into which individual session files are written. A relative path is relative to the temporary work directory for this application. Applicable only if the persistence type is file.

Example: Setting the maxSessions and reapIntervalSeconds Properties

In the following example, the value of maxSessions has been set to 1000 and the value of reapIntervalSeconds has been set to 60.

configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --property maxSessions=1000:reapIntervalSeconds=60 instance1

---

Specifying JNDI Name of the JDBC Resource for HADB Database

While configuring session persistence, you must specify the JNDI name of the JDBC resource that you create for the HADB database. If you use HADB as the persistence store, this information is used to connect to the HADB database.

Note	If you have used the configure-session-persistence command to configure the session persistence, you would have already specified the JNDI name for the --store option and you do not need to specify it again.

To specify the JNDI name of the JDBC resource that you create for the HADB database using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Availability Service tab.
Click Properties under Persistence Store Properties.
In the Name field, type the following:

store-pool-jndi-name

In the Value field, type the JNDI name of the JDBC Resource that you created for the HADB database while configuring the JDBC parameters for the HADB database. For more information, see Chapter 20, "Administering the High-Availability Database."

To specify the JNDI name of the JDBC resource using the command-line interface, set the value of the store-pool-jndi-name property for the instance to the value of the JNDI name of the JDBC URL as shown in the example here:

Example: Specifying the JNDI Name of the JDBC Resource for HADB

set instance1.availability-service.persistence-store.property.store-pool-jndi-name = jdbc_ha

In this example, instance1 is the name of the application server instance and jdbc_ha is the value of the JNDI name of the JDBC URL as that you created while configuring the JDBC parameters for the HADB database. For more information on configuring the JDBC parameters, see "Configuring the HADB".

---

Specifying a Cluster Name for Application Server Instance

It is recommended that you do not use the same session store for two or more clusters. If, however, you choose to do this, make sure that each cluster is configured with a different cluster name.

To configure each cluster with a different cluster name, for each application server instance in these clusters, specify the name of the cluster to which the instance belongs.

Note	If you are using a separate HADB database for each cluster, or if you are using a separate session store within the same HADB database for each cluster, you do not need to perform this step.

For example, if you are using the same session store for two clusters, you can specify the name cluster1 for instances in the first cluster and the name cluster2 for instances in the second cluster.

Note	The name of the cluster need not be the same as the name of the cluster as specified in the loadbalancer.xml file.

To specify the name of the cluster for the application server instance using the Administration interface:

In the left pane of the Administration interface, under the application server instance, open the Containers component.
Click Web Container.
Click the Availability Service tab.
Click Properties under Persistence Store Properties.
In the Name field, type the following:

cluster-id

In the Value field, type the name of the cluster for the application server instance.

For more information on clusters, see Chapter 17, "Managing Clusters."

To specify the name of the cluster using the command-line interface, set the value of the cluster-id property for the instance to the name of the cluster.

Example: Specifying the Cluster Name for an Instance

In the following example, the cluster name cluster2 has been specified for an application server instance called instance1.

set instance1.availability-service.persistence-store.property.cluster-id = cluster2

---

Making an Application Distributable

For session persistence to work for an application, the application must be distributable.

To make an application distributable, in the corresponding web.xml file, specify the distributable sub-element for the web-app element.

Example: Making an Application Distributable

The example here provides extracts from a sample web.xml file. The relevant portion has been highlighted.

<web-app>

  <display-name>webapps-simple</display-name>

  <description>

  A sample application.

  </description>

  <distributable></distributable>

  <servlet>

    <servlet-name>HelloWorldExample</servlet-name>                <servlet-class>samples.webapps.simple.servlet.HelloWorldExample

        </servlet-class>

  </servlet>

  <servlet-mapping>

    <servlet-name>HelloWorldExample</servlet-name>   <url-pattern>/helloworld</url-pattern>

  </servlet-mapping>

</web-app>

To be distributable, an application must also conform to the behavior and rules prescribed for a distributable application as per Java Servlet Specification 7.7.2. For more information, see Java Servlet Specification, v2.3.

If the web-app element of the web.xml file does not have the distributable sub-element specified, the application is called a non-distributable application. A non-distributable application cannot be configured for high availability.

---

Default Values for Session Persistence

If high availability is disabled, persistence type is set to memory. If high availability is enabled, persistence type is set to ha. If no further configuration exists either at the instance-level or at the application level, then the default session persistence configuration is as follows:

Persistence type is set to ha.
Persistence frequency is set to web-method.
Persistence scope is set to session.

This default can be overridden by any other persistence configuration, either for an application server instance or for an application.

---

Clearing the Session Store

Sometimes you may want to clear the sessions for all application server instances from the HADB database. This may be needed for example when the application server instance has shut down abruptly and there are many sessions in the HADB database that contain data no longer required. To clear all the sessions from the HADB database, use the asadmin clear-session-store command.

Caution	The clear-session-store command removes all sessions, including passivated sessions, from the HADB database.

This section contains the following topics:

Before You Clear the Session Store
Using the asadmin clear-session-store Command
After You Clear the Session Store

Before You Clear the Session Store

You should not use the asadmin clear-session-store command if any application server instances in the cluster are persisting session data to the HADB database.

Therefore, before you can use the asadmin clear-session-store command, disable high availability for all instances in the cluster as explained in "Disabling Availability for an Application Server Instance".

Using the asadmin clear-session-store Command

The syntax of the asadmin clear-session-store command is as follows:

asadmin clear-session-store [--storeurl persistent-store-url] [--storeuser username] [--storepassword userpassword] [--optionsfile file_name]

The values of storeurl, storeuser, and storepassword are the same as explained in "Creating a Session Store".

For more information on using HADB commands, see Chapter 20, "Administering the High-Availability Database."

For more information on command syntax, see the command-line interface help.

For more information on using asadmin, see Appendix A, "Using the Command Line Interface."

You can also specify storeurl, storeuser and storepassword in a file with their corresponding environment variables. The name of the file can be used as the value for the optionsfile option. The environment variables are described in the following table. In the table, the left column specifies the option and the right column specifies the corresponding environment variable.

Table 18-9  Environment Variables for the create-session-store Command Options

Option	Environment variable
--storeurl	AS_ADMIN_STOREURL
--storeuser	AS_ADMIN_STOREUSER
--storepassword	AS_ADMIN_STOREPASSWORD

The file must be a standard text file with each name=value pair on a different line. You can specify the location of this file as shown in the example later in the section. Here is an example of name=value pairs specified in a file.

AS_ADMIN_STOREURL = jdbc:sun:hadb:host1:4045,host2:4085

AS_ADMIN_STOREUSER = MyUser

AS_ADMIN_STOREPASSWORD = MyPassword

Example: Removing All Sessions from the HADB Database

In the following example, the storeurl is jdbc:sun:hadb:myhost1:7676,myhost2:6767, the storeuser is haadmin, the storepassword is hapassword, and the dbstorepassword is dbhapassword.

asadmin clear-session-store --storeurl jdbc:sun:hadb:myhost1:4045,myhost2:4085 --storeuser haadmin --storepassword hapassword --dbstorepassword dbhapassword

Example: Removing All Sessions from the HADB Database by Specifying the Required options in a File

The following command removes all the sessions in the persistence store according to the options defined in the file /space/hadetails.txt.

asadmin clear-session-store --optionsfile /space/hadbdetails.txt

After You Clear the Session Store

Once the session is restored, enable availability for all instances in the cluster as explained in "Enabling Availability for an Application Server Instance".

Previous      Contents      Index      Next

---

Copyright 2003 Sun Microsystems, Inc. All rights reserved.