Skip navigation.
Downloads | Product Documentation | Support

Developing Web Applications for WebLogic Server

# Using Sessions and Session Persistence in Web Applications

The following sections describe how to set up sessions and session persistence:

- Overview of HTTP Sessions
- Setting Up Session Management
- Configuring Session Persistence
- Using URL Rewriting Instead of Cookies

# Overview of HTTP Sessions

Session tracking enables you to track a user's progress over multiple servlets or HTML pages, which, by nature, are stateless. A session is defined as a series of related browser requests that come from the same client during a certain time period. Session tracking ties together a series of browser requests—think of these requests as pages—that may have some meaning as a whole, such as a shopping cart application.

# Setting Up Session Management

WebLogic Server is set up to handle session tracking by default. You need not set any of these properties to use session tracking. However, configuring how WebLogic Server manages sessions is a key part of tuning your application for best performance. When you set up session management, you determine factors such as:

- How many users you expect to hit the servlet
- How long each session lasts
- How much data you expect to store for each user
- Heap size allocated to the WebLogic Server instance

You can also store data permanently from an HTTP session. See Configuring Session Persistence.

For information on editing deployment descriptors, see Deployment Descriptors in Deploying Web Applications.

## HTTP Session Properties

You configure WebLogic Server session tracking by defining properties in the WebLogic-specific deployment descriptor, `weblogic.xml`. For a complete list of session attributes, see session-descriptor.

WebLogic Server 7.0 introduced a change to the SessionID format that caused some load balancers to lose the ability to retain session stickiness.

A new server startup flag, -Dweblogic.servlet.useExtendedSessionFormat=true , retains the information that the load-balancing application needs for session stickiness. The extended session ID format will be part of the URL if URL rewriting is activated, and the startup flag is set to true.

## Session Timeout

You can specify an interval of time after which HTTP sessions expire. When a session expires, all data stored in the session is discarded. You can set the interval in either web.xml or weblogic.xml:

- Set the `TimeoutSecs` attribute in the session-descriptor element of the WebLogic-specific deployment descriptor, `weblogic.xml.` This value is set in seconds. For more information, see session-descriptor.
- Set the session-timeout element in the Web Application deployment descriptor, `web.xml`. For more information, see session-config.

## Configuring WebLogic Server Session Cookies

WebLogic Server uses cookies for session management when cookies are supported by the client browser.

The cookies that WebLogic Server uses to track sessions are set as transient by default and do not outlive the session. When a user quits the browser, the cookies are lost and the session ends. This behavior is in the spirit of session usage and it is recommended that you use sessions in this way.

You can configure session-tracking attributes of cookies in the WebLogic-specific deployment descriptor, `weblogic.xml`. A complete list of session and cookie-related attributes is available in session-descriptor.

## Configuring Application Cookies That Outlive a Session

For longer-lived client-side user data, you program your application to create and set its own cookies on the browser via the HTTP servlet API. The application should not attempt to use the cookies associated with the HTTP session. Your application might use cookies to auto-login a user from a particular machine, in which case you would set a new cookie to last for a long time. Remember that the cookie can only be sent from that particular client machine. Your application should store data on the server if it must be accessed by the user from multiple locations.

You cannot directly connect the age of a browser cookie with the length of a session. If a cookie expires before its associated session, that session becomes orphaned. If a session expires before its associated cookie, the servlet is not be able to find a session. At that point, a new session is automatically assigned when the `request.getSession(true)` method is called.

You can set the maximum life of a cookie with the `CookieMaxAgeSecs` attribute in the session descriptor of the `weblogic.xml` deployment descriptor.

## Logging Out and Ending a Session

User authentication information is stored both in the user's session data and in the context of a server or virtual host that is targeted by a Web application. The `session.invalidate()` method, which is often used to log out a user, only invalidates the current session for a user—the user's authentication information still remains valid and is stored in the context of the server or virtual host. If the server or virtual host is hosting only one Web application, the `session.invalidate()` method, in effect, logs out the user.

