10 Using Sessions and Session Persistence

This chapter describes how to set up and use HTTP sessions and session persistence in WebLogic Server.

This chapter includes the following sections:

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.

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.

In a previous WebLogic Server release, a change was introduced to the SessionID format that caused some load balancers to lose the ability to retain session stickiness. A 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 timeout-secs parameter value 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 Java EE standard Web application deployment descriptor, web.xml.

Limiting the Number of Concurrent Requests for a Session

The weblogic.http.session.maxConcurrentRequest property can be specified to limit the number of concurrent requests for a session. If the number of concurrent requests for a given session exceeds the specified value, the servlet container starts rejecting requests. By default, this property is set to -1, which indicates the servlet container does not impose any restrictions.

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 parameters of cookies in the WebLogic-specific deployment descriptor, weblogic.xml. A complete list of session and cookie-related parameters 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 cookie-max-age-secs element in the session descriptor of the weblogic.xml deployment descriptor. See session-descriptor.

Logging Out

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 Logging Out and Ending a Session.

Enabling Web Applications to Share the Same Session

By default, Web applications do not share the same session. If you would like Web applications to share the same session, you can configure the session descriptor at the application level in the weblogic-application.xml deployment descriptor. To enable Web applications to share the same session, set the sharing-enabled attribute in the session descriptor to true in the weblogic-application.xml deployment descriptor. See "sharing-enabled" in session-descriptor.

The session descriptor configuration that you specify at the application level overrides any session descriptor configuration that you specify at the Web application level for all of the Web applications in the application. If you set the sharing-enabled attribute to true at the Web application level, it will be ignored.

All Web applications in an application are automatically started using the same session instance if you specify the session descriptor in the weblogic-application.xml deployment descriptor and set the sharing-enabled attribute to true as in the following example:

<?xml version="1.0" encoding="ISO-8859-1"?>

<weblogic-application xmlns="http://xmlns.oracle.com/weblogic/weblogic-application";;>
   ...
 <session-descriptor>
     <persistent-store-type>memory</persistent-store-type>
     <sharing-enabled>true</sharing-enabled>
     ...
 </session-descriptor>
...
</weblogic-application>

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 Clusters for Oracle WebLogic Server.

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

Attributes Shared by Different Types of Session Persistence

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

  • cache-size—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 1028. To turn off caching, set this to 0. See "cache-size" in session-descriptor.

    Note:

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

  • invalidation-interval-secs—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. Use this element to tune WebLogic Server for best performance on high traffic sites. See "invalidation-interval-secs" in session-descriptor.

    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.

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 persistent-store-type parameter in the session-descriptor element in the weblogic.xml deployment descriptor file to memory. See session-descriptor.

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:

  • In the deployment descriptor file weblogic.xml, set the persistent-store-type parameter in the session-descriptor element in the weblogic.xml deployment descriptor file to file. See "persistent-store-type" in session-descriptor.

  • Set the directory where WebLogic Server stores the sessions. See "persistent-store-dir" in session-descriptor.

    Note:

    You must create this directory 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 life time 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.

Configuring JDBC-based Persistent Storage

To configure JDBC-based persistent storage for sessions:

  • Set the persistent-store-type parameter in the session-descriptor element in the weblogic.xml deployment descriptor file to jdbc. See session-descriptor.

  • Set a JDBC connection pool to be used for persistence storage with the persistent-store-pool parameter in the session-descriptor element in the weblogic.xml deployment descriptor file. Use the name of a connection pool that is defined in the WebLogic Server Administration Console. See session-descriptor.

  • 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 10-1 Creating wl_servlet_sessions

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.


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.

Example 10-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 jdbc-connection-timeout-secs parameter 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 session-descriptor.

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.

Example 10-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 DB2, use the following SQL statement to create the wl_servlet_sessions table. Modify the SQL statement for use with your DBMS.

Example 10-3 Creating wl_servlet_sessions table with DB2

