Previous     Contents     Index     DocHome     Next     
iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets



Chapter 6   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.

iPlanet Web Server 6.0 comes with these session managers for creating and managing sessions:

  • IWSSessionManager -- the default session manager, which can use a database or a file store for persistent sessions, and can run in single-process or multi-process mode.

  • MMapSessionManager (Unix Only) -- a session manager for running the server in multi-process mode. Does not support distributed sessions.

  • SimpleSessionManager -- a deprecated simple session manager. Does not support distributed sessions.

  • JdbcSessionManager -- a deprecated session manager that stores session information in a database using the JDBC API and that supports distributed sessions.

Multi-process mode is supported only on Unix platforms. All multi-process mode features of session managers are ignored on Windows NT.

iPlanet Web Server 6.0 also allows you to develop your own session managers and load them into the server. The source code files for session manager 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/servlets/iws-apis/sessions.



Specifying a Session Manager


By default iPlanet Web Server uses IWSSessionManager as the session manager for servlets. You can change the session manager in any of the following ways:

  • Edit the file web-apps.xml in the directory server_id/config.

    Add a session-manager element within the web-app element for the servlet or JSP as in the following example:

    <session-manager
       class='com.iplanet.server.http.session.YourSesMgr'
       <init-param>
          <param-name>maxSessions</param-name>
          <param-value>1000</param-value>
       </init-param>
       <init-param>
          <param-name>timeOut</param-name>
          <param-value>1800</param-value>
       </init-param>
       <init-param>
          <param-name>reapInterval</param-name>
          <param-value>600</param-value>
       </init-param>
    </session-manager>

    For more information about the web-apps.xml file, see Chapter 2 "Web Applications."

  • Use the Legacy 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. This will apply to the default virtual server only.

    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.iplanet.server.http.session.YourSesMgr
    servlets.sessionmgr.initArgs=maxSessions=20,timeOut=300,reapInterval=150

  • Edit the file contexts.properties in the directory server_id/config. This will apply to the default virtual server only.

    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.iplanet.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 Chapter 8 "Legacy Servlet and JSP Configuration."



IWSSessionManager

The IWSSessionManager is the default session manager.

IWSSessionManager 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. The MaxProcs directive in the magnus.conf file determines whether the server is running in single process mode or multi-process mode. For more information, see the NSAPI Programmer's Guide for iPlanet Web Server.

For session persistence, IWSSessionManager can use a database or a distributed file system (DFS) path that is accessible from all servers in a server farm. Each session is serialized to the database or distributed file system. You can also create your own persistence mechanism.

If iPlanet Web Server is running in single-process mode, then by default, no session persistence mode is defined and therefore sessions are not persistent.

If iPlanet Web Server is running in multi-process mode, sessions are persistent by default. If a persistence mode is not defined, IWSSessionManager uses a DFS.

Multi-process mode is supported only on Unix platforms. All multi-process mode features of IWSSessionManager are ignored on Windows NT.


Parameters for IWSSessionManager

IWSSessionManager 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).

    If session-timeout is specified in web.xml, it overrides this timeOut parameter value. For details, see "session-timeout."

  • 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).

  • maxLocks - the number of cross-process locks to use for synchronizing access to individual sessions across processes. The default value is 10. This default value is used if the value 0 is specified. This parameter is ignored in single-process mode.

  • session-data-store - the name of the class that determines the means of session persistence. The classes supplied with iPlanet Web Server are:

    • com.iplanet.server.http.session.JdbcStore

    • com.iplanet.server.http.session.FileStore

    If you do not specify the session-data-store parameter, sessions are not persistent in single-process mode, and FileStore is the default in multi-process mode.

    The JdbcStore and FileStore classes are subclasses of the SessionDataStore class. You can create your own class that implements session persistence by extending SessionDataStore.


    Note Prior to using JdbcStore, you must create the table in which the session information is stored. The name of the table is specified by the table parameter, and the table's four columns are specified by the accessTimeColumn, timeOutColumn, sessionIdColumn, and valueColumn parameters.


If the session-data-store parameter is set to the JdbcStore or FileStore class, IWSSessionManager takes the following additional parameter:

  • session-failover-enabled - specifies whether sessions are reloaded from the persistent store for every request, and always forced to true in multi-process mode.

If the session-data-store parameter is set to the FileStore class, IWSSessionManager takes the following additional parameter:

  • session-data-dir - the directory in which session data for all servers and web applications is kept.

    If the session-data-dir parameter is not specified, the following directory is used by default:

    server_root/server_id/SessionData/virtual_server_id/web_app_URI

If the session-data-store parameter is set to the JdbcStore class, IWSSessionManager takes the following additional parameters:

  • 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


    Note The JdbcStore class does not recognize JDBC driver classes assigned to the classpath attribute of the class-loader element in web-apps.xml. Assign them to the jvm.classpath variable in the jvm12.conf file instead. For more information, see Appendix C "JVM Configuration."


  • 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).

  • timeOutColumn - the name of the column that holds the session timeout in minutes (the default name is TimeOut). 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 IWSSessionManager

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

  • Edit the file web-apps.xml in the directory server_id/config.

    Add a session-manager element within the web-app element for the servlet or JSP as in the following example:

    <session-manager
       class='com.iplanet.server.http.session.    IWSSessionManager'
       <init-param>
          <param-name>maxSessions</param-name>
          <param-value>1000</param-value>
       </init-param>
       <init-param>
          <param-name>timeOut</param-name>
          <param-value>1800</param-value>
       </init-param>
       <init-param>
          <param-name>reapInterval</param-name>
          <param-value>600</param-value>
       </init-param>
       <init-param>
          <param-name>    session-data-dir</param-name>
          <param-value>    /net/dotcom.com/sessions</param-value>
       </init-param>
    </session-manager>

    For more information about the web-apps.xml file, see Chapter 2 "Web Applications."

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

    In the Session Manager field specify:

    com.iplanet.server.http.session.IWSSessionManager

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

    maxSessions=20,session-data-dir=/net/dotcom.com/sessions


