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 usuallycorresponds 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

• Specifying a Session Manager

• SimpleSessionManager

• JdbcSessionManager

• How Do Servlets Access Session Data?

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 these session managers for creating and managing sessions:

• SimpleSessionManager -- the default session manager.

• 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 iPlanet Web Server uses SimpleSessionManager as the session manager for servlets.

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 is loaded by default 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. 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 server_root/plugins/samples/servlets/sessions/SimpleSession directory.

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.

JdbcSessionManager

---

This is a persistent JDBC-based session manager. It can be used to store sessions in a custom database.

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. 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 Appendix G "API Clarifications," and the Servlets API Javadoc published by Sun Microsystems at:

http://java.sun.com/products/servlet/2.2/javadoc/index.html