CREATE TABLE WL_SERVLET_SESSIONS
(
   WL_ID VARCHAR(100) not null,
   WL_CONTEXT_PATH VARCHAR(100) not null,
   WL_IS_NEW SMALLINT,
   WL_CREATE_TIME DECIMAL(16),
   WL_IS_VALID SMALLINT,
   wl_session_values BLOB(10M) NOT LOGGED,
   WL_ACCESS_TIME DECIMAL(16),
   WL_MAX_INACTIVE_INTERVAL INTEGER,
   PRIMARY KEY (WL_ID,WL_CONTEXT_PATH)
);

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

Example 10-4 Creating wl_servlet_sessions table with Sybase

create table WL_SERVLET_SESSIONS (
WL_ID                         varchar(100)                   not null  ,
WL_CONTEXT_PATH               varchar(100)                   not null  ,
WL_IS_NEW                     CHAR(1)                           null  ,
WL_CREATE_TIME                decimal(16,0)                      null  ,
WL_IS_VALID                   CHAR(1)                           null  ,
WL_SESSION_VALUES             image                              null  ,
WL_ACCESS_TIME                decimal(16,0)                      null  ,
WL_MAX_INACTIVE_INTERVAL      int                                null  ,
)
go

alter table WL_SERVLET_SESSIONS
add PRIMARY KEY CLUSTERED (WL_ID, WL_CONTEXT_PATH)
go

Caching and Database Updates for JDBC Session Persistence

WebLogic Server does not write the HTTP session state to disk if the request is read-only, meaning the request does not modify the HTTP session. Only the wl_access_time column is updated in the database, if the session is accessed.

For non read-only requests, the Web application container updates the database for the changes to session state after every HTTP request. This is done so that any server in the cluster can handle requests upon failovers and retrieve the latest session state from the database.

To prevent multiple database queries, WebLogic Server caches recently used sessions. Recently used sessions are not refreshed from the database for every request. The number of sessions in cache is governed by the cache-size parameter in the session-descriptor element of the WebLogic Server-specific deployment descriptor, weblogic.xml. See session-descriptor.

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:

  • Set the persistent-store-type parameter in the session-descriptor element in the weblogic.xml deployment descriptor file to cookie. See session-descriptor.

  • Optionally, set a name for the cookie using the persistent-store-cookie-name element. The default is WLCOOKIE. See session-descriptor.

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 hyperlinks 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 url-rewriting-enabled parameter in the WebLogic-specific deployment descriptor, weblogic.xml, under the session-descriptor element. The default value for this attribute is true. See session-descriptor.

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.

    When a plug-in is used (Apache, NSAPI, ISAPI, HttpClusterServlet, or HttpProxyServlet) and URL rewriting is used at the back-end server using response.sendRedirect(url) or response.encodeRedirectURL(url), then the PathTrim and PathPrepend parameters will be applied to the URL under the following condition: PathTrim will only be applied to the URL if PathPrepend is null or PathPrepend has been applied.

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

    Note:

    The CISCO Local Director load balancer expects a question mark "?" delimiter for URL rewriting. Because the WebLogic Server URL-rewriting mechanism uses a semicolon ";" as the delimiter, our URL rewriting is incompatible with this load balancer.

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 "id-length" in session-descriptor.

Session Tracking from a Servlet

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.

The following sections discuss various aspects of tracking sessions from an HTTP servlet:

A History of Session Tracking

Before session tracking matured conceptually, developers tried to build state into their pages by stuffing information into hidden fields on a page or embedding user choices into URLs used in links with a long string of appended characters. You can see good examples of this at most search engine sites, many of which still depend on CGI. These sites track user choices with URL parameter name=value pairs that are appended to the URL, after the reserved HTTP character ?. This practice can result in a very long URL that the CGI script must carefully parse and manage. The problem with this approach is that you cannot pass this information from session to session. Once you lose control over the URL—that is, once the user leaves one of your pages—the user information is lost forever.

Later, Netscape introduced browser cookies, which enable you to store user-related information about the client for each server. However, some browsers still do not fully support cookies, and some users prefer to turn off the cookie option in their browsers. Another factor that should be considered is that most browsers limit the amount of data that can be stored with a cookie.

