. 41
( 87 .)


(see the document collection parameters as shown in Figure 12-9), and if it
does whether it is prede¬ned or user-de¬ned.
When a categorizer is used, it eases the task of browsing through the doc-
uments, as well as the Advanced Search which allows focusing on speci¬c

Extended Search
The WebSphere Portal Extend ships with the IBM Lotus Extended Search
product. It provides a search engine that is more powerful than the one
integrated into the Portal Server. Extended Search supports a variety of data
sources, ranging from text documents, and document repositories such as
Lotus Notes, to fully blown RDBMS such as DB2 and Oracle.
Extended Search is installed separately from the WebSphere Portal, and
once installed, you are able to de¬ne data sources. For each data source,
Extended Search supports ¬eld mapping to allow common naming for ¬elds
that have different names in different subsystems.
IBM offers a portlet for using Extended Search from within the portal. This
portlet allows the user to query using Web-style querying (using + and ’),
using GQL (Generalized Query Language, which is a language used by
the Extend Search internally), or using native syntax when searching in
databases (for example, SQL query syntax when searching an RDBMS).

In this chapter you learned how to use WebSphere collaboration and search
capabilities within the Portal Server. These capabilities allow you to seam-
lessly integrate existing collaboration tools such as Lotus Notes or Microsoft
Exchange into your portal. In addition, Lotus QuickPlace and Lotus Same-
time, which are shipped with the Portal Extend offering, can be used to
facilitate people awareness, instant messaging, and common workplaces.
This chapter concludes this part of the book, and by now you should be
familiar with the Portal Server basics. In the next part of the book you will
learn how to develop new portlets. New portlets are required whenever
you want to implement functionality that is not available within an exist-
ing portlet.
WY009-12 WY009-BenNatan-v1.cls May 11, 2004 14:49

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

Portlet Development in
WebSphere Portal

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

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


Extending Portal
Functionality: Portlets

In this chapter you will learn about portlets, what they are, how they work,
and how they are managed by WebSphere Portal. We will discuss the por-
tal environment in which the portlets operate and some key portlet objects
and services that portal provides. In addition, we will discuss the portlet
life cycle, relevant aspects of the portal container, page aggregation and the
differences between portlet applications and portlets, abstract and concrete
portlets, and portlet instances. We will conclude the chapter with a discus-
sion about the portlet event model and two-phase portlet processing.

What Is a Portlet?
Portlets are distinct, functional components of a portal. They are imple-
mented in Java and are based on a well-de¬ned portlet API. They are de-
ployed through portal, packaged as a Web application, and are managed by
portal through a portlet container. They process HTTP requests forwarded
through the container and generate dynamic content in response.
From a user™s perspective, portlets are functional entities represented
on a portal page. A portal page typically contains several portlets that are
arranged on the portal page in a grid of rectangles of varying size. Common
examples of portlets are portal applications that show the local weather
forecast, the stock ticker, or a user™s email.
A portlet rendered on a page contains a title bar showing the title of the
portlet, portlet navigation and behavior icons, and the dynamic content
generated by the portlet. The content generated by the portlet is a portion
(fragment) of the total markup that makes up the portal page. All portlets

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

242 Chapter 13

on the page contribute these markup fragments. The portlet navigation and
behavior icons allow the user to minimize or maximize the portlet and to
change portlet modes. We will discuss portlet modes and states in more
detail later in this chapter. In addition to portlet content, the portal page
consists of headers, banners, and a navigation area.
Portlets tend to implement very speci¬c tasks with less page navigation
and less complexity than a typical Web-based application may have. From
a development perspective portlets are very similar to servlets. A servlet is
an application within a Web application server. A portlet is an application
within a portal.
From a deployment perspective portlets are packaged as J2EE WAR ¬les
and deployed into the portal environment using portal administrative util-
ities or administrative portlets.
Portlets bene¬t from functions and services of the portal, which provides
a common user interface (UI) framework, a common user interaction model,
single authentication, and common administration. Developers bene¬t by
gaining access to supporting portal infrastructure for personalization, cus-
tomization, and administrative functions such as security, access control,
UI skins and themes support, and page layout.
Figure 13-1 shows the portal architecture. The portal receives the client
HTTP request for a portlet page. Using the portal user and access control
information the portlets on that page are determined. Each portlet is in-
voked to generate its content fragment in context of the requesting device
type. Those fragments are aggregated in context of the device type and the

