Creating and Managing User Sessions

This chapter describes how to create and manage a session that allows users and transaction information to persist between interactions.

Introducing Sessions

The term user session refers to a series of user application interactions that are tracked by the server. Sessions are used for maintaining user specific state, including persistent objects (like handles to EJB components or database result sets) and authenticated user identities, among many interactions. For example, a session could be used to track a validated user login followed by a series of directed activities for a particular user.

The session itself resides in the server. For each request, the client transmits the session ID in a cookie or, if the browser does not allow cookies, the server automatically writes the session ID into the URL.

The Sun ONE Application Server supports the servlet standard session interface, called HttpSession, for all session activities. This interface enables you to write portable, secure servlets.

Sessions and Cookies

A cookie is a small collection of information that can be transmitted to a calling browser, which retrieves it on each subsequent call from the browser so that the server can recognize calls from the same client. A cookie is returned with each call to the site that created it, unless it expires.

Sessions are maintained automatically by a session cookie that is sent to the client when the session is first created. The session cookie contains the session ID, which identifies the client to the browser on each successive interaction. If a client does not support or allow cookies, the server rewrites the URLs where the session ID appears in the URLs from that client.

You can configure the session-properties for the entire web container:

To use the Administration interface, select Containers and then Web Container under your server instance. Then click on the Properties button under Session Configuration Properties. After editing the properties, click on OK, then Save.

You can also edit the session-properties element in the server.xml file, which is the same as the corresponding element in the sun-web.xml file. For details, see the Sun ONE Application Server Administrator’s Configuration File Reference.

You can configure the session-properties and cookie-properties elements in the sun-web.xml file for an individual web application. The sun-web.xml file is described in Chapter 6, “Assembling and Deploying Web Modules.”

Sessions and URL Rewriting

You can configure the session-properties for the entire web container:

You can configure the session-properties element in the sun-web.xml file for an individual web application. The sun-web.xml file is described in Chapter 6, “Assembling and Deploying Web Modules.”

Sessions and Security

The Sun ONE Application Server security model is based on an authenticated user session. Once a session has been created the application user is authenticated (if authentication is used) and logged in to the session. Each interaction step from the servlet that receives an EJB request does two things: generates content for a JSP to format the output, and checks that the user is properly authenticated.

Additionally, you can specify that a session cookie is only passed on a secured connection (that is, HTTPS), so the session can only remain active on a secure channel.

Distributed Sessions and Persistence

A distributed session can run in multiple Sun ONE Application Server instances, provided the following criteria are met:

Each server instance has the same distributable web application deployed to it. The web-app element of the web.xml deployment descriptor file must have the distributable subelement specified.

Each server instance has access to the same Sun ONE high-availability database (HADB). For information about how to enable this database, see "Enabling the Availability Service".

The web application uses high-availability session persistence. If a non-distributable web application is configured to use high-availability session persistence, an error is written to the server log. See "PersistentManager".

All objects bound into a distributed session must be of the types listed in the "Object Types Supported for J2EE Web Application Session State Failover" table.



Note	Contrary to the Servlet 2.3 specification, Sun ONE Application Server does not throw an IllegalArgumentException if an object type not supported for failover is bound into a distributed session. You should keep the distributed session size as small as possible. Session size has a direct impact on overall system throughput.

A servlet that is not deployed as part of a web application is implicitly deployed to a default web application and has the default ServletContext. The default ServletContext is not distributed. (A web application with an empty context root does not have the default ServletContext.)

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

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

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

For more information about the InitialContext, transaction recovery, and Administered Objects, see the Sun ONE Application Server Developer's Guide to J2EE Services and APIs. For more information about local and remote EJB references, see the Sun ONE Application Server Developer's Guide to Enterprise JavaBeans Technology.

Table 4-1 Object Types Supported for J2EE Web Application Session State Failover
Java Object Type	Failover Support
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
Java™ Message Service (JMS) ConnectionFactory, Destination	No
JavaMail™ Session	No
Connection Factory	No
Administered Object	No
Web service reference	No
Serializable Java types	Yes

How to Use Sessions

To use a session, first create a session using the HttpServletRequest method getSession(). Once the session is established, examine and set its properties using the provided methods. If desired, set the session to time out after being inactive for a defined time period or invalidate it manually. You can also bind objects to the session which store them for use by other components.

Creating or Accessing a Session

To create a new session or to gain access to an existing session, use the HttpServletRequest method getSession(), as shown in the following example:

getSession() returns the valid session object associated with the request, identified in the session cookie which is encapsulated in the request object. Calling the method with no arguments, creates a session if one does not already exist which is associated with the request. Additionally, calling the method with a Boolean argument creates a session only if the argument is true.

The following example shows the doPost() method from a servlet which only performs the servlet’s main functions, if the session is present. Note that, the false parameter to getSession() prevents the servlet from creating a new session if one does not already exist:

