Introduction

With the emergence of an increasing number of enterprise portals, a variety of APIs for portal components, which are called portlets, has been created by different vendors. Having multiple, incompatible interfaces creates problems for application providers, portal customers, and portal server vendors. The Java Portlet Specification, JSR 168, which is being defined by the Java Community Process (JCP), provides a standard for interoperability between portlets and portals. In time, it will help to overcome these problems.

The goal of this document is to compare the JSR 168 and the WebSphere Portal V5.0 Portlet API and to show some examples.

Important: The IBM Portlet API will still be supported in the next WebSphere Portal releases to give customers and partners a convenient migration window.

Back to top

Introducing JSR 168

The Java Standardization Request 168 (JSR 168) defines a portlet specification, including a contract between the portlet container and the portlet. JSR 168 is defined by the Java Community Process (JCP). The JSR 168 was co-led by IBM and Sun and had a large Expert Group that helped to create the final version which is now available. This Expert Group consisted of Apache Software Foundation, Art Technology Group Inc.(ATG), BEA, Boeing, Borland, Citrix Systems, Fujitsu, Hitachi, IBM, Novell, Oracle, SAP, SAS Institute, Sun, Sybase, Tibco, Vignette. More details about this JSR can be found at http://jcp.org/en/jsr/detail?id=168.

Important: The information provided in this analysis is provided without warranty of any kind. The analysis is intended to be an informational tool only for the reader.

JSR 168 definitions

This section provides basic JSR 168 definitions so that you can understand how JSR 168 fits into the overall portal architecture.

Portal and portlet container

A portal is a Web application which typically provides personalization, single sign-on, content aggregation from different sources, and hosts the presentation layer of different backend systems.

The main task of a portal is to aggregate different applications into one page with a common look and feel for the portal user. A portal may also have sophisticated personalization features which provide customized content to users. Portal pages may have different sets of portlets to create content for different users.

Figure 1 depicts the basic architecture of portals, such as a portal that is served by WebSphere Portal. A client request is processed by the portal Web application, which retrieves the portlets on the current page for the current user. The portal Web application then calls the portlet container for each portlet to retrieve its content through the Container Invoker API. The portlet container calls the portlets through the Portlet API. The Container Provider Service Provider Interface (SPI) enables the portlet container to retrieve information from the portal.

The portlet container runs the portlets, provides them with the required runtime environment, and manages their lifecycle. It provides persistent storage for portlet preferences which enables the portlet to produce customized output for different users.

Portal page and portlets

Figure 2 depicts the basic portal page components. The portal page represents a complete markup document and aggregates several portlet windows; that is, it combines different application user interfaces into one unified presentation. The portal page lets the user authenticate to the portal through the login dialog to access a personalized portal view. Most portal pages include some navigation mechanism to enable the user to navigate to other portal pages.

A portlet window consists of:

• Title bar, with the title of the portlet
• Decorations, including buttons to change the window state of the portlet (such as maximize or minimize the portlet) and buttons to change the mode of a portlet (such as show help or edit the predefined portlet settings)
• Content produced by the portlet (also called a markup fragment).

Figure 3 shows such a portlet window on different browsers. As you can see, the markup fragment produced by the portlet is not restricted to HTML, but can be any markup.

Portlet lifecycle

The basic portlet lifecycle is to:

1. Initialize, using the init class to initialize the portlet and put it into service.
2. Handle requests, processing different kinds of actions and rendering content.
3. Complete, using the destroy class to take the portlet out of

The portlet receives requests based on the user interaction with the portlet or portal page. The request processing is divided into two phases:

1. Action processing

   If a user clicks on a link on the portlet, an action is triggered.The action processing must be finished before any rendering of the portlets on the page is started. In the action phase the portlet can change the state of the portlet.

2. Rendering content

   In the render phase, the portlet produces its markup to be sent back to the client. Rendering should not change any state. It allows a page re-fresh without modifying the portlet state. Rendering of all portlets on a page can be performed in parallel.

Figure 4 depicts the request flow from the client to the portlets, and shows the action and render phases in more detail. In this example, portlet A has received an action. After the action is processed, the render methods of all portlets on the page (A, B, C) are called.

Portlet modes

Portlets perform different tasks and create content according to their current function. A portlet mode indicates the function a portlet is performing, at a point in time. A portlet mode specifies the kind of task the portlet should perform and what content it should generate. When invoking a portlet, the portlet container provides the mode for the current request to the portlet. Portlets can programmatically change their portlet mode while processing an action request.

JSR 168 defines three categories of portlet modes.

1. Modes which are required to support (same semantic as above)

   Edit

   Display one or more views that let the user personalize portlet settings.Help

   Help

   Display help views.

   View

   Display the portlet output.

