Exercise 1.2: Conceptual differences between the APIs

Before you begin, you should complete Exercise 1.1: Importing the resources.

In this exercise, you will learn conceptual differences between the two portlet APIs.

Overview

The IBM portlet API was initially developed for WebSphere Portal Version 4. Support for the JSR 168 portlet API was provided beginning with WebSphere Portal version 5.0.2.

The JSR 168 portlet API is a standardized JavaTM portlet specification, developed by a group that was jointly led by IBM and Sun, with input from the major vendors of portal servers. Its purpose is to solve portlet compatibility issues between portal servers from different vendors. The initial specification was approved in October, 2003.

WebSphere Portal supports both APIs. It provides two portal containers: the legacy container for IBM portlet API portlets (hereafter referred to as IBM portlets), and the Standard container for JSR 168 portlet API portlets (hereafter referred to as JSR 168 portlets). Portlets running in different containers can reside on the same portal page.

A portal container provides the run-time environment for portlets. It supports the portlet life cycle, which consists of these three phases:

The request handling phase has these two sub-phases:

Prior to understanding the specific coding differences, you need to understand some basic differences between the two portlet APIs.

Note that you do not have to work directly with the source code for the portlet deployment descriptors as discussed below. The portlet deployment descriptor editor provides a graphical user interface for portlet.xml, and updates the source code for you.

Class instances and data using the IBM portlet API

When a portlet is initially loaded, it is initialized with parameters from the Web deployment descriptor (web.xml). The parameters are defined on the <init-param> element of the <servlet> element. These parameters can be retrieved using the getInitParameter() method of the PortletConfig object. The resulting portlet is an abstract portlet.

Before a portlet is used, parameters from the portlet deployment descriptor (portlet.xml) are loaded into a PortletApplicationSettings object or a PortletSettings object. These parameters are set on the <context-param> element of the <concrete-portlet-app> element and on the <config-param> element of the <concrete-portlet> element.

Parameters on the <concrete-portlet-app> element apply to all portlets in the portlet application; they can be retrieved with the PortletSettings.getApplicationSettings() method. The getApplicationSettings() method returns a PortletApplicationSettings object and PortletApplicationSettings.getAttribute() is used to retrieve the individual parameters. Parameters on the <concrete-portlet> element apply to specific portlets; they can be retrieved with the PortletSettings.getAttribute() method.

The combination of an abstract portlet plus the data from a PortletSettings object is called a concrete portlet.

When a portlet is placed on a portal page, a PortletData object is created. The combination of a concrete portlet plus a PortletData object is called a concrete portlet instance. The PortletData objects manage the persistent data for the concrete portlet instances. The values are retrieved using the PortletRequest.getData() and PortletData.getAttribute() methods, and stored using the PortletData.setAttribute() and PortletData.store() methods. The data is scoped to a user or a group, depending on the scope of the portal page.

The combination of a concrete portlet instance plus a PortletSession object is called a user portlet instance.

The following illustration shows the objects just discussed.
Logical representation of portlet classes and data in the IBM portlet API

Class instances and data using the JSR 168 portlet API

Using the JSR 168 portlet API, initial parameters are defined in portlet.xml with the <portlet-preferences> element. The <init-param> element in web.xml for the IBM portlet API is equivalent to the <init-param> element in portlet.xml for the JSR 168 portlet API.

These initial parameters can be set to read-only, but can be modified at run-time in Config mode. Only an administrator can change read-only initialization parameters. When modified during run-time, a validator class can be called. The name of the validator class is also set on the <portlet-preferences> element. The PortletPreferences object makes these parameters available to the portlet via the RenderRequest.getPreferences(), PortletPreferences.getValue(), and PortletPreferences.getValues() methods. The <portlet-preferences> element is equivalent to the <config-param> element plus a PortletData object in the IBM portlet API.

The combination of a PortletPreferences object and a portlet is known as a portlet entity. A portlet window is defined as the combination of the portlet mode (edit, view), the portlet window state (normal, maximized, minimized), and the render parameters. A portal page can contain more than one portlet window for a given portlet, each associated with a specific mode, state and set of render parameters.

The following illustration shows the objects just discussed.
Logical representation of portlet classes and data in the JSR 168 API

Portlet life cycle

Both portlet APIs use a life cycle that consists of an initialization phase, a request processing phase, and a destruction phase. The request processing phase is divided into sub-phases: action processing and content rendering. Details of the request processing phase are discussed in Request processing. The specific methods called in each phase are listed below.

IBM portlet API life cycle methods

init(PortletConfig)
The init() method is called when the portlet is placed in service. The PortletConfig parameter provides access to the PortletContext object.
initConcrete(PortletSettings)
The initConcrete() method is used to initialize the concrete portlet with the PortletSettings object.
service(PortletRequest, PortletResponse)
The service() method is called when the portlet is required to render its content. The service method is called many times during the life cycle of a portlet. Service calls methods such as doView() and doEdit(), depending on the window state of the portlet. The service method is usually not overridden in the implementing portlet class.
destroyConcrete(PortletSettings)
The destroyConcrete() method is called when the concrete portlet is taken out of service.
destroy(PortletConfig)
The destroy() method is called when the portlet is taken out of service, providing a place for cleanup of resources.

JSR 168 portlet API life cycle methods

init(PortletConfig)
The init() method is called when the portlet is placed in service. The PortletConfig parameter provides access to the PortletContext object.
render(RenderRequest, RenderResponse)
The render() method is called when the portlet is required to render its content. It calls methods such as doEdit() and doView(), depending on the window state of the portlet. The render method is usually not overridden in the implementing portlet class.
processAction(ActionRequest, ActionResponse)
The processAction() method requires ActionRequest and ActionResponse objects as parameters.
destroy()
The destroy() method is called when the portlet is taken out of service, providing a place for cleanup of resources.

Request processing

Both portlet APIs use two-phase request processing. Actions (or events) are processed first, then the rendering phase is invoked. In the IBM portlet API, the action phase is invoked via the actionPerformed() method, and the rendering phase is invoked by the service() method. In the JSR 168 portlet API, the phases are invoked via the processAction() and render() methods.

A big difference between the two APIs is that the JSR portlet API uses different request and response objects in the action and render phases, while the IBM portlet API uses the same objects in the two phases. Using the IBM portlet API, you can set attributes on the request and response objects during event processing, and retrieve the values during the rendering phase. Using the JSR portlet API, attribute values can be passed using the session object or using render parameters.

Another difference is that the IBM portlet API's actionPerformed() method uses its ActionEvent parameter to gain access to the PortletRequest object. The JSR 168 portlet API's processAction() method has the parameters ActionRequest and ActionResponse, which implement the PortletRequest and PortletResponse interfaces.

Now you are ready to begin Exercise 1.3: Comparing JavaTM class differences.

Terms of use | Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.