Creating and Managing Sessions

This chapter describes how to create and manage HTTP or SIP sessions that allows users and transaction information to persist between interactions.

This chapter contains the following sections:

• Configuring Sessions

• Session Managers

Configuring Sessions

This section covers the following topics:

• HTTP Sessions, Cookies, and URL Rewriting

• Coordinating Session Access

• SIP Session Limitation

• Distributed Sessions and Persistence

HTTP Sessions, Cookies, and URL Rewriting

To configure whether and how HTTP sessions use cookies and URL rewriting, edit the session-properties and cookie-properties elements in the sun-web.xml file for an individual web application. For more about the properties you can configure, see session-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide and cookie-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide.

For information about configuring default session properties for the entire web container, see Chapter 8, SIP, Web, and EJB Containers, in Sun GlassFish Communications Server 2.0 Administration Guide and the Sun GlassFish Communications Server 2.0 High Availability Administration Guide.

Coordinating Session Access

Make sure that multiple threads don’t simultaneously modify the same session object in conflicting ways.

This is especially likely to occur in SIP applications where multiple SIP sessions share a SIP application session, and in converged applications where requests for the same session occur through HTTP and SIP protocols. It is likely to occur in pure web applications that use HTML frames where multiple servlets are executing simultaneously on behalf of the same client. A good solution is to ensure that one of the servlets modifies the session and the others have read-only access.

SIP Session Limitation

The following JSR 289 API methods are not fully supported in a clustered environment:

javax.servlet.sip.SipSessionsUtil.getApplicationSessionById(String applicationSessionId)

javax.servlet.sip.SipSessionsUtil.getApplicationSessionByKey(String applicationSessionKey, 
boolean create)

If the session is not located in the server instance where the method is executed, these methods return a null result.

If a SIP application session contains application data that must be accessed from anywhere in the cluster, the application should store that data in a database, using the SIP application ID as the key. This makes the data easily accessible from JMS handlers, EJB components, or similar entities whose distribution in the cluster is not correlated with the distribution of SIP application sessions.

Distributed Sessions and Persistence

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile. For information about profiles, see Usage Profiles in Sun GlassFish Communications Server 2.0 Administration Guide.

A distributed HTTP or SIP session can run in multiple Communications Server instances, provided the following criteria are met:

• Each server instance has the same distributable web, SIP, or converged web/SIP application deployed to it. The web-app element of the web.xml or sip.xmldeployment descriptor file must have the distributable subelement specified. For a converged web/SIP application to be treated as distributable, both its web.xml and sip.xml deployment descriptor files must have the distributable subelement specified.

• The web, SIP, or converged web/SIP application uses high-availability session persistence. If a non-distributable web, SIP, or converged web/SIP application is configured to use high-availability session persistence, a warning is written to the server log, and the session persistence type reverts to memory. See The replicated Persistence Type.

• If a converged web/SIP application uses high-availability session persistence for its SIP sessions, but not its HTTP sessions, or the reverse, a warning is logged, and the persistence type of both the application's SIP and HTTP sessions reverts to memory.

• All objects bound into a distributed session must be of the types listed in Table 8–4.

• The web, SIP, or converged web/SIP application must be deployed using the deploy or deploydir command with the --availabilityenabled option set to true. See the Sun GlassFish Communications Server 2.0 Reference Manual.

Contrary to the Servlet 2.5 specification, Communications Server does not throw an IllegalArgumentException if an object type not supported for failover is bound into a distributed session.

Keep the distributed session size as small as possible. Session size has a direct impact on overall system throughput.

In the event of an instance or hardware failure, another server instance can take over a distributed session, with the following limitations:

• If a distributable web, SIP, or converged web/SIP application references a Java EE component or resource, the reference might be lost. See Table 8–4 for a list of the types of references that HTTPSession or SipApplicationSessionfailover supports.

• References to open files or network connections are lost.

• Session replication occurs asynchronously, so a small number of sessions may be lost on failure because their state has not propagated to the other instances in the cluster.

For information about how to work around these limitations, see the Sun GlassFish Communications Server 2.0 Deployment Planning Guide.

In the following table, No indicates that failover for the object type might not work in all cases and that no failover support is provided. However, failover might work in some cases for that object type. For example, failover might work because the class implementing that type is serializable.

For more information about the InitialContext, see Accessing the Naming Context. For more information about transaction recovery, see Chapter 16, Using the Transaction Service. For more information about Administered Objects, see Creating Physical Destinations.

Session Managers

A session manager automatically creates new session objects whenever a new session starts. In some circumstances, clients do not join the session, for example, if the session manager uses cookies and the client does not accept cookies.

Communications Server offers these session management options, determined by the session-manager element’s persistence-type attribute in the sun-web.xml or sun-sip.xmlfile:

• The memory Persistence Type, the default

• The file Persistence Type, which uses a file to store session data, supported only for pure web applications

• The replicated Persistence Type, which uses other servers in the cluster for session persistence

If the session manager configuration contains an error, the error is written to the server log and the default (memory) configuration is used.

For more information, see session-manager in Sun GlassFish Communications Server 2.0 Application Deployment Guide.

