JSR-286 development tutorial: Understanding the PortletSession

The key to state management in web based applications is the session object. Here we explore the Portlet 2.0 API's PortletSession, how it is used, and how it relates to the HttpSession of the Servlet and JSP specification.

The following tutorial introducing the PortletSession, written by  Sal Pece, is one in a series of Portal and Portlet 2.0 development tutorials appearing on TheServerSide. These tutorials, CBTs and tips are designed to help any Java  professional who is looking to acquire JSR-286 development skills to become quickly adept at both intermediate and advanced portlet programming topics, empowering the developer to quickly create portlet-based software that can be effectively deployed to any of the standards-based portal servers on the market today, including Liferay, WebSphere, eXo and the JBoss Portal.

If the user is going to be good enough to provide information to us through HTML forms and HTTP headers, the least we could do is keep track of that information for at least the duration of the user's visit to our site. To provide such a stateful experience for portal users, portlet developers rely upon the services of the PortletSession. The good news about the PortletSession? It is easy to use, helps maintain a stateful experience for the user, overcoming the stateless nature of the HTTP protocol, and if you have any history with Servlet and JSP development, you'll be delighted to know that the PortletSession is remarkably similar to the HttpSession from the Servlet world.

This tutorial will look at the PortletSession, how the PortletSession works, and will even discuss some of the drawbacks and alternatives to using the PortletSession in your code

Canada and the http protocol have one thing in common: they are both stateless. Canada has ten provinces and three relatively empty territories, but no states. Of course, they have been eyeing Michigan for a while.

Managing State with the PortletSession Object 

When a user visits our portal site, we often need to keep track of information the user has provided. Information stored in the PortletRequest or PortletResponse objects are purged as soon as a response is sent back to the client. This creates a problem if we want to recall that information on subsequent request-response cycles.

To store user specific information for the duration of the user's interaction with the server, the Portlet API provides a special object called the PortletSession. Any useful piece of information, in the form of Java objects, can be stuffed inside a user's session object. That information is then available to our portlet instance on all subsequent request-response cycles. The PortletSession is effectively tied to the user for which it is created.

The Transient Nature of the PortletSession

One thing to note about the PortletSession is that it is transient – it's the hobo of the Portlet API. If the user leaves our site, doesn't interact with the site for a predetermined amount of time (usually thirty minutes), or even if the user closes their browser, information stored in the PortletSession is lost, or at least, the ethereal session containing that information will not longer be tied to the user.  Information stored in the PortletSession is not stored persistently. The job of the PortletSession is to simply create a stateful experience for users while interacting with our site.

Taking Advantage of the PortletSession Object

Figure 5-1 shows a simple portlet that keeps track of the number of times the doView method of a portlet is called. The view count variable is stored in the PortletSession, under the key named timesvisited. Every time the doView method of the portlet is called, the view count increases by one. The view count is then displayed back to the user.

Notice how the SimpleSessionPortlet requires some session-data management. When the portlet is first viewed, there will be no data stored in the session regarding the view count. On the first iteration,  a timesvisited key, with an assigned value of 1, is placed into the PortletSession. On subsequent iterations, when the timesvisited key is present in the session, the associated value is extracted, incremented, and then stored back in the PortletSession.

Figure 5-1 Taking Advantage of the PortletSession

package com.mcnz.portlet;
import java.io.*;
import javax.portlet.*;
public class SimpleSessionPortlet extends GenericPortlet {
 protected void doView(RenderRequest request, RenderResponse response)   
                           throws PortletException, IOException {

  PrintWriter out = response.getWriter();
   // grab the PortletSession from the PortletRequest 
  PortletSession session = request.getPortletSession();

  //pull the visitCount out of the session.
  String visitCount =
  if (visitCount == null) {
   //if this is the first time viewing the portlet, set the value to 1
    session.setAttribute("timesvisited", "" + 1);
    out.print("Welcome to our little portlet!");
    out.print("Click refresh, minimize or maximize!!!");
  else {
   // if this portlet has been visited before, increase the count 
    int newCount = Integer.parseInt(visitCount) + 1;
    session.setAttribute("timesvisited", "" + newCount);
    out.print("Number of times visiting this portlet: ");

Here is how the application looks when it is deployed to a portal server such as WebSphere Portal Server, Liferay or eXo:


State management is one of the biggest challenges of any modern day enterprise application that is deployed and delivered over the web. Since its inception, the Servlet and JSP API has relied heavily on the HttpSession object to maintain a stateful conversation between the client and the server. In a similar fashion, the PortletSession piggybacks on the HttpSession of the Servlet and JSP API to provide a similar set of functionalities that allows server side management of data that pertains to the current interaction any individual user is currently having with the portal server.

Next Steps

New to Git and distributed version control? Here are some Git examples and Jenkins-Git integration tutorials designed to help you master the popular source code versioning tool.

Dig Deeper on Integrated development environments

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.