Programmer's Guide to Servlets

Table of Contents | Previous | Next | Index | Bookshelf

Programmer's Guide to Servlets

Appendix A
Session Managers

Session objects maintain state and user identity across multiple page requests over the normally stateless HTTP protocol. A session persists for a specified time period, across more than one connection or page request from the user. A session usually corresponds to one user, who may visit a site many times. The server can maintain a session either by using cookies or by rewriting URLs. Servlets can access the session objects to retrieve state information about the session.

This appendix has the following sections:

Session Overview

An HTTP session represents the server's view of the session. The server considers a session new under these conditions:

The client does not yet know about the session.

The session has not yet begun.

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.

NOTE: The session ID generator, which is used for servlet sessions, employs cryptographically strong unique random number generation algorithms. This may present a performance problem on older, slow machines. The Session Manager API allows you to redefine the random ID generation method and customize it to your particular needs (see the SimpleSessionManager.java example file described in "Source Code for SimpleSessionManager").

iPlanet Web Server 4.1 comes with three session managers for creating and managing sessions:

SimpleSessionManager -- the default session manager when the server runs in single process mode.
MMapSessionManager -- the default session manager when the server runs in multi-process mode.
JdbcSessionManager -- a session manager that stores session information in a database using the JDBC API.

iPlanet Web Server 4.1 also allows you to develop your own session managers and load them into the server. The build includes the source code for SimpleSessionManager and the session object it manages, SimpleSession. The source code files for these classes are provided as a starting point for you to define your own session managers if desired. These Java files are in the directory server_root/plugins/samples/servlets/sessions/SimpleSession.

The build also includes the source code for JdbcSessionManager and the session object it manages, JdbcSession. These Java files are in the directory server_root/plugins/samples/servlets/sessions/JdbcSession.

Specifying a Session Manager

By default, if the iPlanet Web Server starts in single process mode, it uses SimpleSessionManager as the session manager for servlets. If it starts in multi-process mode, it uses MMapSessionManager. For more information about single process mode versus multi-processes mode, see Chapter 7, "Configuring Server Preferences," in the iPlanet Web Server Administrator's Guide. In addition, you can read about the MaxProcs parameter in the magnus.conf file in the NSAPI Programmer's Guide for iPlanet Web Server.

You can change the session manager in any of the following ways:

Use the Servlets>Configure Global Servlet Attributes page in the Server Manager interface.

In the Session Manager field, specify the session manager, and, if appropriate, specify parameters for the session manager in the Session Manager Args field.

Edit the file servlets.properties in the directory server_id/config.

Add a line specifying a value for servlets.sessionmgr and, if appropriate, also add a line specifying the parameters for the session manager. For example:

servlets.sessionmgr=com.netscape.server.http.session.YourSesMgr
servlets.sessionmgr.initArgs=maxSessions=20,timeOut=300,reapInterval=150

Edit the file contexts.properties in the directory server_id/config.

Add a line specifying a value for context.context_name.sessionmgr and, if appropriate, also add a line specifying the parameters for the session manager. For example:

context.global.sessionmgr=com.netscape.server.http.session.YourSesMgr
context.global.sessionmgr.initArgs=maxSessions=20,timeOut=300

You can change the global context or define a new context and assign specific servlets to it. For more information, see

Appendix C, "Properties Files."

SimpleSessionManager

The SimpleSessionManager works only in single process mode. It is loaded by default if the iPlanet Web Server starts in single-process mode when a SessionManager is not specified in the servlets.properties or contexts.properties configuration file. These sessions are not persistent, that is, all sessions are lost when the server is stopped.

Parameters

The SimpleSessionManager class takes the following parameters:

maxSessions - the maximum number of sessions maintained by the session manager at any given time. The session manager refuses to create any more new sessions if there are already maxSessions number of sessions present at that time. The default value is 1000.

timeOut - the amount of time in seconds after a session is accessed by the client before the session manager destroys it. Those sessions that haven't been accessed for at least timeOut seconds are destroyed by the reaper method. The default value is 1800 (30 minutes).

reapInterval - the amount of time in seconds that the SessionReaper thread sleeps before calling the reaper method again. The default value is 600 (10 minutes).

Enabling SimpleSessionManager

You may want to enable SimpleSessionManager to change its default parameters. You can also enable SimpleSessionManager for a particular context if the server is running in multi-process mode. To enable the iPlanet Web Server to use SimpleSessionManager, do any of the following:

Use the Servlets>Configure Global Servlet Attributes page in the Server Manager interface.

In the Session Manager field specify:

com.netscape.server.http.session.SimpleSessionManager

You can also specify parameters for the session manager in the Session Manager Args field, for example:

maxSessions=20,timeOut=300,reapInterval=150

