. 44
( 87 .)


Finally we reviewed the portlet event model and looked at how a two-
phase processing design handles portal and user interaction events prior to
the portlet rendering phase.
In the next chapter we will look at the portlet API in more detail.
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49


Portlet Programming
Model and API

In this chapter you will learn about the portlet Application Programming
Interfaces (APIs) supported in WebSphere Portal. We will discuss in detail
the API that exists for portlet development, starting with the existing API,
which is based on Portal 5.0 and is referred to as the IBM Portlet API. We
will discuss the Java Community Process portlet speci¬cation identi¬ed as
Java Speci¬cation Request (JSR) 168.
JSR 168 is described as follows: “To enable interoperability between
Portlets and Portals, this speci¬cation will de¬ne a set of APIs for Portal
computing addressing the areas of aggregation, personalization, presenta-
tion and security.”
We will review this speci¬cation in context of WebSphere Portal (version
5.02 or later) and compare this API to the IBM Portlet API.

The JSR 168 API
In the previous chapter we discussed portlets and the portal context under
which they operate. Part of that discussion naturally relied on an under-
standing of the portlet API. The discussion in that chapter was based on the
IBM Portlet API. In this chapter we will discuss the API based on JSR 168
and compare it with the IBM Portlet API.
Java Portlet Speci¬cation JSR 168 is a Java Community Process speci¬cation
to provide a standard for interoperability between portlets and portals. The
speci¬cation was approved in October 2003.

WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

260 Chapter 14

Portlet API in WebSphere Portal
As of version 5.0.2, WebSphere Portal provided support for the JSR 168
portlet API. However, at the time of this writing, there are functions and
services provided in the IBM Portlet API that have not been de¬ned in the
JSR 168 speci¬cation. Therefore, the early implementation of JSR 168 API
in WebSphere Portal does not contain all of the portlet functions available
with the IBM Portlet.
As we mentioned in the previous chapter, WebSphere Portal provides
two portlet containers to support the IBM Portlet API and the JSR 168 API.
Portlets from both containers can reside on the same portal page. There is no
difference to the portlet user as to which API is used as the administration
and deployment of the portlets are the same. There are however functional
differences in the API, which will be explored in this chapter.

Portlet API Comparison
In order to show an organized comparison between the two portlet APIs
in total, we will review the API by functional area. The areas of the portlet
API we will consider are:

Portlet deployment descriptors
Portlet processing model
Portlet life cycle and con¬guration objects
Portlet services and objects
Portlet URI addressability
Portlet window

Portlet Deployment Descriptors
In both portlet APIs, there is one portlet class instance for each portlet con-
¬guration in the Web deployment descriptor and one or more portlets are
de¬ned in a portlet application in a WAR ¬le. And in both cases the port-
let deployment descriptor (portlet.xml) de¬nes the portlet application
and portlets, while the Web deployment descriptor (web.xml) de¬nes the
associated Web application.
There are a few main differences with the JSR 168 portlet deployment
descriptor. A change with the JSR 168 API is that a portlet is no longer
a servlet. The portlet deployment descriptor is created in the format of
an XML schema and it does not contain a reference to a corresponding
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

Portlet Programming Model and API 261

servlet ID in the Web descriptor. As with the IBM Portlet API we can asso-
ciate context parameters in the Web descriptor and retrieve them using the
PortletContext getInitParameter() method.
In order to uniquely identify the portlet application, a unique identi¬er
(UID) is added to the <portlet-app/> element. In the case of the IBM
Portlet this was the UID attribute, for the JSR 168 descriptor this is the ID
attribute. The default ID value, if not speci¬ed, is the WAR ¬lename.
Within the portlet element de¬nition the <allows> maximized and min-
imized do not need to be explicitly de¬ned in the JSR 168 descriptor. The
portlet must support the default window states. Custom state however will
need to be de¬ned here. Figure 14-1 shows this element set in the IBM Portlet

Figure 14-1 IBM Portlet API descriptor.
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

262 Chapter 14

Figure 14-2 JSR 168 Portlet descriptor.

