<<

. 42
( 87 .)



>>

tinction on the user™s access rights not just at the portlet level but for the
portlet and for modes within the portlet. We want to allow all users access to
the portlet™s view, edit, and help modes but give only portal administrators
the ability to execute the con¬gure mode of the portlet.
Keep in mind that it is up to the writer of the portlet to determine what, if
any, con¬guration and customization processing needs to be accomplished,
and implement it accordingly. Portal provides the infrastructure to associate
access control permissions with portlet modes, to provide the Portlet API
with mode support, and provides access to portlet settings, portlet appli-
cation con¬guration parameters, and servlet initialization parameters. It
provides access to a persistence store for user-speci¬c application data. It
is up to the portlet writer to determine which values should be shared and
which should be user-speci¬c.


Portlet Applications and Portlets
Portals are de¬ned within the context of a portlet application. A portlet
application may contain one or more portlets. Portlet applications are used
for administrative management of a set of portlets.
Portlets are de¬ned in the portlet deployment descriptor, an XML ¬le that
gets consumed by portal during the process of installing or updating a portal
application. As we said before a portlet is deployed in a Web application so
we also have a Web deployment descriptor for our portlet application. The
Web application deployment descriptor de¬nes one or more servlets and
each of those servlet de¬nitions is tied to a portlet de¬nition in the portlet
descriptor (via a mapping of the servlet id to the portlet href).
The portlet deployment descriptor de¬nes portlet properties such as port-
let display name, caching preferences, supported portlet states, modes, and
markups, and portlet con¬guration parameters.
Portlet application properties are minimal and include the display name
and an application unique identi¬er. A portlet application will have one
or more concrete portlet applications de¬ned in the portal deployment
descriptor.
A concrete portlet application is differentiated by a set of Context Parame-
ters that are shared across its concrete portlets. One or more concrete portlets
are de¬ned in the portlet deployment descriptor. They are mapped to the
abstract (nonconcrete) portlets by the href attribute of the concrete portlet
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




Extending Portal Functionality: Portlets 247


mapping to the id attribute of the abstract portlet. Concrete portlets are
differentiated by a set of additional properties that include the de¬ned lan-
guage locales (and default), the portlet-language-speci¬c portlet title, short
title, description and keyword properties, and de¬ned setting parameters.
Although the portlets and servlets have many similarities, there are some
key differences. Portlets cannot issue a redirect or forward a request. Since
portlets only contribute to the response markup output stream rather than
write the entire response, they have some limitations in what markup they
can generate. In general, portlets should generate only markup that could
be contained within a table. A portal provides dynamic administration of
portlets, and dynamic updates can be made to change the portlet settings,
to copy portlets, and to delete portlets. Portlet applications are installed into
a running portal.
Figure 13-4 shows the relationship of portlet application to Web applica-
tion and the attributes associated with portlet applications, concrete portlet
applications, abstract portlets, and concrete portlets.
While administrative tasks can target portlet application and concrete
portlet applications, only concrete portlets are put on pages to be used by
the portal user.
The portlet class that implements the required portlet API and provides
the function of the portlet is de¬ned as the servlet class in Web applica-
tion deployment descriptor. Portlet application and portlet con¬guration
information is linked from the Web descriptor and the implementation of
the portlet is invoked from the Web descriptor servlet class.




Figure 13-4 Portlet application.
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




248 Chapter 13


To deploy a portlet to a portal there is a bit more work to do. We don™t
simply add a portlet to the portal. We de¬ne an abstract portlet in a portlet
application and a concrete portlet in a concrete portlet application in the
portlet deployment descriptor. We create a Web application and a servlet
de¬nition in a Web deployment descriptor and map the servlet to the ab-
stract portlet. We package the deployment descriptors with the portlet class
¬les and any associate resource ¬les into a WAR ¬le. Then we use the ad-
ministrative tools in portal to deploy the WAR into portal. Under the covers,
portal generates an Enterprise Application for the Web application and de-
ploys the Enterprise Application to the Portal Application Server.


Portlet Life Cycle
Portlets have a life cycle similar to servlets. The portlet container is respon-
sible to manage the portlet life cycle. As we would expect, portlets move
through the life cycle by virtue of being deployed, being placed on a user™s
page, or having that page invoked by the user. They also progress as a result
of con¬guration data that is associated with them.
As we see in Figure 13-5, an abstract portlet is loaded when the por-
tal is initialized. Legacy portlets extend the Portlet API implementation
class org.apache.jetspeed.portlets.AbstractPortlet, which in
turn extends org.apache.jetspeed.portlets.PortletAdapter.
PortletAdapter provides the default implementations for the methods
referenced in Figure 13-5.
Prior to being ¬rst used the settings de¬ned for the portlet are held
in a PortletSettings object. With the association of the Portlet
Settings object the portlet is referred to as a concrete portlet. We can
use the administrative function of portal to create many copies of the ab-
stract portlet, each with its own portlet settings and each referred to as a
concrete portlet. Portlet settings are read and write properties. They can
be dynamically modi¬ed either through portlet function using the portlet
API or through administrative services. Modi¬cation of these settings is
required to be performed while the portlet is in con¬gure mode if using the
portlet API. Portlet settings are persisted by portal. They are initialized with
the concrete portlet setting parameters de¬ned in the portal deployment
descriptor. We can then have multiple concrete portlets de¬ned with their
own setting information allowing a single portlet deployment to provide
tailored behavior.
Like many representations of the portlet in the life cycle described here,
there is no ConcretePortlet object. Rather the concrete portlet is a repre-
sentation of the abstract portlet when associated with a speci¬c Portlet-
Settings object.
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