There are several Java methods and strategies you can use when using authentication with multiple Web applications. For more information, see Implementing Single Sign-On in Programming WebLogic HTTP Servlets.

# Configuring Session Persistence

You use session persistence to permanently store data from an HTTP session object to enable failover and load balancing across a cluster of WebLogic Servers. When your applications stores data in an HTTP session object, the data must be serializable.

There are five different implementations of session persistence:

- Memory (single-server, non-replicated)
- File system persistence
- JDBC persistence
- Cookie-based session persistence
- In-memory replication (across a cluster)

The first four are discussed here; in-memory replication is discussed in HTTP Session State Replication, in Using WebLogic Server Clusters

File, JDBC, cookie-based, and memory (single-server, non-populated) session persistence have some common properties. Each persistence method has its own set of attributes, as discussed in the following sections. These attributes are part of the session-param element, which is a child element of the session-descriptor element in the weblogic.xml deployment descriptor file.

## Attributes Shared by Different Types of Session Persistence

This section describes attributes common to file and JDBC-based persistence. You can configure the number of sessions that are held in memory by defining the following attributes in the `<session-param>` element of the WebLogic-specific deployment descriptor, `weblogic.xml`. These properties are only applicable if you are using session persistence:

  `CacheSize`

  Limits the number of cached sessions that can be active in memory at any one time. If you expect high volumes of simultaneous active sessions, you do not want these sessions to soak up the RAM of your server because this may cause performance problems swapping to and from virtual memory. When the cache is full, the least recently used sessions are stored in the persistent store and recalled automatically when required. If you do not use persistence, this property is ignored, and there is no soft limit to the number of sessions allowed in main memory. By default, the number of cached sessions is 256. To turn off caching, set this to 0.

Note: `CacheSize` is used by JDBC and file-based sessions only for maintaining the in-memory bubbling cache. It is not applicable for other persistence types.

  `InvalidationIntervalSecs`

  Sets the time, in seconds, that WebLogic Server waits between doing house-cleaning checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Set this attribute to a value less than the value set for the `<session-timeout>` element. Use this attribute to tune WebLogic Server for best performance on high traffic sites.

  The minimum value is every second (1). The maximum value is once a week (604,800 seconds). If not set, the attribute defaults to 60 seconds.

  To set `<session-timeout>`, see session-config.

## Using Memory-based, Single-server, Non-replicated Persistent Storage

When you use memory-based storage, all session information is stored in memory and is lost when you stop and restart WebLogic Server. To use memory-based, single-server, non-replicated persistent storage, set the `PersistentStoreType` attribute in the `<session-param>` element of `weblogic.xml` file to memory.

Note: If you do not allocate sufficient heap size when running WebLogic Server, your server may run out of memory under heavy load.

## Using File-based Persistent Storage

To configure file-based persistent storage for sessions:

1. In the deployment descriptor file `weblogic.xml`, set the `PersistentStoreType` attribute in the `<session-param>` element to `file`.
2. Set the directory where WebLogic Server stores the sessions. See PersistentStoreDir.

Note: You must create this directory yourself and make sure appropriate access privileges have been assigned to the directory.

## Using a Database for Persistent Storage (JDBC persistence)

JDBC persistence stores session data in a database table using a schema provided for this purpose. You can use any database for which you have a JDBC driver. You configure database access by using connection pools.

Because WebLogic Server uses the system time to determine the session lifetime when using JDBC session persistence, you must be sure to synchronize the system clock on all of the machines on which servers are running in the same cluster.

To configure JDBC-based persistent storage for sessions:

1. In weblogic.xml, set the `PersistentStoreType` attribute in the `<session-param>` element to `jdbc.`
2. Set a JDBC connection pool to be used for persistence storage with the `PersistentStorePool` property in the `<session-descriptor>` element of the WebLogic-specific deployment descriptor, `weblogic.xml`. Use the name of a connection pool that is defined in the WebLogic Server Administration Console.
3. Set up a database table named `wl_servlet_sessions` for JDBC-based persistence. The connection pool that connects to the database needs to have read/write access for this table.