2. Optional custom modes

   About

   Display the portlets purpose, origin, version, and other information.

   Config

   Display one or more configuration views that let administrators configure portlet settings which are valid for all users.

   Edit_defaults

   Set the default values for the modifiable preferences that are typically changed in the EDIT screen.

   Preview

   Render output without the need to have back-end connections or user specific data available.

   Print

   Display a view which is suitable for printing.

3. Portal vendor specific modes
   

   These modes are only available in a specific vendor portal.

Window states

A window state is an indicator of the amount of portal page space assigned to the content generated by a portlet. The portlet container provides the current window state to the portlet, and the portlet uses the window state to decide how much information it should render. However, portlets can also programmatically change their window state while processing an action request.

JSR 168 defines the following window states:

Normal

The portlet shares the space with other portlets and should take this into account when producing its output.

Maximized

A window has more real estate to render its output than in normal window state.

Minimized

The portlet should only render minimal or no output.

In addition to these window states, JSR 168 allows the portal to define custom window states.

Data model

JSR 168 defines different mechanisms for the portlet to access transient and persistent data.

The portlet can set and get transient data in the following scopes:

The portlet can access persistent data with these scopes:

Portlet application

All resources, portlets, and deployment descriptors are packaged together into one Web application archive (WAR) file. There are two deployment descriptors:

• All Web application resources that are not portlets must be specified in the web.xml deployment descriptor.
• All portlets and portlet related settings must be specified in the portlet.xmldeployment descriptor.

Back to top

Comparing JSR 168 and the IBM Portlet API

This section gives a high level comparison between the new JSR 168 Portlet API and the IBM Portlet API. First, it covers the concepts that are similar; then, it explains some of the differences between the two.

Similarities

The following concepts are very similar in JSR 168 and the IBM Portlet API.

Differences

The JSR 168 and the IBM Portlet API differ in the following ways.

Exclusive to JSR 168

These items are only available in the JSR 168.

Exclusive to the IBM Portlet API

The following concepts are only available in the IBM Portlet API.

Back to top

Example portlets

This section shows a HelloWorld portlet implemented in each of the two APIs. The key differences are highlighted in the second portlet.

The two example portlets implement the same functions:

• Use JSPs for rendering the output
• Customize the portlet output, based on user-specific data
• Handle actions to allow the user to change these

This example shows a hello world portlet which uses personalization. It addresses the user by name, and it allows the user into edit mode to set a new user name. In the action method (called actionPerformed in the IBM Portlet API and processAction in JSR 168), the portlet persistently stores the new user name which the user enters.

First look at the portlet implemented using the IBM Portlet API.

public class HelloWorld extends AbstractPortlet implements ActionListener
{
€¦
  public void doView (PortletRequest request, PortletResponse response)
   throws PortletException, IOException
    {
   //Get the user's name to display from persistent storage
   PortletData portletData = request.getData();
   String stringToDisplay=(String)portletData.getAttribute("userName");

   if (stringToDisplay == null) {
       stringToDisplay = defaultString;    // set default string
   }

   // Add the display string to the portlet request to make it 
   // accessible by the view JSP
   request.setAttribute("userName", stringToDisplay);

   // Get a context for the current session for invoking the JSP
   PortletContext context = getPortletConfig().getContext();
   context.include(viewJSP, request, response);
    }