Extending Portal Functionality: Portlets 249




Figure 13-5 Portlet life cycle.


When the portlet is placed on a portal page, a PortletData object is
created for the concrete portlet. This PortletData object is associated with
the concrete portlet to generate a reference to a concrete portlet instance.
There can be multiple concrete portlet instances for each concrete portlet.
The PortletData object is available for portlet writers to persist appli-
cation data. PortletData must be written when the portlet is in Edit mode
but can be read from all modes. PortletData can be scoped to either a
user or a group of users depending on the scope of the page on which the
portlet was added. If an administrator puts a portlet on a shared page then
the users that have view access to that page will share the portlet data. Users
that have edit access to the page will get user-speci¬c portlet data. Likewise,
if users put a portlet on their own page, they will have private access to the
portlet data.
Finally, when a user accesses a portal page, user portlet instances for the
portlets on that page are created. User portlet instances are the association
of the user PortetSession object with the concrete portlet instance. Of
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




250 Chapter 13


course, there can be many user portlet instances for each concrete portlet
instance. A PortletSession object is created for each user portlet when
the user logs in to the portal. As we have discussed, for a new portlet
deployment the deployment descriptors contain the information by which
one or more abstract portlets and one or more concrete portlets are de¬ned.
When the portlet application is installed (deployed) to portal, the abstract
portlet(s) are created, and when associated with their portlet settings their
concrete portlet representations are also available. In this case, the portlet™s
init() and initConcrete() methods are invoked. Similarly, when the
administrative function is used to copy a portlet a new PortletSettings
object is created and associated with the new concrete portlet representation.
This is performed by the initConcrete() method.


Portlet Con¬guration Objects
In the previous section on portlet life cycle we saw that changes in a portlet
representation was marked by the association of a con¬guration object. They
were PortletSettings, PortletData, and PortletSession. In addi-
tion, there was con¬guration de¬ned in the portlet deployment descriptors
that get encapsulated in other con¬guration objects including Portlet
ApplicationSettings and PortletConfig. In this section we will
take a closer look at these objects.

PortletCon¬g
In the Web deployment descriptor we can de¬ne a number of servlet context
parameters. These con¬guration parameters provide the initial con¬gura-
tion for the abstract portlet and are available to all of its concrete portlets.
This information is read-only and cannot be modi¬ed by the portlet. These
parameters are encapsulated in a PortletConfig object and that object is
passed to the abstract portlet on the init() method. Parameters are acces-
sible using the getInitParameters() method on the PortletConfig
object.
Figure 13-6 shows an example of a Web deployment descriptor with a
con¬guration parameter named persist_to_DB de¬ned.

PortletApplicationSettings
In the portlet deployment descriptor for each concrete portlet application
we can de¬ne context parameters. Figure 13-7 shows an example portlet
deployment descriptor with a portlet application setting parameter high-
lighted. There can be multiple parameters de¬ned although only one is
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




Extending Portal Functionality: Portlets 251




Figure 13-6 web.xml”context parameter.


shown here. When deployed these context parameters are encapsulated
in a PortletApplicationsSettings object and are available to the
portlet. This information is shared with all concrete portlets included in
the portlet application. The PortletApplicationsSettings object can
be read by the portlet in any mode but can only be updated in con¬gure
mode. It can be retrieved from the PortletSettings object using the get
ApplicationSettings() method.


PortletSettings
Also in the portlet deployment descriptor, for each concrete portlet we can
de¬ne a number of con¬guration parameters. Figure 13-8 shows the ex-
ample portlet deployment descriptor with a portlet setting highlighted.
There can be multiple parameters de¬ned although only one is shown
here. When deployed these con¬guration parameters are encapsulated in a
PortletSettings object and are available to the portlet. This information
is shared with all concrete portlet instances. The PortletSettings object
can be read by the portlet in any mode but can only be updated in con¬g-
ure mode. It can be retrieved from the PortletRequest object using the
getPortletSettings() method.
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-13 WY009-BenNatan-v1.cls May 11, 2004 14:49




252 Chapter 13




Figure 13-7 portlet.xml”portlet application settings.


The PortletData object manages persistent data for a concrete portlet
instance. As we discussed in the section on portlet life cycle, when a portlet
is placed on a portal page a PortletData object is created for the concrete
portlet and then a concrete portlet instance is generated. The PortletData
instance associated with the portlet can be retrieved using the getData()
method of the PortletRequest object. Data is stored as name and value
pairs, with the name represented as a string and the value as a serializ-
able object. The store() method is used to persist the values set using
the setData() method and as we discussed this can only be performed
while the portlet is in edit mode.
PortletData can be scoped to either a user or a group of users, de-
pending on the scope of the page on which the portlet was added. If an
administrator puts a portlet on a shared page then the users that have view
access to that page will share the portlet data. Users that have edit access to
the page will get user-speci¬c portlet data. Likewise, if users put a portlet
on their own page, they will have private access to the portlet data.
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH

<<

. 42
( 87 .)



>>