Note: Create indexes on `wl_id` and `wl_context_path`, if the database does not create them automatically. Some databases create indexes automatically for primary keys.

Set up column names and data types as follows.

Table 4-1

Column Name | Data Type
--- | ---
`wl_id` | Variable-width alphanumeric column, up to 100 characters; for example, Oracle `VARCHAR2(100)`. The primary key must be set as follows: `wl_id + wl_context_path.`
`wl_context_path` | Variable-width alphanumeric column, up to 100 characters; for example, Oracle `VARCHAR2(100)`. This column is used as part of the primary key. (See the `wl_id` column description.)
`wl_is_new` | Single char column; for example, Oracle `CHAR(1)`
`wl_create_time` | Numeric column, 20 digits; for example, Oracle `NUMBER(20)`
`wl_is_valid` | Single char column; for example, Oracle `CHAR(1)`
`wl_session_values` | Large binary column; for example, Oracle `LONG RAW`
`wl_access_time` | Numeric column, 20 digits; for example, `NUMBER(20)`
`wl_max_inactive_interval` | Integer column; for example, Oracle `Integer`. Number of seconds between client requests before the session is invalidated. A negative time value indicates that the session should never time out.

Creating wl_servlet_sessions table

If you are using an Oracle DBMS, use the following SQL statement to create the `wl_servlet_sessions` table. Modify the SQL statement for use with your DBMS.

Listing 4-1 Creating wl_servlet_sessions table with Oracle DBMS

>     create table wl_servlet_sessions
>       ( wl_id VARCHAR2(100) NOT NULL,
>         wl_context_path VARCHAR2(100) NOT NULL,
>         wl_is_new CHAR(1),
>         wl_create_time NUMBER(20),
>         wl_is_valid CHAR(1),
>         wl_session_values LONG RAW,
>         wl_access_time NUMBER(20),
>         wl_max_inactive_interval INTEGER,
>        PRIMARY KEY (wl_id, wl_context_path) );

Note: You can use the `JDBCConnectionTimeoutSecs` attribute to configure a maximum duration that JDBC session persistence should wait for a JDBC connection from the connection pool before failing to load the session data. For more information, see JDBCConnectionTimeoutSecs.

If you are using SqlServer2000, use the following SQL statement to create the `wl_servlet_sessions` table. Modify the SQL statement for use with your DBMS.

Listing 4-2 Creating wl_servlet_sessions table with SqlServer 2000

>     create table wl_servlet_sessions
>       ( wl_id VARCHAR2(100) NOT NULL,
>         wl_context_path VARCHAR2(100) NOT NULL,
>         wl_is_new VARCHAR(1),
>         wl_create_time DECIMAL,
>         wl_is_valid VARCHAR(1),
>         wl_session_values IMAGE,
>         wl_access_time DECIMAL,
>         wl_max_inactive_interval INTEGER,
>        PRIMARY KEY (wl_id, wl_context_path) );

If you are using Pointbase, Pointbase translates the SQL. For example, Pointbase would translate the SQL provided in Listing 4-1 as follows.

Listing 4-3 Creating wl_servlet_sessions table with Pointbase SQL Translation

>     SQL> describe wl_servlet_sessions;

>     WL_SERVLET_SESSIONS

>     WL_ID VARCHAR(100) NULLABLE: NO

>     WL_CONTEXT_PATH VARCHAR(100) NULLABLE: NO

>     WL_IS_NEW CHARACTER(1) NULLABLE: YES

>     WL_CREATE_TIME DECIMAL(20) NULLABLE: YES

>     WL_IS_VALID CHARACTER(1) NULLABLE: YES

>     WL_SESSION_VALUES BLOB(65535) NULLABLE: YES

>     WL_ACCESS_TIME DECIMAL(20) NULLABLE: YES

>     WL_MAX_INACTIVE_INTERVAL INTEGER(10) NULLABLE: YES

>     Primary Key: WL_CONTEXT_PATH

>     Primary Key: WL_ID

## Using Cookie-Based Session Persistence

