. 45
( 87 .)


custom modes include about, preview, print, and edit defaults.
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

Portlet Programming Model and API 265

JSP Invocation and Tag Libraries
To invoke a JSP from the portlet render phase, the IBM Portlet API provided
an include() method on the PortletContext object. The JSR 168 API
provides a PortletRequestDispatcher include() method. We will
de¬ne the PortletRequestDispatcher object later in this chapter. The
following code example shows the invocation of a JSP using the JSR 168 API.
public void doView(RenderRequest request, RenderResponse response)
throws PortletException, IOException {

PortletContext context = getPortletConfig().getPortletContext();
String jspFileName = "/jsp/html/main_view.jsp";

In the JSP, the portlet tag library provides a <portletAPI:init/>
tag that will initialize local variables to reference the PortletRequest,
PortletResponse, and PortletConfig objects. Using the tag library
with JSR 168 API the <portlet:defineObjects/> tag initializes vari-
ables for RenderRequest, RenderResponse, and PortletConfig ob-
Other taglib differences for creating portlet URI references and to encode
namespace references are <portletAPI:createURI/> and <portlet
API:encodeNamespace/> in IBM Portlet API and <portlet:action
URL/> and <portlet:renderURL/> and <portlet:namespace/> in
the JSR 168 API.

Render Parameters
Render parameters allow a portlet to store its navigational state. The
setRenderParameter() and setRenderParameters() methods of
the ActionResponse object allows portlets to set render parameters
during an action request. The parameters will then be used for all render
requests until the next action occurs.
The portlet should be written to store any information that is needed to
successfully redisplay and use those parameters in the render phase. When
the portlet encounters a new action, the render parameters are set again.

Portlet Life Cycle and Con¬guration Objects
In the IBM Portal API the PortletSettings object encapsulates the port-
let con¬guration setting initially de¬ned in the portlet deployment descrip-
tor. It is through a PortletSettings object that the abstract portlet was
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

266 Chapter 14

Table 14-2 JSR 168 Portlet
Portlet Portlet class
container loaded and
starts the instantiated

Portlet Prior to ¬rst Portlet is
init() Portlet-
portlet access method initialized

Portlet User or Portlet
Administrator window
places the
portlet on a

con¬gured as a concrete portlet. There could be multiple concrete portlets
for each abstract portlet. Similarly, an association of a PortletData object
with a concrete portlet de¬nes a concrete portlet instance.
When users edit the settings in a portlet according to their preferences,
the settings are persisted using the PortletData object. There can be
many PortletData objects associated with the same concrete portlet. Each
PortletData object along with the concrete portlet comprises a concrete
portlet instance.
The JSR 168 API does not de¬ne a concrete portlet or a concrete portlet
application. Portlets are de¬ned by a PortletPreferences object that
encapsulates parameters in the portlet deployment descriptor. These pa-
rameters can be identi¬ed as read-only and in that case will be analogous
to the IBM Portlet API PortletSettings object in that they can be mod-
i¬ed only when the portlet is in con¬gure mode.
Also since there are no concrete portlets, there are no life cycle methods
such as initConcrete() or destroyConcrete() in the JSR 168 API.
Table 14-2 shows this portion of the JSR 168 portlet life cycle.
The PortletConfig object in the IBM Portlet API provides access to the
initialization parameters de¬ned in the Web deployment descriptor. In the
JSR 168 API, the PortletConfig object provides access to the initialization
parameters in the portlet deployment descriptor.

Portlet Session
The JSR 168 API de¬nes two session scopes, APPLICATION_SCOPE and
PORTLET_SCOPE. Using APPLICATION SCOPE allows the sharing of
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

Portlet Programming Model and API 267

information between portlets. Any object that is set to the Portlet
Session object using APPLICATION SCOPE can be retrieved by any other
portlet that is part of the same portlet application and that handles a request
that is part of the same session. This sharing is among all components of
the Web application so that you can share data between portlets or between
a portlet and a servlet.
The code example below shows the JSR 168 API to set an attribute in the
portlet session using APPLICATION SCOPE.
PortletSession portletSession = portletRequest.getPortletSession(true);
MyAppBean myAppBean = new MyAppBean(portletRequest);
portletSession.setAttribute("app_bean", myAppBean,

Portal Context
JSR 168 API supports a PortalContext that can be retrieved from the
PortletRequest object. The PortalContext provides portal informa-
tion to the portlet. This allows the portal vendor, portal version, and a set
of portal properties to be de¬ned by the portal and available to the portlet.
The portlet can interrogate the portal information in the PortalContext
and adapt accordingly.

Portlet Services and Objects
This section will discuss additional portlet services and portlet object dif-
ferences between the two APIs.

Portal User Pro¬le
In the IBM Portlet API the user pro¬le information is accessed in the form of
the User object, retrieved from the PortletRequest object. In an LDAP
con¬guration the User object held attributes that mapped to an LDAP
object, typically the inetOrgPerson LDAP object class.
In the JSR 168 API the user pro¬le information (such as name, address,
and userid) is stored in a map in the request and can be accessed through
the Platform for Privacy Preferences (P3P) keys. In the JSR 168 API the
deployment descriptor can de¬ne the user pro¬le information that is to
be made accessible. The recommendation from the JSR 168 speci¬cation
is to use a list of standard P3P attributes but the portlet is not limited to
that de¬nition. The portal will map the requested user pro¬le attributes
to the supported pro¬le attributes. The portlet can then determine which
pro¬le attributes are available by retrieving the map of attributes using the
getAttribute() method of the request object for the attribute named
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

268 Chapter 14

Portlet Caching
The two APIs use different mechanisms to implement portlet caching. The
IBM Portlet API uses an invalidation-based caching mechanism where the
portlet can explicitly invalidate the portlet cache using the invalidate-
Cache() method on the PortletRequest object.
In addition, with the IBM Portlet API the portal queries a portlet to de-
termine if the cache is still valid. The portlet deployment descriptor sets
a cache time value for the portlet application. The value determines the
length of time the cache is valid. The portal queries the portlet using the
getLastModified() method to determine the time that the cache was
last modi¬ed. By overriding this method the portlet can manage the portlet
In Figure 14-1 you saw the cache value speci¬cations in the portlet de-
ployment descriptor for the portlet application. For this example, this entry
looks like the following: The expires value of 0 indicates that the cache always
expires. The shared value of “No” indicates that the portlet cache should not
be shared between portlet instances. A value of ’1 for expires indicates that
the cache never expires and any other positive number indicate the number
of seconds that the cache is to be valid.
The following xml is the cache de¬nition from the portlet deployment

Caching is somewhat different in the JSR 168 as the portlet can attach an
expiration time to the portlet de¬nition. The JSR 168 API de¬nes
an expiration-based cache mechanism. As you saw in Figure 14-2 the
<expiration-cache> timer value is set in the portlet deployment de-
scriptor. It can be dynamically changed by the portlet using the set
Attribute() method of the RenderResponse object referencing the
EXPIRATION_CACHE attribute name.
The following xml shows the expiration cache timer value from the portlet
deployment descriptor.

N O T E Sharing the cache entry across users is only possible in the IBM Portlet
API. Dynamic fragment caching is not implemented for JSR 168 portlets in
WebSphere Portal V5.0.2. Placing JSR 168 portlets on a page with other portlets
that support caching results in incorrect page output. If you use dynamic fragment
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49

Portlet Programming Model and API 269

cache, make sure that there are no JSR 168 portlets on pages where portlets are

Property Broker
The property broker provided with WebSphere Portal and the IBM Portlet
API is used to allow the dynamic integration of portlets. Portlets can be de-
veloped and deployed independently and then by using the property broker
service, portlets can register for and receive noti¬cation of property changes.
Cooperative portlets declare, publish, and share data (properties) using
the property broker, not with a speci¬c portlet or portlets. Portlets that
need to respond based on changed property values will associate actions
with properties. This action processing in the portlet does not differentiate
between a user initiated action event or an action that is the result of a
property value change. In this way, portlets can behave in a coordinated
fashion without depending on a close development“time association.
This service is not available with the initial implementation of the JSR 168

Portlet Services
The IBM Portlet API provides a PortletService interface. This interface
allows vendors and developers to make pluggable portlet services available
to portlet developers. PortletService writers follow a few simple steps
to create their service:

1. De¬ne the service (class extends PortletService).
2. Implement the service (class implements
3. Optionally create a new service factory (if not using the prede¬ned
4. Register the service in the PortletServiceRegistryService
.properties ¬le in the <wp_root>/shared/app/config/
services directory.

Portlet developers can use the PortletContext getService()
method to get the PortletService for the class of the given name. Two
portlet services provided with this API are the ContentAccessService
and the CredentialVaultService.
The ContentAccessService allows portlets to access remote systems
or content from remote URLs, including URLs located on the other side of
a proxy server.
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49


. 45
( 87 .)