The IBM Portlet API allows you to specify localized strings in the portlet
deployment descriptor for the portlet title, the portlet short title, the portlet
description, and the searchable keywords. You can see in Figure 14-2 in
the example deployment descriptor that the concrete portlet is de¬ned to
default to English (en) but includes translated text to support English and
The JSR 168 API provides two mechanisms in the deployment descriptor
to support localization. The ¬rst is the ability to specify localized strings in
the descriptor for administrative value like the portlet display name and
the portlet description. These elements allow you to specify an xml:lang
attribute to allow you to specify multiple element de¬nitions using different
language strings.
You can see in Figure 14-2 the elements de¬ning the description and
display name in both English and German. Also you can see in the example
that the portlet also de¬nes the locales it supports using the <supported-
locale> element.
The second mechanism allows for the localization of strings like the port-
let title, the portlet short title, and the portlet search keywords in a resource
bundle. The resource bundle is speci¬ed in the deployment descriptor us-
ing the <resource-bundle> tag. The resource bundle then de¬nes the
localized strings for these properties. The portlet has access through the
PortletConfig object to the resource bundle at runtime.
The following shows the HelloWorld.properties ¬le for this portlet.

# HelloWorld Resource Bundle
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

Portlet Programming Model and API 263

# English Resource Bundle
javax.portlet.title=Hello World Portlet
javax.portlet.short-title=Hello World

# German Resourse Bundle
javax.portlet.title=Hallo Welt Portlet
javax.portlet.short-title=Hallo Welt

Portlet Content Types
The JSR 168 API allows the portlet container to de¬ne to the portlets the con-
tent types that the container supports. It also allows the portlet deployment
descriptor to specify the content types that the portlet supports. Figure 14-2
shows a portlet descriptor where the supported content type is de¬ned in
the <supports> section.
Portlets must explicitly set the content type of their markup response.
The RenderResponse setContentType() method is used. The con-
tent type speci¬ed must match one of the content types supported by the
portlet, otherwise an IllegalArgumentException is thrown and the
setContentType() method must be called before the response writer is
committed. The getResponseContentTypes() method of the Render-
Response object returns the list of supported content types. The method
will only return content types that the portlet supports as de¬ned in the
deployment descriptor.

Portlet Class De¬nition
The Portlet interface de¬nes the JSR 168 portlet class. Portlet can im-
plement this interface directly or extend GenericPortlet, which imple-
ments Portlet and provides default method implementations.
By comparison, portlet classes using the IBM Portlet API typically extend
AbstractPortlet and may also implement listener interfaces to partici-
pate in event model noti¬cations.

Portlet Processing Model
Both APIs adhere to a two-phase processing model. A key difference in the
JSR model is that the request and response objects are different between the
two phases of processing. With the IBM Portlet API you could set attributes
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

264 Chapter 14

Table 14-1 IBM Portlet API Events and Listeners
ActionEvent ActionListener

MessageEvent MessageListener

WindowListener (depreciated in
WebSphere Portal 5.0)

PortletSettings PortletSettingsAttributeListener

PortletApplication PortletApplicationSettingsAttribute
SettingsAttributeEvent Listener

Render phase life cycle PortletPageListener

Session life cycle PortletSessionListener

Event phase life cycle EventPhaseListener

on the ActionRequest object in the event processing phase and retrieve
them from the RenderRequest object in the rendering phase. Using the
JSR 168 API you cannot do this. Passing user instance objects from the ¬rst
phase to the second needs to be done on the session object. However, you
can set string parameters on the ActionRequest in the event phase and
have them added to the RenderRequest object for the render phase.
Instead of the service() method being invoked as in the IBM Portlet
API, the JSR 168 API de¬nes a render() method. The action
Performed() event listener method is replaced with the process
Action() method. Also, during the action phase, the JSR 168 API allows
portlets to redirect requests to other Web resources, a servlet for example.
The IBM Portlet API provided an event model to signal processing events
such as a user action or a portlet message. As we mentioned previously, the
action event listener method is replaced by a method on the portlet that
gets invoked from the portlet container. The IBM Portlet API supports the
events and associated listeners shown in Table 14-1. The JSR 168 API does
not support events or listeners.

Portlet Modes
The view, edit, and help modes are the same between both APIs and can be
invoked through the corresponding doView(), doEdit(), and doHelp()
methods. The JSR 168 API provides the capability for portlets to de¬ne
custom modes where con¬gure mode can be implemented. Other suggested


. 44
( 87 .)