Sun Java System Web Server 6.1 SP12 Programmer's Guide to Web Applications

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.

In compliance with the Java Servlet 2.3 API specification, session managers allow for session scoping only by web application.

To successfully restore the state of session attributes, all such attributes must implement the java.io.Serializable interface. You can configure the session manager to enforce this restriction by including the distributable element in the web application deployment descriptor file, web.xml.

Sun Java System Web Server 6.1 provides the following session management options, which are described in this section:


Note –

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


StandardManager

The StandardManager is the default session manager.

Enabling StandardManager

You may want to specify StandardManager explicitly to change its default parameters. To do so, edit the sun-web.xml file for the web application as in the following example. Note that persistence-type must be set to memory.

<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, Chapter 7, Deploying Web Applications.

Manager Properties for StandardManager

The following table describes manager-properties properties for the StandardManager session manager. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 4–4 manager-properties Properties for StandardManager

Property Name  

Default Value  

Description  

reapIntervalSeconds

60

Specifies the number of seconds between checks for expired sessions. 

Setting this value lower than the frequency at which session data changes is recommended. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed web site, or you could lose the last few hits each time you restart the server. 

maxSessions

-1 

Specifies the maximum number of active sessions, or -1 (the default) for no limit.

sessionFilename

SESSIONS

Specifies the absolute or relative path name of the file in which the session state is preserved between application restarts, if preserving the state is possible. A relative path name is relative to the temporary directory for this web application. 

PersistentManager

The PersistentManager is another session manager provided with Sun Java System Web Server. For session persistence, PersistentManager can use a file, to which each session is serialized. You can also create your own persistence mechanism.

Enabling PersistentManager

You may want to specify PersistentManager explicitly to change its default parameters. To do so, edit the sun-web.xml file for the web application as in the following example. Note that persistence-type must be set to file.

<sun-web-app>
        ...
        <session-config>
           <session-manager persistence-type=”file”>
              <manager-properties>
                 <property name=reapIntervalSeconds value=20 >
              </manager-properties>
              <store-properties>
                 <property name=directory value=sessions >
              </store-properties>
           </session-manage>
           ...
        </session-config>
        ...
</sun-web-app>

For more information about the sun-web.xml file, Chapter 7, Deploying Web Applications.

Manager Properties for PersistentManager

The following table describes manager-properties properties for the PersistentManager session manager. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 4–5 manager-properties Properties for PersistentManager

Property Name  

Default Value  

Description  

reapIntervalSeconds

60

Specifies the number of seconds between checks for expired sessions. 

Setting this value lower than the frequency at which session data changes is recommended. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed web site, or you could lose the last few hits each time you restart the server. 

maxSessions

-1 

Specifies the maximum number of active sessions, or -1 (the default) for no limit.

IWSSessionManager

The IWSSessionManager ensures backward compatibility with any custom session managers that you may have created on Sun Java System Web Server 6.0.

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 or multi-process mode.


Note –

If the value of MaxProcs is higher than 1 and no session manager is configured, then by default the session manager used is the IWSSessionManager with file-based persistence.


For more information on the MaxProcs directive, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

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 Sun Java System Web Server is running in single-process mode, then by default, no session persistence mode is defined and therefore sessions are not persistent.

If Sun Java System 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.

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 do so, edit the sun-web.xml file for the web application as in the following example. Note that persistence-type must be set to s1ws60.

<sun-web-app>
   ...
   <session-config>
    <session-manager persistence-type=”s1ws60”>
     <manager-properties>
      <property name=”classname” value=”com.iplanet.server.http.
                                       session.IWSSessionManager”>
      // other manager-related properties
     </manager-properties>
    </session-manager> 
     ...
   </session-config>
   ...
</sun-web-app>

In the case of persistent sessions:

<sun-web-app>
   ...
   <session-config>
    <session-manager persistence-type=”s1ws60”>
     <manager-properties>
      <property name=”classname” value=”com.iplanet.server.http.
                                       session.IWSSessionManager”>
      // other manager-related properties
     </manager-properties>
     <store-properties>
       <property name=”classname” value=”com.iplanet.server.http.
                                               session.FileStore”>
       <property name=”directory” value=”<directory name to store the persistant sessions>”>
       // other store-related properties
     </store-properties>
    </session-manager> 
     ...
   </session-config>
   ...