Figure 13-1 Portal architecture.
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

Extending Portal Functionality: Portlets 243

theme and skin de¬nitions. The portlet container is the portion of the portal
server that provides the runtime environment for the portlet.
The portal environment supports multiple device types and multiple
markup languages. So, well written portlets that could be invoked from a
variety of device types will respond with the appropriate markup and the
portal will use markup speci¬c aggregators to generate the correct markup
response. These could be HTML, cHTML, or WML.

Portlet Container
Portlets run in the portlet container. The portlet container implements the
portlet API and provides a runtime environment where portlets are in-
stantiated, invoked, and destroyed. Through the API, portlets can access
the logged-in users™ pro¬le, respond to events, communicate with other
portlets, gain access to portal services such as the Credential Vault and
content access service, persist application data, access portlet setting infor-
mation, and access the portlet session object, the portlet request object, and
the portlet response object.
WebSphere Portal provides two portlet containers that support two dif-
ferent portlet APIs. There is support for the javax.portlet API which
is de¬ned by JSR 168 and also support for the proprietary portlet API as
it was de¬ned by WebSphere Portal 4.1. All portlets written prior to Portal
version 5 used only this API.
As shown in Figure 13-2, the portlet containers are components of the
portlet environment. Portal itself runs as a Web application in WebSphere
Application Server. The portal engine in that Web application talks to the
portlet environment through the portlet invoker API and the information
provider SPI. As portlets get invoked by the portal engine, they can commu-
nicate back to requesting portal information through the portlet API. The
implementation of that API may need to gain access to the portal engine
through the information provider SPI.
A portlet request will get directed to the correct portlet container de-
pending on the implemented API of the portlet. The portlet then responds
back with its markup fragment, which is passed back through the portlet
container to the portal engine for aggregation.

Page Aggregation
One of the key differences between a portlet and a servlet is page aggre-
gation. In a servlet the generated markup is solely the responsibility of
the servlet to de¬ne and generate. In a portlet the portal aggregator is
responsible for generating the resulting markup with assistance from the
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

244 Chapter 13

Figure 13-2 Portlet container.

portlets that are on the page to be rendered. Portlets have to be cautious that
any generated markup is going to be in context of the markup generated
by the aggregator and in context of the markup of other portlets on the
page. For example, JavaScript that is generated by a portlet may con¬‚ict
with JavaScript generated by other portlets contributing to the same portal
page. Care should be taken to minimize the risk of name collisions.

Portlet Modes and States
Portlets inherit common UI behavior from the portal. One of these is the
ability for users to select a portlet to be maximized or minimized. When
maximized the portlet takes over the entire portal page. When minimized
the portlet is reduced to just the title bar. This is known as the state of the
portlet. The states that are allowed for a portlet are de¬ned in the portlet
deployment descriptor as a property of the abstract portlet.
The portal also provides infrastructure for common portlet behavior.
Portlets often have requirements for runtime con¬guration and customiza-
tion. Consider a portlet that shows the local weather. Typically we would
expect that a portal administrator would deploy the portlet and provide
portlet con¬guration. In this case, the portlet would probably be con¬gured
to specify the source of the weather information. The portal user would then
need to customize the portlet to specify their location, probably in the form
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

Extending Portal Functionality: Portlets 245

of a zip code or city and state. Then the deployed portlet can successfully
execute for all portal users customized for each user but con¬gured by an
administrator for common settings such as the weather source provider. We
will see later where to store this kind of information so that it is shared in
one case but local to each user in another.
So, given this scenario and given that it is common behavior for many
portlets, we would like the portlet container and portlet API to provide the
common infrastructure to remove some of that work from the portlet devel-
oper and also to make sure that we have a consistent user interaction model.
The ¬rst commonality is the need for the portlet API to implement portlet
modes. The de¬ned modes are view, con¬gure, edit, and help, as shown in
the sample portlet control icons in Figure 13-3. All portlets support view

Figure 13-3 Sample portlet.
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49

246 Chapter 13

mode and this is the initial mode when the portlet is displayed. View mode
is the main mode of the portlet. Con¬gure mode is for shared portlet con¬g-
urations as we discussed. Edit mode is for user-speci¬c portlet customiza-
tions. Help mode is naturally for displaying portlet help.
The other common function requirement here is the need to make a dis-


. 41
( 87 .)