The memory Persistence Type

This persistence type is not designed for a production environment that requires session persistence. It provides no session persistence. However, for web applications only, you can configure it so that the session state in memory is written to the file system prior to server shutdown.

To specify the memory persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Sun GlassFish Communications Server 2.0 Reference Manual.

To specify the memory persistence type for a specific web or SIP application, edit the sun-web.xml or sun-sip.xml file as in the following example. The persistence-type property is optional, but must be set to memory if included. This overrides the web container availability settings for the web application.

<sun-web-app>
...
<session-config>
	<session-manager persistence-type="memory" />
		<manager-properties>
			<property name="sessionFilename" value="sessionstate" />
		</manager-properties>
	</session-manager>
	...
</session-config>
...
</sun-web-app>

The only manager property that the memory persistence type supports is sessionFilename, which is listed under manager-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide. This property does not apply to SIP applications.

For more information about the sun-web.xml or sun-sip.xml file, see Sun GlassFish Communications Server 2.0 Application Deployment Guide.

The file Persistence Type

This persistence type provides session persistence to the local file system, and allows a single server domain to recover the session state after a failure and restart. The session state is persisted in the background, and the rate at which this occurs is configurable. The store also provides passivation and activation of the session state to help control the amount of memory used. This option is not supported in a production environment. However, it is useful for a development system with a single server instance. This persistence type does not apply to SIP applications.

Make sure the delete option is set in the server.policy file, or expired file-based sessions might not be deleted properly. For more information about server.policy, see The server.policy File.

To specify the file persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Sun GlassFish Communications Server 2.0 Reference Manual.

To specify the file persistence type for a specific web application, edit the sun-web.xml file as in the following example. Note that persistence-type must be set to file. This overrides the web container availability settings for the web application.

<sun-web-app>
...
<session-config>
	<session-manager persistence-type="file">
		<store-properties>
			<property name="directory" value="sessiondir" />
		</store-properties>
	</session-manager>
	...
</session-config>
...
</sun-web-app>

The file persistence type supports all the manager properties listed under manager-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide except sessionFilename, and supports the directory store property listed under store-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide.

For more information about the sun-web.xml file, see Sun GlassFish Communications Server 2.0 Application Deployment Guide.

The replicated Persistence Type

The replicated persistence type uses other servers in the cluster for session persistence. Clustered server instances replicate session state in a predictive manner so that the state is saved where it is most likely to be needed. Each backup instance stores the replicated data in memory. This allows sessions to be distributed. For details, see Distributed Sessions and Persistence. In addition, you can configure the frequency and scope of session persistence. The other servers are also used as the passivation and activation store. Use this option in a production environment that requires session persistence.

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile. For information about profiles, see Usage Profiles in Sun GlassFish Communications Server 2.0 Administration Guide.

To use the replicated persistence type, you must first enable availability. Select the Availability Service component under the relevant configuration in the Admin Console. Check the Availability Service box. To enable availability for the web container, select the Web Container Availability tab, then check the Availability Service box. To enable availability for the SIP container, select the SIP Container Availability tab, then check the Availability Service box. All instances in a Communications Server cluster should have the same availability settings to ensure consistent behavior. For details, see the Sun GlassFish Communications Server 2.0 High Availability Administration Guide.

To change settings such as persistence frequency and persistence scope for the entire web container, use the Persistence Frequency and Persistence Scope drop-down lists on the Web Container Availability tab in the Admin Console, or use the asadmin set command. For example:

asadmin set 
server-config.availability-service.web-container-availability.persistence-frequency=time-based

For more information, see the description of the asadmin set command in the Sun GlassFish Communications Server 2.0 Reference Manual.

To specify the replicated persistence type for a specific web application, edit the sun-web.xml file as in the following example. Note that persistence-type must be set to replicated. This overrides the web container availability settings for the web application.

<sun-web-app>
...
<session-config>
	<session-manager persistence-type="replicated">
		<manager-properties>
			<property name="persistenceFrequency" value="web-method" />
		</manager-properties>
		<store-properties>
			<property name="persistenceScope" value="session" />
		</store-properties>
	</session-manager>
	...
</session-config>
...
</sun-web-app>

To specify the replicated persistence type for a specific SIP application, edit the sun-sip.xml file as in the following example. Note that persistence-type must be set to replicated and that persistenceFrequency and persistenceScope are not used.

<sun-sip-app>
...
<session-config>
	<session-manager persistence-type="replicated"/>
	...
</session-config>
...
</sun-sip-app>

For a converged web/SIP application, you must edit both the sun-web.xml file and the sun-sip.xml file. A converged web/SIP application has two session managers. The HTTP session manager is configured by sun-web.xml. The SIP session manager is configured by sun-sip.xml.

For web container session persistence only, the replicated persistence type supports all the manager properties listed under manager-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide except sessionFilename, and supports the persistenceScope store property listed under store-properties in Sun GlassFish Communications Server 2.0 Application Deployment Guide.

For more information about the sun-web.xml or sun-sip.xml file, see Sun GlassFish Communications Server 2.0 Application Deployment Guide.