Cookie-based session persistence provides a stateless solution for session persistence by storing all session data in a cookie in the user's browser. Cookie-based session persistence is most useful when you do not need to store large amounts of data in the session. Cookie-based session persistence can make managing your WebLogic Server installation easier because clustering failover logic is not required. Because the session is stored in the browser, not on the server, you can start and stop WebLogic Servers without losing sessions.

There are some limitations to cookie-based session persistence:

- You can store only string attributes in the session. If you store any other type of object in the session, an `IllegalArgument` exception is thrown.
- You cannot flush the HTTP response (because the cookie must be written to the header data before the response is committed).
- If the content length of the response exceeds the buffer size, the response is automatically flushed and the session data cannot be updated in the cookie. (The buffer size is, by default, 8192 bytes. You can change the buffer size with the `javax.servlet.ServletResponse.setBufferSize()` method.
- You can only use basic (browser-based) authentication.
- Session data is sent to the browser in clear text.
- The user's browser must be configured to accept cookies.
- You cannot use commas (,) in a string when using cookie-based session persistence or an exception occurs.

To set up cookie-based session persistence:

1. In the `<session-param>` element of `weblogic.xml`, set the `PersistentStoreType` attribute to `cookie.`
2. Optionally, set a name for the cookie using the `PersistentStoreCookieName` attribute. The default is `WLCOOKIE`.

# Using URL Rewriting Instead of Cookies

In some situations, a browser or wireless device may not accept cookies, which makes session tracking with cookies impossible. URL rewriting is a solution to this situation that can be substituted automatically when WebLogic Server detects that the browser does not accept cookies. URL rewriting involves encoding the session ID into the hyper-links on the Web pages that your servlet sends back to the browser. When the user subsequently clicks these links, WebLogic Server extracts the ID from the URL address and finds the appropriate `HttpSession` when your servlet calls the `getSession()` method.

Enable URL rewriting in WebLogic Server by setting the `URLRewritingEnabled` attribute in the WebLogic-specific deployment descriptor, `weblogic.xml`, under the `<session-param>` element.`` The default value for this attribute is `true`. See URLRewritingEnabled.

## Coding Guidelines for URL Rewriting

Here are general guidelines for supporting URL rewriting.

- Avoid writing a URL straight to the output stream, as shown here:

>     out.println("<a href=\"/myshop/catalog.jsp\">catalog</a>");

Instead, use the `HttpServletResponse.encodeURL()` method, for example:

>     out.println("<a href=\""
>          + response.encodeURL("myshop/catalog.jsp")
>          + "\">catalog</a>");

Calling the `encodeURL()` method determines whether the URL needs to be rewritten. If it does need to be rewritten, WebLogic Server rewrites the URL by appending the session ID to the URL, with the session ID preceded by a semicolon.

- In addition to URLs that are returned as a response to WebLogic Server, also encode URLs that send redirects. For example:

>     if (session.isNew())
>       response.sendRedirect (response.encodeRedirectUrl(welcomeURL));

WebLogic Server uses URL rewriting when a session is new, even if the browser does accept cookies, because the server cannot tell whether a browser accepts cookies in the first visit of a session.

- Your servlet can determine whether a given session ID was received from a cookie by checking the Boolean returned from the `HttpServletRequest.isRequestedSessionIdFromCookie()` method. Your application may respond appropriately, or simply rely on URL rewriting by WebLogic Server.

## URL Rewriting and Wireless Access Protocol (WAP)

If you are writing a WAP application, you must use URL rewriting because the WAP protocol does not support cookies.

In addition, some WAP devices have a 128-character limit on the length of a URL (including attributes), which limits the amount of data that can be transmitted using URL rewriting. To allow more space for attributes, you can limit the size of the session ID that is randomly generated by WebLogic Server.

In particular, to use the `WAPEnabled` attribute, use the Administration Console at Server —>Protocols—> HTTP—> Advanced Options. The `WAPEnabled` attribute restricts the size of the session ID to 52 characters and disallows special characters, such as ! and #. You can also use the IDLength parameter of weblogic.xml to further restrict the size of the session ID. For additional details, see IDLength.