Source Code for IWSSessionManager

The IWSSessionManager creates an IWSHttpSession object for each session. The source files for IWSSessionManager.java and IWSHttpSession.java are in the server_root/plugins/servlets/iws-apis/sessions directory. The source code files for IWSSessionManager.java and IWSHttpSession.java are provided so you can use them as the starting point for defining your own session managers and session objects.

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

The JdbcStore.java and FileStore.java source files and the source file for the parent class, SessionDataStore.java, are provided so you can modify the session persistence mechanism of IWSSessionManager. These files are also located in the directory server_root/plugins/servlets/iws-apis/sessions.



MMapSessionManager (Unix Only)


This is a persistent memory map (mmap) file based session manager that works in both single process and multi-process mode.

The MaxProcs directive in the magnus.conf file determines whether the server is running in single process mode or multi-process mode. For more information, see the NSAPI Programmer's Guide for iPlanet Web Server.


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. The default value is 10.

  • maxValueSize - the maximum size of each value or object that can be stored in the session. The default value is 4096.

  • 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).

    If session-timeout is specified in web.xml, it overrides this timeOut parameter value. For details, see "session-timeout."

  • 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).

  • maxLocks - the number of cross-process locks to use for synchronizing access to individual sessions across processes. The default value is 1. This default value is used if the value 0 is specified. This parameter is ignored in single-process mode.


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 Legacy Servlets>Configure Global Servlet Attributes page in the Server Manager interface.

    In the Session Manager field specify:

    com.iplanet.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

  • Edit the file servlets.properties in the directory server_id/config. This will apply to the default virtual server only.

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

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

  • Edit the file contexts.properties in the directory server_id/config. This will apply to the default virtual server only.

    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.iplanet.server.http.session.MMapSessionManager
    context.global.sessionmgr.initArgs=maxSessions=20,maxValueSize=1024,timeOut=300

    You can change the global context or define a new context and assign specific servlets to it. For more information, see Chapter 8 "Legacy Servlet and JSP Configuration."

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


Deleting SessionData Version Files

If the server uses the MMapSessionManager session manager, it stores persistent session information in the SessionData directory. This cache has a Version file containing a version number that the server uses to determine the structure of the directories and files in the caches. You can clean out the caches by simply deleting the version file.

When the server starts up, if it does not find the version file, it deletes the directory structures for the corresponding caches and re-creates the version file. The next time the server serves a servlet while using MMapSessionManager session manager, it recreates the session data cache.

You can delete the version file simply by deleting it from the SessionData directory as you would normally delete a file, or you can use the Java>Delete Version Files page in the Server Manager to delete it. After deleting the version file, be sure to restart the iPlanet Web Server to force it to clean up the appropriate caches and to recreate the version file before the server serves any servlets.



Deprecated Session Managers


The SimpleSessionManager and the JdbcSessionManager are provided for backward compatibility with iPlanet Web Server 4.x.


Note The parent class of the deprecated session managers is also deprecated and is included for backward compatibility only:

com.netscape.server.http.session.NSHttpSessionManager

Extend the following class instead:

com.iplanet.server.http.session.IWSHttpSessionManager



SimpleSessionManager

The SimpleSessionManager works only in single process mode. Its sessions are not persistent, that is, all sessions are lost when the server is stopped.


Note The SimpleSessionManager is deprecated and is included for backward compatibility only. Use IWSSessionManager with no session persistence instead.



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).

    If session-timeout is specified in web.xml, it overrides this timeOut parameter value. For details, see "session-timeout."

  • 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 Legacy 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. This will apply to the default virtual server only.

    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. This will apply to the default virtual server only.

    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 Chapter 8 "Legacy Servlet and JSP Configuration."


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.


Note The JDBCSessionManager is deprecated and is included for backward compatibility only. Use IWSSessionManager with JdbcStore session persistence instead.


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).

    If session-timeout is specified in web.xml, it overrides this timeOut parameter value. For details, see "session-timeout."

  • 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


    Note The JdbcStore class does not recognize JDBC driver classes assigned to the classpath attribute of the class-loader element in web-apps.xml. Assign them to the jvm.classpath variable in the jvm12.conf file instead. For more information, see Appendix C "JVM Configuration."


  • 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 Legacy 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. This will apply to the default virtual server only.

    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. This will apply to the default virtual server only.

    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 Chapter 8 "Legacy Servlet and JSP Configuration."

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



Load Balancing, Session Failover, and Session IDs


iPlanet Web Server 6.0 supports server farm (or cluster) configurations with off-the-shelf, session-aware front-end load balancers such as Resonate. iPlanet Web Server 6.0 implements sticky sessions by prefixing the node_id of the server host that generated the session to JSESSIONID, the session cookie name specified in the Servlets 2.2 specification, as follows:

Set-Cookie: JSESSIONID=node_id-3ad%253A39c02099%253Ad19e53e2a2;
path=/app;expires=Thu, 14-Sep-2000 01:19:30 GMT

This enables the front-end load balancer to forward future requests to the same host that generated the session.

If the session manager used by a cluster supports distributed sessions, an alternate server can pick up a session created by a server that crashed. The IWSSessionManager supports distributed sessions if its session-data-store parameter has a value that defines the mode of session persistence. The JdbcSessionManager also supports distributed sessions.


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 IWSSessionManager.java example file described in "Source Code for IWSSessionManager").



Note iPlanet Web Server session managers generate session IDs with a maximum length of 108 ASCII characters.



Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated May 02, 2001