    public void doEdit(PortletRequest portletRequest, 
        PortletResponse portletResponse )
      throws PortletException, IOException
    {
   // Create the cancel return URI for the edit page
   PortletURI cancelURI = portletResponse.createReturnURI();
   // Preserve the Cancel URI in the request to make it 
   // accessible by the edit JSP
   portletRequest.setAttribute("cancelURI", cancelURI.toString());

   // Create the save URI for the edit page
   PortletURI saveURI = portletResponse.createReturnURI();
   // For the "Save" button the return URI must include the "Save" action
   //    so the Action Listener for this portlet will be invoked       
   SimpleActionHelper.
   addSimplePortletAction(getPortletConfig().getContext(), saveURI, "save");

   // Preserve the Save URI in the request to make it accessible by 
   // the edit JSP
   portletRequest.setAttribute("saveURI", saveURI.toString());

   //Get the user's name to display from persistent storage
   String stringToDisplay = (String) 
        portletRequest.getData().getAttribute("userName");
   if (stringToDisplay == null) {
       stringToDisplay = defaultString;    // none found, set default string
   }

   // Add the display string to the request to make it accessible by the 
   // edit JSP as an inital value of the input field on the edit form
   portletRequest.setAttribute("userName", stringToDisplay);

   // Get a context for the current session for invoking the JSP
   PortletContext context = getPortletConfig().getContext();
   context.include(editJSP, portletRequest, portletResponse);
    }
    
public void actionPerformed(ActionEvent event) {
    String action = 
    SimpleActionHelper.getActionString(getPortletConfig().getContext(),
            event);
    HelloWorld helloPortlet = (HelloWorld)event.getPortlet();
    PortletLog log = helloPortlet.getPortletLog();

    // If this is a save action, then see if the user specified a name
    if ( action!=null ) {
      if ( action.equals("save") ) {
       PortletRequest request = event.getRequest();
       PortletData portData = request.getData();
       String userName = request.getParameter("userName");
       try {
       // Save the name specified by the user
         if ( userName != null ) {
         portData.setAttribute("userName", userName);
         portData.store();
      }
      } catch ( AccessDeniedException ade ) {
      } catch ( IOException ioe ) {
       log.error( "
					Couldn't write the user date to 
persistence because an I/O Error occurred.
				" );
      }
     }
    }
  }
}     

Now, look at the same portlet that has been modified to use JSR 168. The changed text is marked in bold.

public class HelloWorld extends GenericPortlet
{
€¦
  public void doView (RenderRequest request, RenderResponse response)
   throws PortletException, IOException
   {
   //Get the user's name to display from persistent storage
   PortletPreferences portletData = request.getPreferences();
  String stringToDisplay = (String) portletData.getValue("userName",defaultString);

   // Add the display string to the portlet request to make it 
   // accessible by the view JSP
   request.setAttribute("userName", stringToDisplay);

   // Get a context for the current session for invoking the JSP
   PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(viewJSP);      
   rd.include(request, response);

    }
    public void doEdit(RenderRequest portletRequest, 
        RenderResponse portletResponse )
      throws PortletException, IOException
    {
   // Create the cancel URI for the edit page
   PortletURL cancelURI = portletResponse.createActionURL();

   // Preserve the Cancel URI in the request to make it 
   // accessible by the edit JSP
   portletRequest.setAttribute("cancelURI", cancelURI.toString());

   // Create the save URI for the edit page
   PortletURL saveURI = portletResponse.createActionURL();

   // For the "Save" button the return URI must include the "Save" action
   // so the Action Listener for this portlet will be invoked
   saveURI.setParameter("action", "save");

   // Preserve the Save URI in the request to make it accessible by 
   // the edit JSP
   portletRequest.setAttribute("saveURI", saveURI.toString());

   //Get the user's name to display from persistent storage
   String stringToDisplay = portletRequest.getPreferences().getValue("userName", 
                             defaultString);

   // Add the display string to the request to make it accessible by the edit JSP
   // as an inital value of the input field on the edit form
   portletRequest.setAttribute("userName", stringToDisplay);

       // Get a context for the current session for invoking the JSP
   PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(editJSP);
   rd.include(portletRequest, portletResponse);
    }

  public void processAction(ActionRequest request, ActionResponse response) 
    throws PortletException, IOException 
  {
    String action = request.getParameter("action");

  // If this is a save action, then see if the user specified a name
  if ( action!=null ) {
      if ( action.equals("save") ) {
   PortletPreferences portData = request.getPreferences();
   String userName = request.getParameter("userName");
   // Save the name specified by the user
   if ( userName != null ) {
     portData.setAttribute("userName", userName);
     portData.store();
   }
  }  

The major differences to the IBM Portlet API version of the portlet are:

1. Request dispatcher usage

   The request dispatcher usage differs slightly between JSR 168 and the IBM Portlet API. JSR 168 uses the same mechanism to get a request dispatcher from context with the path as parameter as the servlet API.

2. Persistent portlet data

   JSR 168 persistent data, PortletPreferences, have an API similar to the JDK 1.4 Preferences and allows specifying a default value for the get methods. The code to check for a null return value and explicitly set a default value are no longer necessary . JSR 168 only allows String and String arrays as values of preferences; arbitrary objects are allowed by the IBM Portlet API.

3. Action handling

   The action handling in JSR 168 is simplified and does not need specific action objects to be created. Creating an action URL automatically triggers a call to the processAction method.

Back to top

Conclusion

With the definition of JSR 168, there is finally a standard portlet API which allows programming portlets independent of portal vendors and lets you run the same portlet unchanged on different portals.

The concepts of the JSR 168 are closely aligned with the IBM Portlet API. When compared to the IBM Portlet API, the functionality of JSR 168 is restricted, because it is the first version of the portlet specification. Developers familiar with the IBM Portlet API should not have difficulty using the JSR 168 API quickly.

Resources

• Java Portlet Specification JSR 168
  
  
• Java Community Process
  
  
• Web Services for Remote Portlets Specification
  
  
• Portlet API Javadoc for WebSphere Portal 5.0
  
  

About the author

Stefan Hepper is a software architect on the WebSphere Portal team at the IBM Silicon Valley Lab in the U.S. He is responsible for rendering WCM content in portal and the convergence of WCM and portal. Previously, he was leading the Java Portlet standards JSR 286 and 168. He has conducted lectures at international conferences, published papers, filed patents, and is a co-author of the book Pervasive Computing (Addison-Wesley 2001).

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Introducing JSR 168
• Comparing JSR 168 and the IBM Portlet API
• Example portlets
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers