. 43
( 87 .)


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

Extending Portal Functionality: Portlets 253

Figure 13-8 portlet.xml”portlet settings.PortletData.

A PortletSession is very similar to an HttpSession. Its function is to
provide a facility to maintain transient user application data across multiple
HTTP requests. A PortletSession object is created for all user portlets on
authenticated pages when the user logs into the portal. Portlet user instances
are differentiated from portlet instances (or other portlet user instances) by
their PortletSession objects.
The PortletSession object is accessible from the request object using
the getPortletSession() method.
A portlet placed on an unauthenticated page on the other hand will not
have a PortletSession object assigned automatically. The portlet write
can ask to have one created using the getPortletSession() or get-
PortletSession(true) method. Portlets should verify that they have
a valid session object by testing the results of the getPortletSession
(false) method.
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

254 Chapter 13

Figure 13-9 NavigatorService.properties.

A portal con¬guration change can be made to request a Portlet
Session object also by default for portlets on unauthenticated pages. Keep
in mind that the session object will be available when the portlet is executed
but will be transient. That is, a new PortletSession object will be created
by the portlet container for each request to that portlet. Change the pub-
lic.session property to true in the NavigatorService.properties
(see Figure 13-9) ¬le to have the PortletSession object created for unau-
thenticated page portlets. The NavigatorService.properties ¬le can
be found in <wp_root>/shared/app/config/services.
As with HttpSession objects, good programming practice is to be care-
ful and limit how much data is put on the session. Application memory
requirements and database overhead if the session data is persisted can
grow quickly and limit performance and scalability.
This is especially true in a portal environment as there are as many “appli-
cation sessions” active as there are portlets on pages that the user is visiting
during the current logged-on session.

Portlet Objects
There are a number of portlet objects that are de¬ned by the portlet API. The
following section describes the PortletRequest, PortletResponse,
PortletContext, PortletLog, and User objects. These represent the
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

Extending Portal Functionality: Portlets 255

key portlet objects in addition to the objects already de¬ned in the section
on portlet con¬guration (PortletConfig, PortletSettings, Portlet
ApplicationSettings, PortletData, and PortletSession).

The PortletRequest object provides the portlet access to HTTP request
speci¬c information and to portlet con¬guration information as well. The
PortletRequest object is passed to the portlet as a parameter on the
service method.
Through the PortletRequest the portlet can get and set attributes, can
get parameters sent in the URI query string, and get the user agent infor-
mation to determine client support information such as the markup name
and the MIME types. As we have mentioned before, through the Portlet
Request object, we can also retrieve the PortletData, Portlet
Session, and PortletSettings objects. We can also get the current
mode and state of the portlet.

Like the PortletRequest object the PortletResponse object is passed
to the portlet as a parameter on the service method call. Typically, the
PortletResponse object is used to return output to the client using a
PrintWriter. The PortletResponse is also used to generate encoded
URI strings that can be used to reference the portlet, and associated portlet
actions, in context of the portal.

The PortletContext provides the portlet access to some context informa-
tion in the portlet container including providing access to portlet services.
Application scoped resources, attributes, and initialization parameters are
all available through the PortletContext. Portlet-to-portlet messaging
is also possible through the PortletContext as well as access to portlet
services and the portlet log.

The PortletLog object is available from the PortletContext using the
getPortletLog() method. It provides common trace logging services for
portlet writers. Messages can be informational, warning, or errors. Logging
at various levels can be switched on/off by changing a properties ¬le setting
or, dynamically, through portal administrative function.
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

256 Chapter 13

One of the important bene¬ts to applications running in a portal is the
availability of common services and function. Some of these we have al-
ready mentioned, such as the common user interaction model and common
UI facades through portal managed themes and skins. Another common
service is user authentication and authorization (access control). Both of
these services are provided by the underlying portal services, and portlet
developers can focus on the application requirements and use the portlet
API to determine user information.
The User object represents the pro¬le of the user logged in to portal. The
User object can be retrieved from the PortletRequest object using the
getUser() method. While the PortletSession getUser() method is
available as well, it has been deprecated in the current version of Portal.