</sun-web-app>

For more information about the sun-web.xml file, Chapter 7, Deploying Web Applications.

Manager Properties for IWSSessionManager

The following table describes manager-properties properties for the IWSSessionManager session manager. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 4–6 manager-properties Properties for IWSSessionManager

Property Name  

Default Value  

Description  

maxSessions

1000

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.

timeOut

1800

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.

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

reapInterval

600

The amount of time in seconds that the SessionReaper thread sleeps before calling the reaper method again.

maxLocks

10

The number of cross-process locks to use for synchronizing access to individual sessions across processes. The 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 Sun Java System 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 session-data-store class. You can create your own class that implements session persistence by extending SessionDataStore.

session-failover-enabled

 

Specifies whether sessions are reloaded from the persistent store for every request, and always forced to true in multi-process mode.

Applicable only if the session-data-store parameter is set to the JdbcStore or FileStore class.

session-data-dir

(this should all be on one line) 

server_root/server_id/SessionData/virtual_server_id/web_app_URI

The directory in which session data for all servers and web applications is kept. 

Applicable only if the session-data-store parameter is set to the FileStore class.

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

Applicable only if the session-data-store parameter is set to the JdbcStore class.

url

jdbc:odbc:LocalServer

Specifies the data source. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

table

sessions

Name of the SQL table that store sessions. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

username

none 

The login user name for the database. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

password

none 

The login password for the database. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

reaperActive

true

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.

Applicable only if the session-data-store parameter is set to the JdbcStore class.

accessTimeColumn

AccessTime

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

Applicable only if the session-data-store parameter is set to the JdbcStore class.

timeOutColumn

TimeOut

The name of the column that holds the session timeout in minutes. The SQL type is NUMERIC(9). 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

sessionIdColumn

SessionID

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

Applicable only if the session-data-store parameter is set to the JdbcStore class.

valueColumn

Value

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

Applicable only if the session-data-store parameter is set to the JdbcStore class.

lookupPool

4

The number of dedicated connections that perform search operations on the database. Each of these connections would have a precompiled SQL statement for higher performance. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

insertPool

4

The number of dedicated connections that perform insert operations on the database. Each of these connections would have a precompiled SQL statement for higher performance. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

updatePool

4

The number of dedicated connections that perform update operations on the database. Each of these connections would have a precompiled SQL statement for higher performance. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.

deletePool

2

The number of dedicated connections that perform delete operations on the database. Each of these connections would have a precompiled SQL statement for higher performance. 

Applicable only if the session-data-store parameter is set to the JdbcStore class.


Note –

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/java/apis 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 webserv-rt.jar in the directory server_root/bin/https/jar. The IWSSessionManager implements all of 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 webserv-rt.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/java/apis directory.

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 or multi-process mode. For more information, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

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 do so, edit the sun-web.xml file for the web application as in the following example. Note that persistence-type must be set to mmap.

<sun-web-app>
        ...
        <session-config>
            <session-manager persistence-type=”mmap”>
              ...
          </session-manager>
           ...
        </session-config>
        ...
</sun-web-app>

For more information about the sun-web.xml file, see Chapter 7, Deploying Web Applications

Manager Properties for MMapSessionManager

The following table describes manager-properties properties for the MMapSessionManager session manager. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 4–7 manager-properties Properties for MMapSessionManager

Property Name  

Default Value  

Description  

maxSessions

1000

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.

maxValuesPerSession

10

The maximum number of values or objects a session can hold. 

maxValueSize

4096

The maximum size of each value or object that can be stored in the session. 

timeOut

1800

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.

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

reapInterval

600

The amount of time in seconds that the SessionReaper thread sleeps before calling the reaper method again.

maxLocks

1

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


Note –

The MMapSessionManager can only store objects that implement java.io.Serializable.