public void doPost (HttpServletRequest req,
            HttpServletResponse res)
        throws ServletException, IOException
{
  if ( HttpSession session = req.getSession(false) )
  {
    // session retrieved, continue with servlet operations
  }
  else
    // no session, return an error page

  }
}


Note	The getSession() method should be called before anything is written to the response stream. Otherwise the SetCookie string is placed in the HTTP response body instead of the HTTP header.

For more information about getSession(), see the Java Servlet Specification v2.3.

Examining Session Properties

Once a session ID has been established, use the methods in the HttpSession interface to examine session properties, and methods in the HttpServletRequest interface to examine request properties that relate to the session.

Table 4-2 HttpSession Methods
HttpSession method	Description
getCreationTime()	Returns the session time in milliseconds since January 1, 1970, 00:00:00 GMT.
getId()	Returns the assigned session identifier. An HTTP session’s identifier is a unique string which is created and maintained by the server.
getLastAccessedTime()	Returns the last time the client sent a request carrying the assigned session identifier (or -1 if its a new session) in milliseconds since January 1, 1970, 00:00:00 GMT.
isNew()	Returns a Boolean value indicating if the session is new. Its a new session, if the server has created it and the client has not sent a request to it. This means, the client has not acknowledged or joined the session and may not return the correct session identification information when making its next request.

String mySessionID = mySession.getId();
if ( mySession.isNew() ) {
log.println(currentDate);
log.println("client has not yet joined session " + mySessionID);
}

Table 4-3 HttpServletRequest Methods
HttpServletRequest Methods	Description
getRemoteUser()	Gets the requesting user name (HTTP authentication can provide the information). Returns null if the request has no user name information.
getRequestedSessionId()	Returns the session ID specified with the request. This may differ from the session ID in the current session if the session ID given by the client is invalid and a new session was created. Returns null if the request does not have a session associated with it.
isRequestedSessionIdValid()	Checks if the request is associated to a currently valid session. If the session requested is not valid, it is not returned through the getSession() method.
isRequestedSessionIdFromCookie()	Returns true if the request’s session ID provided by the client is a cookie, or false otherwise.
isRequestedSessionIdFromURL()	Returns true if the request’s session ID provided by the client is a part of a URL, or false otherwise.

if ( request.isRequestedSessionIdValid() ) {
  if ( request.isRequestedSessionIdFromCookie() ) {
    // this session is maintained in a session cookie
  }
  // any other tasks that require a valid session
} else {
  // log an application error
}

Binding Data to a Session

You can bind objects to sessions in order to make them available across multiple user interactions.

The following table shows the HttpSession methods that provide support for binding objects to the session object.

Table 4-4 HttpSession Methods
HttpSession Methods	Description
getAttribute()	Returns the object bound to a given name in the session or null if there is no such binding.
getAttributeNames()	Returns an array of names of all attributes bound to the session.
setAttribute()	Binds the specified object into the session with the given name. Any existing binding with the same name is overwritten. An object bound into a distributed session must implement the java.io.Serializable interface. See "Distributed Sessions and Persistence".
removeAttribute()	Unbinds an object in the session with the given name. If there is no object bound to the given name this method does nothing.

Binding Notification with HttpSessionBindingListener

Some objects require you to know when they are placed in or removed from, a session. To obtain this information, implement the HttpSessionBindingListener interface in those objects. When your application stores or removes data with the session, the servlet engine checks whether the object being bound or unbound implements HttpSessionBindingListener. If it does, the Sun ONE Application Server notifies the object under consideration, through the HttpSessionBindingListener interface, that it is being bound into or unbound from the session.

Invalidating a Session

Specify the session to invalidate itself automatically after being inactive for a defined time period. Alternatively, invalidate the session manually with the HttpSession method invalidate().

Invalidating a Session Manually

Setting a Session Timeout


Tip	The session API does not provide an explicit session logout API, so any logout implementation must call the session.invalidate() API.

Enabling the Availability Service

This section describes how to enable the Sun ONE high-availability database (HADB) for session persistence. For information about how to set up and configure this database, see the Sun ONE Application Server Administrator’s Guide. To enable the HADB, perform these tasks:

The availability setting applies unconditionally to all applications deployed to the server instance, including those with the persistence-type set to ha. You should should set the same availability value for all instances in a cluster to ensure consistent behavior.

The Availability Service setting also determines whether single sign-on, if configured, is highly available.


Note	Enabling the Availability Service is not sufficient for configuring session persistence. For details, see "Distributed Sessions and Persistence".

If the Availability Service is disabled, there is no high availability for HTTP session persistence. In other words, persistence-type=memory.

If the Availability Service is enabled, high availability for HTTP session persistence is enabled for all applications by default. If no further configuration exists either in the server.xml or sun-web.xml file, the default session persistence configuration is as follows:

You can override this default configuration for all applications in server.xml. For details, see the Sun ONE Application Server Administrator’s Configuration File Reference. You can override this default configuration for a specific application in sun-web.xml. For details, see "Session Managers".

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.