Unlike the CGI approach, the HTTP servlet specification defines a solution that allows the server to store user details on the server beyond a single session, and protects your code from the complexities of tracking sessions. Your servlets can use an HttpSession object to track a user's input over the span of a single session and to share session details among multiple servlets. Session data can be persisted using a variety of methods available with WebLogic Service.

Tracking a Session with an HttpSession Object

According to the Java Servlet API, which WebLogic Server implements and supports, each servlet can access a server-side session by using its HttpSession object. You can access an HttpSession object in the service() method of the servlet by using the HttpServletRequest object with the variable request variable, as shown:

HttpSession session = request.getSession(true);

An HttpSession object is created if one does not already exist for that client when the request.getSession(true)method is called with the argument true. The session object lives on WebLogic Server for the lifetime of the session, during which the session object accumulates information related to that client. Your servlet adds or removes information from the session object as necessary. A session is associated with a particular client. Each time the client visits your servlet, the same associated HttpSession object is retrieved when the getSession() method is called.

For more details on the methods supported by the HttpSession, refer to the HttpServlet API at http://download.oracle.com/javaee/6/api/javax/servlet/http/HttpSession.html.

In the following example, the service() method counts the number of times a user requests the servlet during a session.

public void service(HttpServletRequest request, 
                    HttpServletResponse, response) 
            throws IOException
{
  // Get the session and the counter param attribute
  HttpSession session = request.getSession (true);
  Integer ival = (Integer) 
                 session.getAttribute("simplesession.counter");
  if (ival == null) // Initialize the counter
    ival = new Integer (1);
  else // Increment the counter
    ival = new Integer (ival.intValue () + 1);
  // Set the new attribute value in the session
  session.setAttribute("simplesession.counter", ival);
  // Output the HTML page
  out.print("<HTML><body>");
  out.print("<center> You have hit this page ");
  out.print(ival + " times!");
  out.print("</body></html>");
}

Lifetime of a Session

A session tracks the selections of a user over a series of pages in a single transaction. A single transaction may consist of several tasks, such as searching for an item, adding it to a shopping cart, and then processing a payment. A session is transient, and its lifetime ends when one of the following occurs:

  • A user leaves your site and the user's browser does not accept cookies.

  • A user quits the browser.

  • The session is timed out due to inactivity.

  • The session is completed and invalidated by the servlet.

  • The user logs out and is invalidated by the servlet.

For more persistent, long-term storage of data, your servlet should write details to a database using JDBC or EJB and associate the client with this data using a long-lived cookie and/or user name and password.

Note:

Although this document states that sessions use cookies and persistence internally, you should not use sessions as a general mechanism for storing data about a user.

How Session Tracking Works

How does WebLogic Server know which session is associated with each client? When an HttpSession is created in a servlet, it is associated with a unique ID. The browser must provide this session ID with its request in order for the server to find the session data again. The server attempts to store this ID by setting a cookie on the client. Once the cookie is set, each time the browser sends a request to the server it includes the cookie containing the ID. The server automatically parses the cookie and supplies the session data when your servlet calls the getSession() method.

If the client does not accept cookies, the only alternative is to encode the ID into the URL links in the pages sent back to the client. For this reason, you should always use the encodeURL() method when you include URLs in your servlet response. WebLogic Server detects whether the browser accepts cookies and does not unnecessarily encode URLs. WebLogic automatically parses the session ID from an encoded URL and retrieves the correct session data when you call the getSession() method. Using the encodeURL() method ensures no disruption to your servlet code, regardless of the procedure used to track sessions. For more information, see Using URL Rewriting Instead of Cookies.

Detecting the Start of a Session

After you obtain a session using the getSession(true) method, you can tell whether the session has just been created by calling the HttpSession.isNew() method. If this method returns true, then the client does not already have a valid session, and at this point it is unaware of the new session. The client does not become aware of the new session until a reply is posted back from the server.

Design your application to accommodate new or existing sessions in a way that suits your business logic. For example, your application might redirect the client's URL to a login/password page if you determine that the session has not yet started, as shown in the following code example:

HttpSession session = request.getSession(true);
if (session.isNew()) {
  response.sendRedirect(welcomeURL);
}