Edit the file servlets.properties in the directory server_id/config.

Add a line specifying a value for servlets.sessionmgr and a line specifying the parameters for the session manager:

servlets.sessionmgr=com.netscape.server.http.session.SimpleSessionManager
servlets.sessionmgr.initArgs=maxSessions=20,timeOut=300,reapInterval=150

Edit the file contexts.properties in the directory server_id/config.

Add a line specifying a value for context.context_name.sessionmgr and a line specifying the parameters for the session manager:

context.global.sessionmgr=com.netscape.server.http.session.SimpleSessionManager
context.global.sessionmgr.initArgs=maxSessions=20,timeOut=300,reapInterval=150

You can change the global context or define a new context and assign specific servlets to it. For more information, see

Appendix C, "Properties Files."

Source Code for SimpleSessionManager

The SimpleSessionManager creates a SimpleSession object for each session. The source files for SimpleSessionManager.java and SimpleSession.java are in the directory server_root/plugins/samples/servlets/sessions/SimpleSession.

The source code files for SimpleSessionManager.java and SimpleSession.java are provided so you can use them as the starting point for defining your own session managers and session objects. These files are very well commented.

SimpleSessionManager extends NSHttpSessionManager. The class file for NSHttpSessionManager is in the JAR file NSServletLayer.jar in the directory server_root/bin/https/jar. The SimpleSessionManager implements all the methods in NSHttpSessionManager that need to be implemented, so you can use SimpleSessionManager as an example of how to extend NSHttpSessionManager. When compiling your subclass of SimpleSessionManager or NSHttpSessionManager, be sure that the JAR file NSServletLayer.jar is in your compiler's classpath.

MMapSessionManager

This is a persistent memory map (mmap) file based session manager that works in both single process and multi-process mode. It can be used for sharing session information across multiple processes possibly running on different machines. It is loaded by default if the iPlanet Web Server starts in multi-process mode when a session manager is not specified in the servlets.properties or contexts.properties configuration file.

Parameters

MMapSessionManager takes the following parameters:

maxSessions - the maximum number of sessions maintained by the session manager at any given time. The session manager refuses to create any more new sessions if there are already maxSessions number of sessions present at that time. The default value is 1000.

maxValuesPerSession - the maximum number of values or objects a session can hold. There is no limit.

maxValuesSize - the maximum size of each value or object that can be stored in the session. There is no limit.

timeOut - the amount of time in seconds after a session is last accessed by the client before the session manager destroys it. Those sessions that haven't been accessed for at least timeOut seconds are destroyed by the reaper method. The default value is 1800 (30 minutes).

reapInterval - the amount of time in seconds that the SessionReaper thread sleeps before calling the reaper method again. The default value is 600 (10 minutes).

Enabling MMapSessionManager

You may want to enable MMapSessionManager to change its default parameters. You can also enable MMapSessionManager for a particular context if the server is running in single process mode. To enable iPlanet Web Server to use MMapSessionManager, do any of the following:

Use the Servlets>Configure Global Servlet Attributes page in the Server Manager interface.

In the Session Manager field specify:

com.netscape.server.http.session.MMapSessionManager

You can also specify parameters for the session manager in the Session Manager Args field, for example:

maxSessions=20,maxValueSize=1024,timeOut=300,reapInterval=150

Edit the file servlets.properties in the directory server_id/config.

Add a line specifying a value for servlets.sessionmgr and a line specifying the parameters for the session manager:

servlets.sessionmgr=com.netscape.server.http.session.MMapSessionManager
servlets.sessionmgr.initArgs=maxSessions=20,maxValueSize=1024,timeOut=300,reapInterval=150

Edit the file contexts.properties in the directory server_id/config.

Add a line specifying a value for context.context_name.sessionmgr and a line specifying the parameters for the session manager:

context.global.sessionmgr=com.netscape.server.http.session.MMapSessionManager
context.global.sessionmgr.initArgs=maxSessions=20,maxValueSize=1024,timeOut=300,
reapInterval=150

You can change the global context or define a new context and assign specific servlets to it. For more information, see

Appendix C, "Properties Files."

This session manager can only store objects that implement java.io.Serializable.

JdbcSessionManager

This is a persistent JDBC-based session manager that works in both single process and multi-process modes. It can be used to store sessions in a custom database, which can then be shared across multiple processes possibly running on different machines.

This sample JDBC session manager is not written, tested, or intended for production use. It is provided so that you can customize its behavior to suit your own needs.

JdbcSessionManager has been tested with a standard JDBC-ODBC driver against Microsoft SQL Server 7.0SP1. You must set up the ODBC source, database, and table for the session manager to use. It is recommended that the Session ID column be indexed for higher lookup performance.