StandardManager


Note	The session manager interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

The StandardManager is the default session manager. By default this session manager provides no session persistence. However, you can configure it so that the session state is written to the file system prior to server shutdown. This session manager is not designed for a production environment.

Enabling StandardManager

To specify StandardManager for a specific web application, edit the sun-web.xml file as in the following example. The persistence-type property is optional. This overrides the web container settings for the web application.

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

Manager Properties for StandardManager


Note	If the session manager configuration contains an error, the error is written to the server log and the StandardManager default configuration is used.

The following table describes manager-properties properties for the StandardManager session manager.

Table 4-5 manager-properties Properties
Property Name	Default Value	Description
reapIntervalSeconds	60	Specifies the number of seconds between checks for expired sessions. You should set this value lower than the frequency at which session data changes. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.
maxSessions	-1	Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this, an attempt to create a new session causes an IllegalStateException to be thrown.
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 web application.

PersistentManager

The PersistentManager is the other session manager provided with Sun ONE Application Server. For session persistence, PersistentManager can use either of the following stores, to which each session is serialized:

A file - Provides session persistence to the local file system, and allows a single server instance 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. This 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.

The Sun ONE high-availability database (HADB). The HADB 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 HADB is also used as the passivation and activation store. Use this option in a production environment that requires session persistence.

Enabling PersistentManager

Open the Containers component under your server instance.

Go to the Web Container page.

Click on the Session Manager tab.

Change the Persistence Type to File or to Highly Available Database.

Click on the Properties button under Properties.

Enter the names and values of any properties that you want to change from the default values. For a list of properties, see "Manager Properties for PersistentManager".

Click on the OK button.

Click on the Properties button under Session Store Properties.

Enter the names and values of any properties that you want to change from the default values. For a list of properties, see "Store Properties for PersistentManager".

Click on the OK button.

Click on the Save button.

To specify PersistentManager 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 or ha. This overrides the web container settings for the web application.

<sun-web-app>
  ...
  <session-config>
    <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>
    ...
  </session-config>
  ...
</sun-web-app>

Manager Properties for PersistentManager


Note	If the session manager configuration contains an error, the error is written to the server log and the StandardManager default configuration is used.

The following table describes manager-properties properties for the PersistentManager session manager.

Table 4-6 manager-properties Properties
Property Name	Default Value	Description
reapIntervalSeconds	60	Specifies the number of seconds between checks for expired sessions. If the persistence-type attribute of the session-manager element is file or ha, sessions are passivated if maxSessions has been exceeded. If persistenceFrequency is set to time-based, active sessions are stored at this interval. You should set this value lower than the frequency at which session data changes. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.
maxSessions	-1	Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this, an attempt to create a new session causes an IllegalStateException to be thrown. If the persistence-type attribute of the session-manager element is file or ha, the session manager passivates sessions to the persistent store when this maximum is reached.
persistenceFrequency	web-method	Specifies how often the session state is stored. Allowed values are as follows: web-method - The session state is stored at the end of each web request prior to sending a response back to the client. This mode provides the best guarantee that the session state is fully updated in case of failure. time-based - The session state is stored in the background at the frequency set by reapIntervalSeconds. This mode provides less of a guarantee that the session state is fully updated. However, it can provide a significant performance improvement because the state is not stored after each request. Applicable only if the persistence-type attribute of the session-manager element is ha.

Store Properties for PersistentManager

The following table describes store-properties properties for the PersistentManager session manager.

Table 4-7 store-properties Properties
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 web application. Applicable only if the persistence-type attribute of the session-manager element is file.
persistenceScope	session	Specifies how much of the session state is stored. Allowed values are as follows: session - The entire session state is stored every time. This mode provides the best guarantee that your session data is correctly stored for any distributable web application. modified-session - The entire session state is stored if it has been modified. A session is considered to have been modified if HttpSession.setAttribute() or HttpSession.removeAttribute() was called. You must guarantee that setAttribute() is called every time an attribute is changed. This is not a J2EE specification requirement, but it is required for this mode to work properly. modified-attribute - Only modified session attributes are stored. For this mode to work properly, you must follow some guidelines, which are explained immediately following this table. Applicable only if the persistence-type attribute of the session-manager element is ha.

If the persistenceScope store property is set to modified-attribute, your web application should follow these guidelines:

Call setAttribute() every time you modify the session state.

Make sure there are no cross-references between attributes. The object graph under each distinct attribute key is serialized and stored separately. If there are any object cross references between the objects under each separate key, they are not serialized and deserialized correctly.

Ideally, the session state should be stored in multiple attributes, or at least in a read-only attribute and a modifiable attribute.



Note	The session persistence scope modified-attribute is not certified as a full production quality feature. You should evaluate the performance and stability of the web container under expected peak load with this persistence scope. If exceptions are logged or response time is too high, do not use this persistence scope for your production environment. Use session or modified-session instead.

Chapter 4 Creating and Managing User Sessions