Portlet Event Model
Unlike a servlet, which does all request processing in the service()
method, a portlet has two processing phases. The ¬rst phase is the event
phase and the second is the rendering phase.
Various types of events can be handled in the event phase. These can be
action events, message events, portlet settings attributes events, and portlet
application settings attributes events.
The Event interface is the basis for all events that are managed within
the legacy portlet container. Portlets that implement the appropriate listener
interface for these events will get noti¬ed during the event processing phase.
The portlet container is responsible to signal all event listeners before any
rendering phase processing begins. Events can be generated by other event
listeners during their event phase processing. In this case the portlet con-
tainer will deliver that, and any subsequent events, before event processing
completes. In addition, no events will be delivered after the event phase
The listener interface de¬nes the methods that will get invoked during
event processing. For example, action events will get handled by the ac-
tionPerformed() method and message events by the message
Received() method.
The rendering phase is sometimes referred to as the content generation
phase. The portlet service() method is invoked to handle this request.
Portlets typically inherit from PortletAdapter and the service()
method implemented in that class performs the following:
public class Sample extends PortletAdapter {

public void service(PortletRequest request, PortletResponse response)
throws PortletException, IOException {
if(request.getMode() == Portlet.Mode.VIEW)
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

Extending Portal Functionality: Portlets 257

doView(request, response);
if(request.getMode() == Portlet.Mode.EDIT)
doEdit(request, response);
if(request.getMode() == Portlet.Mode.HELP)
doHelp(request, response);
if(request.getMode() == Portlet.Mode.CONFIGURE)
doConfigure(request, response);


So, since our portlet typically would want to make a distinction in process-
ing depending on the mode the portlet is currently in, typically the portlet
writer will simply override doView(), doEdit(), doConfigure(), and
doHelp() instead of service().
All portlet state changes are handled during event processing. The
service() method is called after the portlets event handling listener is
invoked for portlets that are direct targets of the event. In addition, the
service() method of a portlet is called when the portal page is refreshed.
So, when a user is interacting with a portlet on a page, that portlet could have
processing in both phases. Other portlets on the same page will have their
service() method called for the rendering phase to generate response
markup fragments for the entire page to be generated.
Typically, the portlet class is used as the event listener class as well. The
event handling method has access to the PortletRequest object and
can add attributes to the PortletRequest to be referenced during the
rendering phase, as the PortletRequest object is the same between both
processing phases.

Action Events
Action events are generated when an HTTP request is received by the port-
let container for which an action has previously been associated with that
clickable link on the page. So, when we create content for a portlet and want
to generate HTML with a clickable link we will use the portlet API to asso-
ciate with the URI for that link, an encoding that can later be interpreted as
a speci¬c action event. We will look at this API more closely in the following

Message Events
Message events are generated when a portlet using the portlet API to
send a message to another portlet where both portlets are within the same
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

258 Chapter 13

portlet application and are on the same portal page. Also, a Default-
PortletMessage can be sent to portlets not in the same portlet applica-
tion to all portlets on the portal page. The portlet receiving the message
event must implement the MessageListener interface. This API allows
for portlet-to-portlet communication and the capability to create coopera-
tive portlets. We will see in later chapters a more advanced framework for
generating cooperative portlets.

Portlet Settings Attributes Events
Portlets that implement the PortletSettingsAttributesListener
interface will be noti¬ed when changes to the attribute list on the portlet set-
tings of a concrete portlet occur. Depending on the change that
occurred, the method attributeAdded(), attributeRemoved(), or
attributeReplaced() will get invoked.

Portlet Application Settings Attributes Events
Portlets that implement the PortletApplicationSettingsAttri-
butesListener interface will be noti¬ed when changes to the attribute
list on the settings of a concrete portlet application occur. Depending on
the change that occurred, the method attributeAdded(), attribute
Removed(), or attributeReplaced()will get invoked.

In this chapter we discussed what a portlet is. We discussed portlets in
context of a high-level view of the portal architecture and how portlets are
managed by the portlet container. We started the discussion about portlet
container and portlet interface differences between the legacy portlet API
and the API provided that implements JSR 168.
We learned about portlet rendering and page aggregation and how
portlets provide markup fragments that the portlet container uses to gen-
erate a complete markup page response. We looked at how portlets are
de¬ned within a J2EE servlet deployment and how a portlet deployment
descriptor maps portlet-speci¬c information to a servlet de¬nition in a Web
application deployment descriptor that is needed for portlet deployment.
We looked that the portlet life cycle and saw how portlets take on different
contexts as con¬guration objects are associated with the portlet.


. 43
( 87 .)