On the login page, provide an option to log in to the system or create a new account. You can also specify a login page in your Web application using the login-config element of the Java EE standard Web application deployment descriptor, web.xml.

Setting and Getting Session Name/Value Attributes

You can store data in an HttpSession object using name=value pairs. Data stored in a session is available through the session. To store data in a session, use these methods from the HttpSession interface:

getAttribute()
getAttributeNames() 
setAttribute() 
removeAttribute()
The following code fragment shows how to get all the existing name=value pairs: 
Enumeration sessionNames = session.getAttributeNames();
String sessionName = null;
Object sessionValue = null;

while (sessionNames.hasMoreElements()) {
  sessionName = (String)sessionNames.nextElement();
  sessionValue = session.getAttribute(sessionName);
  System.out.println("Session name is " + sessionName +
                     ", value is " + sessionValue);
}

To add or overwrite a named attribute, use the setAttribute() method. To remove a named attribute altogether, use the removeAttribute() method.

Note:

You can add any Java descendant of Object as a session attribute and associate it with a name. However, if you are using session persistence, your attribute value objects must implement java.io.Serializable.

Logging Out and Ending a Session

If your application deals with sensitive information, consider offering the ability to log out of the session. This is a common feature when using shopping carts and Internet email accounts. When the same browser returns to the service, the user must log back in to the system.

Using session.invalidate() for a Single Web Application

User authentication information is stored both in the users's session data and in the context of a server or virtual host that is targeted by a Web application. Using 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.

Do not reference an invalidated session after calling session.invalidate(). If you do, an IllegalStateException is thrown. The next time a user visits your servlet from the same browser, the session data will be missing, and a new session will be created when you call the getSession(true) method. At that time you can send the user to the login page again.

Implementing Single Sign-On for Multiple Applications

If the server or virtual host is targeted by many Web applications, another means is required to log out a user from all Web applications. Because the servlet specification does not provide an API for logging out a user from all Web applications, the following methods are provided.

  • weblogic.servlet.security.ServletAuthentication.logout()—Removes the authentication data from the users's session data, which logs out a user but allows the session to remain alive.

  • weblogic.servlet.security.ServletAuthentication.invalidateAll()—Invalidates all the sessions and removes the authentication data for the current user. The cookie is also invalidated.

  • weblogic.servlet.security.ServletAuthentication.killCookie()—Invalidates the current cookie by setting the cookie so that it expires immediately when the response is sent to the browser. This method depends on a successful response reaching the user's browser. The session remains alive until it times out.

Exempting a Web Application for Single Sign-on

If you want to exempt a Web application from participating in single sign-on, define a different cookie name for the exempted Web application. For more information, see Configuring WebLogic Server Session Cookies.

Configuring Session Tracking

WebLogic Server provides many configurable attributes that determine how WebLogic Server handles session tracking. For details about configuring these session tracking attributes, see session-descriptor.

Using URL Rewriting Instead of Cookies

In some situations, a browser may not accept cookies, which means that session tracking with cookies is not possible. URL rewriting is a workaround to this scenario 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 hyperlinks 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 and finds the appropriate HttpSession. Then you use the getSession() method to access session data.

To enable URL rewriting in WebLogic Server, set the URL-rewriting-enabled parameter to true in the session-descriptor element of the WebLogic Server-specific deployment descriptor, weblogic.xml. See session-descriptor.

To make sure your code correctly handles URLs in order to support URL rewriting, consider the following guidelines:

  • You should 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 if the URL needs to be rewritten and, if necessary, rewrites the URL by including the session ID in the URL.

  • Encode URLs that send redirects, as well as URLs that are returned as a response to WebLogic Server. For example:

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

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

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

Note:

The CISCO Local Director load balancer expects a question mark "?" delimiter for URL rewriting. Because the WebLogic Server URL-rewriting mechanism uses a semicolon ";" as the delimiter, our URL rewriting is incompatible with this load balancer.

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 impose a 128-character limit (including parameters) on the length of a URL, which limits the amount of data that can be transmitted using URL rewriting. To allow more space for parameters, you can limit the size of the session ID that is randomly generated by WebLogic Server by specifying the number of bytes with the id-length parameter in the session-descriptor element of the WebLogic Server-specific deployment descriptor, weblogic.xml. See session-descriptor.

