Sun ONE Application Server 7, Enterprise Edition Developer's Guide to Web Applications |
Chapter 4
Creating and Managing User SessionsThis chapter describes how to create and manage a session that allows users and transaction information to persist between interactions.
This chapter contains the following sections:
Introducing SessionsThe 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.
The rest of this section includes these topics:
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 whether and how sessions use cookies in the following ways:
- 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 whether sessions use URL rewriting in the following ways:
- 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 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.
For more information about security, see Chapter 5, “Securing Web Applications.”
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.
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:
- If a distributable web application references a J2EE component or resource, the reference may be lost. See the "Object Types Supported for J2EE Web Application Session State Failover" table for a list of the types of references that HTTPSession failover supports.
- References to open files or network connections are lost.
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.
How to Use SessionsTo 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.
The rest of this section includes these topics:
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:
HttpSession mySession = request.getSession();
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.
The following table shows the methods to examine session properties.
For example:
String mySessionID = mySession.getId();
if ( mySession.isNew() ) {
log.println(currentDate);
log.println("client has not yet joined session " + mySessionID);
}The following table shows the methods to examine servlet request properties.
For example:
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().
Tip
The session API does not provide an explicit session logout API, so any logout implementation must call the session.invalidate() API.
Invalidating a Session Manually
To invalidate a session manually, simply call the following method:
session.invalidate();
All objects bound to the session are removed.
Setting a Session Timeout
Session timeout is set using the sun-web.xml deployment descriptor file. For more information, see the session-properties element in Chapter 6, “Assembling and Deploying Web Modules.”
Enabling the Availability ServiceThis 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:
persistence-type=ha
persistenceFrequency=time-based
persistenceScope=session
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 ManagersA 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.
Sun ONE Application Server 7 gives you these session management options:
- StandardManager, the default session manager
- PersistentManager, a provided session manager that uses a persistent data store
StandardManager
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 the entire web container, perform these tasks:
- 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 Memory.
- 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 StandardManager".
- Click on the OK button.
- Click on the Save button.
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>For more information about the sun-web.xml file, see Chapter 6, “Assembling and Deploying Web Modules.”
Note
If the session manager configuration contains an error, the error is written to the server log and the StandardManager default configuration is used.
Manager Properties for StandardManager
The following table describes manager-properties properties for the StandardManager session manager.
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.
You must enable the HADB before you can use distributed sessions. See "Enabling the Availability Service".
Enabling PersistentManager
To specify PersistentManager for the entire web container, perform these tasks:
- 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>For more information about the sun-web.xml file, see Chapter 6, “Assembling and Deploying Web Modules.”
Note
If the session manager configuration contains an error, the error is written to the server log and the StandardManager default configuration is used.
Manager Properties for PersistentManager
The following table describes manager-properties properties for the PersistentManager session manager.
Store Properties for PersistentManager
The following table describes store-properties properties for the PersistentManager session manager.
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.