Parameters

JdbcSessionManager takes the following parameters:

timeOut - the amount of time in seconds after a session is accessed by the client before the session manager destroys it. Those sessions that haven't been accessed for at least timeOut seconds are destroyed by the reaper method. The default value is 1800 (30 minutes).

provider - the JDBC driver (the default is sun.jdbc.odbc.JdbcOdbcDriver). For more information about the JDBC API, see the following web site:

http://java.sun.com/products/jdbc/index.html

url - the data source (the default is jdbc:odbc:LocalServer).

table - name of the SQL table that store sessions (the default is sessions).

username - the login username for the database.

password - the login password for the database.

reaperActive - tells the session manager whether to run session reaper to remove expired sessions from the database when true, which is the default value. It is recommended that only one server in the cluster be running the reaper.

accessTimeColumn - the name of the column that holds the last access time in minutes (the default name is AccessTime). The SQL type is NUMERIC(9).

sessionIdColumn - the name of the column that holds the session ID (the default name is SessionID). The SQL type is VARCHAR(100).

valueColumn - the name of the column that holds the session object (the default name is Value). The SQL type is VARBINARY(4096). This column must be large enough to accommodate all your session data.

Each type of operation on the database that handles session information (looking up, inserting, updating, and deleting) is performed by a corresponding dedicated connection. Each of these connections has a precompiled SQL statement for higher performance. The following parameters allow you to customize the number of dedicated connections that perform each of the operations.

lookupPool - the number of connections that perform lookup operations (the default is 4 connections).

insertPool - the number of connections that perform insert operations (the default is 4 connections).

updatePool - the number of connections that perform update operations (the default is 4 connections).

deletePool - the number of connections that perform delete operations (the default is 2 connections).

Enabling JdbcSessionManager

You may want to enable JdbcSessionManager to change its default parameters. You can also enable JdbcSessionManager for a particular context if the server is running in single process mode. To enable iPlanet Web Server to use JdbcSessionManager, do any of the following:

Use the Servlets>Configure Global Servlet Attributes page in the Server Manager interface.

In the Session Manager field specify:

com.netscape.server.http.session.JdbcSessionManager

You can also specify parameters for the session manager in the Session Manager Args field, for example:

timeOut=1200,username=mysession,password=mypassword

Edit the file servlets.properties in the directory server_id/config.

Add a line specifying a value for servlets.sessionmgr and a line specifying the parameters for the session manager:

servlets.sessionmgr=com.netscape.server.http.session.JdbcSessionManager
servlets.sessionmgr.initArgs=timeOut=1200,username=mysession,password=mypassword

Edit the file contexts.properties in the directory server_id/config.

Add a line specifying a value for context.context_name.sessionmgr and a line specifying the parameters for the session manager:

context.global.sessionmgr=com.netscape.server.http.session.JdbcSessionManager
context.global.sessionmgr.initArgs=timeOut=1200,username=mysession,password=mypassword

You can change the global context or define a new context and assign specific servlets to it. For more information, see

Appendix C, "Properties Files."

This session manager can only store objects that implement java.io.Serializable.

Source Code for JDBCSessionManager

The JdbcSessionManager creates a JdbcSession object for each session. The source files JdbcSessionManager.java and JdbcSession.java are in the directory server_root/plugins/samples/servlets/sessions/JdbcSession.

The source code files, JdbcSessionManager.java and JdbcSession.java, are provided so you can use them as the starting point for defining your own session managers and session objects. These files are very well commented.

JdbcSessionManager extends NSHttpSessionManager. The class file for NSHttpSessionManager is in the JAR file NSServletLayer.jar in the directory server_root/bin/https/jar. The JdbcSessionManager implements all the methods in NSHttpSessionManager that need to be implemented, so you can use JdbcSessionManager as an example of how to extend NSHttpSessionManager. When compiling your subclass of JdbcSessionManager or NSHttpSessionManager, be sure that the JAR file NSServletLayer.jar is in your compiler's classpath.

How Do Servlets Access Session Data?

To access the state information stored in a session object, your servlet can create a new session as follows:

// request is an HttpServletRequest that is passed to the servlet
SessionClass session = request.getSession(true);

The servlet can call any of the public methods in javax.servlet.http.HttpSession on the session object. These methods include (among others):

getCreationTime
getId
getLastAccessedTime
getMaxInactiveInterval
getValue

For more information about the classes HttpServletRequest and HttpSession, see Sun Microsystem's API Servlets Documentation at:

http://java.sun.com/products/servlet/2.1/html/api-reference.fm.html

Table of Contents | Previous | Next | Index

Last Updated: 03/01/00 13:47:14

Appendix A Session Managers

Appendix A
Session Managers