The minimum value is 8 bytes; the default value is 52 bytes; the maximum value is Integer.MAX_VALUE.

Making Sessions Persistent

You can set up WebLogic Server to record session data in a persistent store. If you are using session persistence, you can expect the following characteristics:

  • Good failover, because sessions are saved when servers fail.

  • Better load balancing, because any server can handle requests for any number of sessions, and use caching to optimize performance. For more information, see the cache-size property, at Configuring Session Persistence.

  • Sessions can be shared across clustered WebLogic Servers. Note that session persistence is no longer a requirement in a WebLogic Cluster. Instead, you can use in-memory replication of state. For more information, see Using Clusters for Oracle WebLogic Server.

  • For customers who want the highest in servlet session persistence, JDBC-based persistence is the best choice. For customers who want to sacrifice some amount of session persistence in favor of drastically better performance, in-memory replication is the appropriate choice. JDBC-based persistence is noticeably slower than in-memory replication. In some cases, in-memory replication has outperformed JDBC-based persistence for servlet sessions by a factor of eight.

  • You can put any kind of Java object into a session, but for file, JDBC, and in-memory replication, only objects that are java.io.Serializable can be stored in a session. For more information, see Configuring Session Persistence.

Scenarios to Avoid When Using Sessions

Do not use session persistence for storing long-term data between sessions. In other words, do not rely on a session still being active when a client returns to a site at some later date. Instead, your application should record long-term or important information in a database.

Sessions are not a convenience wrapper around cookies. Do not attempt to store long-term or limited-term client data in a session. Instead, your application should create and set its own cookies on the browser. Examples include an auto-login feature that allows a cookie to live for a long period, or an auto-logout feature that allows a cookie to expire after a short period of time. Here, you should not attempt to use HTTP sessions. Instead, you should write your own application-specific logic.

Use Serializable Attribute Values

When you use persistent sessions, all attribute value objects that you add to the session must implement java.io.Serializable.

If you add your own serializable classes to a persistent session, make sure that each instance variable of your class is also serializable. Otherwise, you can declare it as transient, and WebLogic Server does not attempt to save that variable to persistent storage. One common example of an instance variable that must be made transient is the HttpSession object. (See the notes on using serialized objects in sessions in the section Making Sessions Persistent.)

The HttpServletRequest, ServletContext, and HttpSession attributes will be serialized when a WebLogic Server instance detects a change in the Web application classloader. The classloader changes when a Web application is redeployed, when there is a dynamic change in a servlet, or when there is a cross Web application forward or include.

To avoid having the attribute serialized, during a dynamic change in a servlet, turn off servlet-reload-check-secs in weblogic.xml. There is no way to avoid serialization of attributes for cross Web application dispatch or redeployment. See servlet-reload-check-secs.

Configuring Session Persistence

For details about setting up persistent sessions, see Configuring Session Persistence.

Configuring a Maximum Limit on In-memory Servlet Sessions

Without the ability to configure in-memory servlet session use, as new sessions are continually created, the server eventually throws out of memory. To protect against this, WebLogic Server provides a configurable bound on the number of sessions created. When this number is exceeded, the weblogic.servlet.SessionCreationException occurs for each attempt to create a new session. This feature applies to both replicated and non-replicated in-memory sessions.

To configure bound in-memory servlet session use, you set the limitation in the max-in-memory-sessions element in the weblogic.xml deployment descriptor. See session-descriptor.

Enabling Session Memory Overload Protection

When memory is overloaded, a weblogic.servlet.SessionCreationException (RuntimeException) for any getSession(true) attempts occurs. As the person developing the servlet, you should handle this exception as follows:

  • Return the appropriate error message to the user when the exception occurs, explaining the situation.

  • Map weblogic.servlet.SessionCreationException to an error page in the Java EE standard Web application deployment descriptor, web.xml.

By default, memory overload protection is turned off. You can enable it with a domain-level flag:

weblogic.management.configuration.WebAppContainerMBean.OverloadProtectionEnabled