|
| |
| Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Update 3 Administration Guide | |
Chapter 20
Configuring Session Persistence (Enterprise Edition)This chapter describes how to configure session persistence for stateful session beans (SFSBs) in the Sun Java™ System Application Server Enterprise Edition 7 environment.
This chapter includes the following sections:
About Session PersistenceAs an application session proceeds, there is often data that is part of a session that is not stored in a traditional database. An example of such data is the content of a shopping cart. Sun Java System 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.
In J2EE applications, session data is typically stored in HTTP sessions or SFSB sessions. Sun Java System Application Server supports persistence of the state of both HTTP sessions and SFSB sessions. Failover of certain J2EE object references that are stored in both HTTP sessions and SFSB sessions is also supported; see Table 20-3.
The high-availability database (HADB) bundled with the Sun Java System Application Server works as the persistence store to provide high availability for session data.
Note
Appendix B, "Failover Scenarios (Enterprise Edition)" describes typical failover scenarios in detail.
Basic Session Persistence Configuration StepsFor successful session persistence configuration, ensure that these steps are followed in the order in which they are presented because some later 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 Java System 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 Appendix F, "Using the cladmin Command for Administration (Enterprise Edition)" and Using the cladmin Command to Configure Session Persistence for an Entire Cluster.
- Create an HADB database for the cluster. This is explained in Chapter 21, "Administering the High-Availability Database on Unix(Enterprise Edition)".
- Configure the JDBC connection pool settings and specify a JDBC datasource for the cluster so that the session states for the applications deployed to the cluster can be stored correctly. This is explained in Setting Up the JDBC Connection Pool.
- Specify the JNDI name of the JDBC resource that you created for the HADB database. This is explained in Referencing the HADB Database’s JDBC Resource.
- Create a session store for the session data for the HADB database for each cluster. This is explained in Creating the Session Store.
- Decide if you are using a single cluster or multiple clusters with a single session store. This is explained in Managing the Session Store for Clusters.
- Enable availability for the application server instances, web or EJB containers, applications, and modules that should support session persistence. This is explained in Enabling and Disabling Availability.
- Enable availability for any specific SFSBs that require it, and select methods for which checkpointing the session state is necessary. This is explained in the Developer’s Guide to Enterprise JavaBeans Technology.
- If you are not enabling availability, you can change the file system session store for SFSBs if desired. This is explained in Setting the SFSB Session Store When Availability is Disabled.
- 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 HTTP session data is stored. This is explained in Setting the Persistence Type.
- If you are using the ha persistence type for HTTP sessions, 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 web applications. This is explained in Setting the Persistence Frequency and Setting the Persistence Scope.
- If you want to fine-tune the HTTP 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 HTTP Session Persistence Properties.
- Make distributable each application that should be highly available. This is explained in Making a Web Application Distributable.
- Restart each server instance.
Note
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 Disabling and Quiescing an Application Server Instance in a Cluster and Stopping an Application Server Instance in a Cluster.
Setting Up AvailabilityTo set up availability, you must reference the HADB database, create a session store, and enable availability. This section includes the following topics:
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.
Referencing the HADB Database’s JDBC Resource
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.
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 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 21, "Administering the High-Availability Database on Unix(Enterprise Edition)."
- Click on the OK button.
- Go to the server instance page.
- Apply Changes and restart the server.
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.
Creating the Session Store
The asadmin create-session-store command creates a session store to be used by a particular database user. The syntax is as follows:
asadmin create-session-store [--storeurl persistent-store-url --storeuser username [--storepassword userpassword] [--dbsystempassword systempassword]] | [--optionsfile file-name]
Note
The asadmin create-session-store command communicates with the HADB database and not with an application server instance. For the create-session-store command to work correctly, the HADB database must be running. You must run the create-session-store command before accessing any application that needs failover support in a clustered environment.
You can use the cladmin command to create a session store for an entire cluster. See Using the cladmin Command to Configure Session Persistence for an Entire Cluster.
The clsetup command also configures session persistence. See the Sun Java System Application Server Installation Guide.
The options of the create-session-store command are as follows:
- storeurl is the URL of the HADB store. To get this URL, see Getting the JDBC URL.
- 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.
- 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 21, "Administering the High-Availability Database on Unix(Enterprise Edition)."
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.
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.
The optionsfile 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
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
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 using the asadmin clear-session-store command, do one of the following:
- Disable high availability for all instances in the cluster as explained in Enabling and Disabling Availability.
- Quiesce all instances in the cluster as explained in Disabling and Quiescing an Application Server Instance in a Cluster.
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 the Session Store.
For more information on using HADB commands, see Chapter 21, "Administering the High-Availability Database on Unix(Enterprise Edition)."
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.
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 and Disabling Availability.
Managing the Session Store for Clusters
You can choose whether to use one cluster or multiple clusters with a single session store. For more information on using multiple clusters, see Defining Multiple Clusters.
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.
You must specify the name of the cluster to which each application server instance belongs.
Note
If you are using a separate 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.
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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.
For more information on clusters, see Chapter 19, "Managing Clusters (Enterprise Edition)."
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
Enabling and Disabling Availability
Availability can be enabled at five different levels:
For availability to be enabled at a given level, it must be enabled at all higher levels as well. For example, to enable availability at the application level, you must also enable it at the server instance and container levels.
The default for a given level is the setting at the next level up. For example, if availability is enabled at the container level, it is enabled by default at the application level.
When availability is disabled at the server instance level (the default setting), enabling it at any other level has no effect. When availability is enabled at the server instance level, it is enabled at all levels unless explicitly disabled.
The following sections describe how to enable availability:
Server Instance and Container Levels
You can enable availability at the server instance or container level in the following ways:
Using the Administration Interface
To enable or disable availability at the server instance or container level using the Administration interface, follow these steps:
- Open the Availability Service component under your server instance.
- Go to the Availability Service page.
- Enable the Instance Level Availability by checking the box. To disable it, uncheck the box.
- Enable the Web Container Availability by choosing either Enabled or Specified by Instance (if Instance Level Availability is checked). To disable it, choose Disabled.
- Enable the Ejb Container Availability by choosing either Enabled or Specified by Instance (if Instance Level Availability is checked). To disable it, choose Disabled.
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
Using the asadmin Command
To enable availability at the container level only, use the asadmin set command as follows, then restart the server:
asadmin set --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] instance_name.ejb-container.availabilityEnabled=true
To enable availability for the web container, use web-container instead of ejb-container.
Editing the server.xml File
To enable availability for the server instance, web container, or EJB container, add availability-enabled="true" to the appropriate element of the server.xml file as follows, then restart the server:
<server name="server1">
...
<availability-service availability-enabled="true">
...
</availability-service>
...
<web-container ... availability-enabled="true"/>
...
<ejb-container ... availability-enabled="true"/>
...
</server>Application and Module Levels
You can enable availability at the application or module level during deployment in the following ways:
These sections briefly describe how the deployment procedure is different when you enable availability. For general information about deployment, see Chapter 13, "Deploying Applications."
Using the Administration Interface
To enable availability in the Administration interface during deployment, make sure Availability Enabled is set to either true or Specified by Container (if availability is enabled for the web or EJB container).
Using the asadmin Command
To enable availability using the asadmin deploy or asadmin deploydir command, include the --availabilityenabled option.
Editing the server.xml File
To enable availability at the application level, set availability-enabled="true" in the j2ee-application element of the server.xml file as follows, then restart the server:
<server name="server1">
...
<applications>
...
<j2ee-application
name="MyApp"
location="instance_dir/applications/j2ee-apps/MyApp"
availability-enabled="true">
</j2ee-application>
...
</applications>
...
</server>To enable availability at the web or EJB module level, set availability-enabled="true" in the web-module or ejb-module element of the server.xml file as follows, then restart the server:
<server name="server1">
...
<applications>
...
<ejb-module
name="MyBean"
location="instance_dir/applications/j2ee-modules/MyBean"
availability-enabled="true">
</ejb-module>
...
</applications>
...
</server>The SFSB Level
For information about enabling availability for a specific SFSB, see the Developer’s Guide to Enterprise JavaBeans Technology.
Failover of J2EE Object References Stored in SessionsSun Java System Application Server supports failover of J2EE object references that are stored in HTTP and SFSB Sessions. Table 20-3 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 application 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.
- A reference to a J2EE component or resource may be lost. Table 20-3 lists the types of references that session failover supports.
- References to open files or network connections are lost.
For information about how to work around some of these limitations, see Sun Java System Application Server System Deployment Guide.
Configuring SFSB Session PersistenceThis section includes the following topics:
How SFSB Session Persistence Works When Availability Is Enabled
When availability is enabled at the EJB container and application levels, SFSB session persistence is enabled by default. See Enabling and Disabling Availability.
If availability is enabled, the state of an SFSB is saved to the persistent store at predefined points in its life cycle. This is called checkpointing. Checkpointing generally occurs after any transaction involving the SFSB is completed, even if the transaction rolls back. You can also configure end-of-method checkpointing.
For more information about SFSB checkpointing, see the Developer’s Guide to Enterprise JavaBeans Technology.
Setting the SFSB Session Store When Availability is Disabled
If availability is disabled, the local file system is used for SFSB state passivation, but not persistence. To change where the SFSB state is stored, follow these steps in the Administration interface:
As an alternative, you can edit the server.xml file. The session-store attribute determines where the SFSB state is stored if the local file system is used for SFSB state persistence. For example:
<server name="server1" ... session-store="/export/sfsbstore">
This change to the server.xml file take effect when you restart the server.
Finally, you can use the asadmin set command. For example:
asadmin set --user joeuser --password secret server1.sessionStore=/export/sfsbstore
This change takes effect when you restart the server.
Configuring HTTP Session PersistenceThis section includes the following topics:
Making a Web Application Distributable
For HTTP session persistence to work for a web application, the web application must be distributable. Configuring a non-distributable web application for high availability has no effect. For details, see the Sun Java System Application Server Developer’s Guide to Web Applications.
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.
Availability of Single Sign-on in the HTTP 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 an HTTP session fails over to another instance in a cluster, single sign-on information must be persisted to the HADB. This is enabled when you enable availability for the application server instance and the web container.
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 HTTP 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.
Setting the Session Timeout
HTTP sessions are persisted for the interval set in the session-timeout element in the web.xml file or the timeoutSeconds property of the session-properties element in the server.xml file (for instance-level configuration) or in the sun-web.xml file (for application-level configuration). Note that the session-timeout element in web.xml is specified in minutes, not seconds.
If a session-timeout element is specified, the session-timeout value overrides any timeoutSeconds value. If timeoutSeconds is specified in both sun-web.xml and server.xml, the value in sun-web.xml takes precedence. If neither session-timeout nor timeoutSeconds is specified, the timeoutSeconds default of 600 seconds (10 minutes) is used.
If session-timeout is not specified and timeoutSeconds is set to 0, HTTP sessions never time out.
Inactive sessions that have timed out are deleted from the session store at the frequency specified by 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). If reapIntervalSeconds is specified in both sun-web.xml and server.xml, the value in sun-web.xml takes precedence. The default is 60 seconds.
To maximize availability, set session-timeout or timeoutSeconds to a large value, and set reapIntervalSeconds to 1, the minimum value.
HTTP Session Persistence Options
You can configure HTTP session persistence for the Sun Java System 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 state), or you can choose to store the session after a time interval you specify (thus providing 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 container-level settings by setting the corresponding configuration for the application in the corresponding sun-web.xml file.
This section includes the following topics:
About the asadmin 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 asadmin 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. The 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.
- store 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 HTTP 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 A, "Using the Command Line Interface."
Using the cladmin Command to Configure Session Persistence for an Entire Cluster
As an alternative to the asadmin configure-session-persistence command, you can use the cladmin command to configure session persistence for all instances in a cluster at once 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:
If the clinstance.conf and the clpassword.conf files are located in the configuration directory of the Sun Java System Application Server (by default etc/opt/SUNWappserver7), you can omit the instancefile and passwordfile options.
For more information on the cladmin command, see Appendix F, "Using the cladmin Command for Administration (Enterprise Edition)."
Setting the Persistence Type
The persistence type defines if and how HTTP session persistence and failover take place in the Sun Java System Application Server. Persistence types 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 session persistence and failover capabilities.
The memory persistence type provides no failover and is the default persistence type for HTTP sessions. It is the best choice for production environments that do not require HTTP session persistence and failover capabilities.
The persistence type setting defines the location where the session state is stored. You can choose one of the three options available:
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.
Default Values for Session Persistence
If high availability is disabled, persistence type is set to memory for HTTP sessions and SFSB sessions use the SFSB session store. 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:
This default can be overridden by any other persistence configuration, either for an application server instance or for an application.
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 data for sessions being serviced by server instances in a cluster is stored in the HADB database. The state of each session is available to all instances in the cluster. Therefore, if an instance becomes unavailable, other instances in the cluster can continue to serve the sessions that the unavailable instance 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 Defining a Cluster.
- Idempotent URLs are supported along the HTTP path, but not the RMI/IIOP path. If a server instance to which an RMI/IIOP client request is sent crashes during the request processing (before the response could be prepared and sent back to the client), an error is propagated to the client. The client must retry the request explicitly. When the client retries the request, the request is sent to another server instance in the cluster, which retrieves session state information for this 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 19, "Managing Clusters (Enterprise Edition)."
When you use the ha persistence type, you must also correctly configure 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 Highly Available Database.
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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
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 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 availability 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 HTTP Session Persistence Properties.
If the application server instance becomes unavailable unexpectedly, the corresponding session state that would be 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
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.
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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">
</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 Java System 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 20-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 HTTP Session Persistence Properties.
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.
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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">
</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.
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.
For information about SFSB persistence options, see Setting the SFSB Session Store When Availability is Disabled.
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:
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
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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
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 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="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 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 HTTP 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
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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
asadmin 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="ha">
<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.
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:
These options are described in the following topics:
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
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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="ha">
<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
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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="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 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.
If you use the modified-attribute persistence scope, your application must follow these guidelines:
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
- Click on the Save button.
- Go to the server instance page.
- Apply Changes and restart the server.
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
asadmin 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="ha">
<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.
Configuring Other HTTP Session Persistence Properties
To fine tune the session persistence behavior, you can modify properties of the manager-properties, store-properties, and session-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 20-7 and Table 20-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.
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.
asadmin configure-session-persistence --user admin --password MyPassword --host localhost --port 4848 --type ha --property maxSessions=1000:reapIntervalSeconds=60 instance1
Overriding HTTP Session Persistence Settings
For a web application, you can specify the session persistence settings through the corresponding sun-web.xml file.
You may want to specify different session persistence settings for a web 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 is not 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 and Disabling Availability. 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.