Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

---

 

Comparing the standard portlet API to the IBM portlet API

 

+

Search Tips   |   Advanced Search

 

1. Introduction
2. Relationship to servlet API
3. Comparing common portlet API concepts
4. Comparing elements of the API
5. Concepts unique to the Java Portlet Specification
6. Concepts unique to the IBM portlet API
7. User attributes for standard portlets
8. Limitations

 

Introduction

Between the Java Portlet Specification and the IBM portlet API, the fundamental concepts of portal servers are the same. The portlet container is the runtime environment for portlets using the portlet API. The portal server...

1. Receives the client request for a page
2. Calls the portlets for the page
3. Calls the container to provide the output for each portlet.
4. Aggregates the output from all portlets on the page

 

Relationship to servlet API

The IBM portlet API extends the servlet API and many of the main interfaces...

• request
• response
• session

The standard portlet API does not extend the servlet API, but takes advantage of much of the functionality provided by the servlet specification, such as...

• deployment
• classloading
• web applications
• web application lifecycle management
• session management
• request dispatching

Standard portlets can call servlets and package them in the same portlet application.

Portlets, servlets and JSPs within the same portlet application share the same classloader, application context and session.

 

Comparing common portlet API concepts

For both portlet APIs, there is one portlet object instance per portlet configuration in the Web deployment descriptor. The APIs differ in how each portlet object is represented in the portal.

Logical representation of portlets in the IBM portlet API

The PortletSettings object ( 1 ) provides the portlet with its unique set of configuration parameters and values. Configuration parameters are initially defined in the portlet deployment descriptor, but can also be added or modified by the portal administrator. There can be many PortletSettings objects, parameterizing the same portlet object according to the Flyweight pattern, provided on a per-request basis. Each PortletSettings object along with the portlet object comprises a concrete portlet.

When users edit the settings in a portlet according to their preferences, the settings are saved to persistence using the PortletData object ( 2 ). There can be many PortletData objects parameterizing the same concrete portlet. Each PortletData object along with the concrete portlet comprises a concrete portlet instance.

When multiple users interact in different browser sessions with the same concrete portlet instance on a portal page, each user sees a particular user portlet instance ( 3 ), which is a concrete portlet instance parameterized with...

• session
• mode
• window state

Logical representation of portlets in the Java Portlet Specification

In WebSphere Portal Express, standard portlets, like IBM portlets, can also be configured on two levels, by an administrator and by individual users. However, the standard portlet API has no concept of a concrete portlet application or concrete portlets. The number of configuration layers is opaque to the programming model; the portlet configuration is contained within a single PortletPreferences object which aggregates these configuration layers.

Preferences can be marked in the portlet.xml as read-only so that they may be customized only by administrators ( 1 ) using configure mode or through the administration portlets. Preferences that are not marked read-only can be modified by users in edit mode ( 2 ).

The parameterized view of a portlet for an individual user interaction is called portlet window in the Java Portlet Specification. The standard portlet API uses render parameters as an alternative way to hold interaction state for a portlet window. A portal page can contain more than one portlet window for a single portlet, each portlet window associated with unique portlet mode, state, and render parameters ( 3 ).

 

Comparing elements of the API

Utility classes

The Portlet interface is the main abstraction for both the Java Portlet Specification and the IBM Portlet API. Portlets for both APIs should extend the corresponding utility classes, which provide default functionality for the portlet.

• Standard portlets should extend the GenericPortlet class.
• IBM portlets should extend the PortletAdapter class.

Life cycle

The following table compares the portlet life cycle between IBM portlets and standard portlets.

IBM Portlet API	Java Portlet Specification	Description
init()	init()	Called after the portlet has been loaded and instantiated. Portlets use this method to perform one-time operations, especially those that might incur performance costs. The portlet can access its configuration, including initialization parameters, within this method.
initConcrete()	none	The Java Portlet Specification does not have a concept of a concrete portlet.
service()	render()	Used to render output to the client. These methods are typically applied using the mode-specific implementations of... doView() doEdit() doHelp() Using the standard portlet API, this method is invoked when the portal receives a render request.
none	processAction()	Used by the portlet to... Receive parameters Update state Perform any other necessary action processing This is not part of the life cycle of the IBM portlet because the IBM portlet must implement an ActionListener for its counterpart, actionPerformed(), to be called. This method is invoked when the portal receives an action request.
destroyConcrete()	none	The Java Portlet Specification does not have a concept of a concrete portlet.
destroy()	destroy()	Called when the portlet is to be removed from service().

Request handling

Similar to servlets, portlets interact with clients using a request/response paradigm implemented by the portlet container. In a typical scenario, a user selects a page and the portlet container sends the request to each portlet on that page to render output in its response. These requests are called render requests. Other requests, however, are launched when the user interacts with one of the portlets on the page, such as clicking a submit button. Such actions generate URLs to the portlet, which might require the portlet to process an action before sending the response. These are called action requests.

In the servlet model, all request handling would be performed in the service() method. Portlets, however, use a two phase processing that is split between an event phase and a render phase. If the portlet receives an action request, then the event phase is started in which the portlet's action processing method is called. The result of this action could invoke actions for other portlets on the page. After actions have been complete for all portlets on the page, each portlet's rendering method is called. The event phase is guaranteed to complete before the start of the render phase.

The following table describes the differences between the IBM Portlet API and the Java Portlet Specification for handling requests.

IBM Portlet API

Java Portlet Specification

The portlet must implement an ActionListener to participate in the event phase. The actionPerformed() method is invoked to handle action requests. Request and session attributes can be set in the action and retrieved from the subsequent render phase. During the render phase, the service() method is called. Methods for both phases take the same PortletRequest and PortletResponse objects as arguments. There is no distinction in the API between action request and response objects and render request and response objects.

The processAction() method is invoked to handle action requests. The main difference is that the action request and response objects are different from render request and response objects. The portlet can set render parameters or session attributes during the action that are available in the render call, but request attributes are not transferred between action and render phase.

For both APIs, if the portlet extends the appropriate utility class, the service() method dispatches the doView(), doEdit() or doHelp() methods, depending on the current portlet mode.

Portlet mode

Modes allow portlets to provide different interfaces depending on the task that is required of them. The following modes are supported by both APIs.

View

View mode is used for displaying portlet content. Utility class invokes doView() method.

Edit

Edit mode is used for personalizing the portlet (portlet data). Utility class invokes doEdit() method.

Help

Help mode is used for displaying help on the portlet Utility class invokes doHelp() method.

The following table describes support for other modes in each API.

IBM Portlet API	Java Portlet Specification
Configure mode is used by an administrator for globally configuring the portlet (portlet settings). Changes affect all occurrences of the portlet on all pages. Utility class invokes doConfigure() method.	Config mode supported as a custom mode. In config mode, the administrator can globally update the configuration of a portlet, including portlet's read-only preferences. Changes affect all occurrences of the portlet on all pages. In config mode, the portlet's read-only preferences can be updated by the administrator.
No custom modes.	Allows portlets and portal server implementations to support custom modes. At runtime, portlets use PortalContext.getSupportedPortletModes() to retrieve the modes supported by the portal and adapt accordingly. The Java Portlet Specification also suggests these custom portlet modes: about, config, edit_defaults, preview, and print. Vendors can also define other portlet modes. The current portlet container in WebSphere Portal Express supports config and edit_defaults.

Portlet window states

Window states indicate the amount of space that the portlet consumes on a page. The portlet can query its state to determine the visible size of the content it should render. The following states are supported by both APIs.

Normal

The portlet is provided equivalent space as other portlets on the page or in the same container.

Maximized

No other portlets are displayed, providing maximum space for the portlet's use.

Minimized

Only the portlet's title bar is displayed. The Java Portlet Specification allows the portlet to provided a limited amount of output, but for WebSphere Portal Express, the portlet's output is not displayed at all.

The following table describes support for other states in each API.

IBM Portlet API	Java Portlet Specification
Solo	Supported only as a custom window state. WebSphere Portal Express does not support solo state for standard portlets.
No custom states.	Allows portlets and portal implementations to define custom window states. At deployment time, the portal can map custom portlet window states from the portlet descriptor to its own custom window states, or it can ignore them. At runtime, portlets use PortalContext.getSupportedWindowStates() to retrieve the modes supported by the portal and adapt accordingly. WebSphere Portal Express does not support custom window states for standard portlets.

Portlet URLs

Portlet URLs allow the portlet to create a URL to itself. When the user clicks a link or performs an action that launches the URL, it creates a new request to the portal targeted to the portlet. The following table describes how each API implements this functionality.

IBM Portlet API

Java Portlet Specification

PortletResponse.createURI() creates a URI to the portlet. An action can be set on the PortletURI object, so that the actionPerformed() method of the portlet is called before the service() method.

RenderResponse.createRenderURL() creates an URL that triggers the render() method of the portlet. RenderResponse.createActionURL() creates an URL that triggers the processAction() method of the portlet before the render() method. HTML form processing must be done using an action URL. Render and action parameters are separate for standard portlets; parameters set on an action URL are not available to the render() method unless they are passed explicitly using ActionResponse.setRenderParameter(). See Request handling for details about the action and render method.

Namespace encoding

Portlets must contribute identifiers and names in their portlet output that is unique within the portal page. For example, two portlets could appear on a page, both with an anchor named return. Namespace encoding allows the portlet to ensure these names do not clash by adding the portlet's namespace to the anchor name. The following table shows how namespace encoding is performed in the Java source for each API.

IBM Portlet API	Java Portlet Specification
PortletResponse.encodeNamespace(name)	RenderResponse.getNamespace(name) returns a namespace that is valid for the current user session.

See JSPs for a comparison of how namespace encoding is performed for JSPs.

JSPs

The following table compares how JSPs are invoked from the portlet class for each API.

IBM Portlet API	Java Portlet Specification
PortletContext.include()	PortletRequestDispatcher.include() The request dispatcher serves as a wrapper for a resource at the path indicated by getRequestDispatcher(path).

The following table describes the differences in the tag libraries for each API.

IBM Portlet API	Java Portlet Specification
<portletAPI:init/> PortletRequest PortletResponse PortletConfig	<portlet:defineObjects/> RenderRequest RenderResponse PortletConfig
<portletAPI:createURI/> Creates a URI that points to the portlet. To invoke an action in an IBM portlet, include the <portletAPI:URIAction/> tag and action parameters.	<portlet:renderURL/> creates an URL that will trigger the render() method of the portlet. <portlet:actionURL/> creates an URL that will trigger the processAction() method of the portlet before the render() method.
<portletAPI:encodeNamespace/>	<portlet:namespace/> returns a namespace that is valid for the current user session.
Other tags provided by the IBM portlet API tag library	Use JSTL tags

URLs to portlet resources

In WebSphere Portal Express, resources within a portlet cannot be invoked using relative URLs. For URLs to these resources to work, they must be encoded using the encodeURL() method of the portlet response. Resources include any file in the portlet application that is referenced or invoked from the portlet or one of its JSPs, including:

• images
• applets
• multimedia
• JSPs
• servlets

The following table explains the differences between each API for using the encodeURL() method.

IBM Portlet API	Java Portlet Specification
Use the encodeURL() method of the response and specify the path to the resource. See the example in Figure 1.	Use the encodeURL() method, just as you would with the IBM portlet, except that you also have to add the context path of the portlet from the request. See the example in Figure 1.

Figure 1. Example of using encodeURL() methodJava Portlet Specification

<%= portletResponse.encodeURL("/images/photo01.jpg") %> 

 

IBM Portlet API

<%= 
portletResponse.encodeURL(renderRequest.getContextPath()
 +  "/images/photo01.jpg") 
%> 

Caching

Both APIs provide the means for portlets to cache their output and improve performance and response times. The table below describes the differences in the implementations.

IBM Portlet API	Java Portlet Specification
Expiration timer set in the portlet.xml. The IBM Portlet API supports invalidation-based caching. Can be dynamically changed by the portlet when its getLastModified() method is called.	Expiration timer set in the portlet.xml. Can be dynamically changed by the portlet using the EXPIRATION_CACHE property of the RenderResponse.

Portlet configuration

For both APIs, the PortletConfig object is made available to portlet during initialization.

IBM Portlet API	Java Portlet Specification
Provides the initialization parameters defined in the web.xml. Initialization parameters can be read using the getInitParameter() method of the Portlet interface.	Provides the initialization parameters, which can be defined in the portlet.xml or the web.xml. Initialization parameters can be read using the getInitParameter() method of the PortletConfig interface.

 

Concepts unique to the Java Portlet Specification

• Render parameters

  Parameters attached to the render request that stay the same for every render request until a new action occurs.

  This allows storing navigational state in the render parameters instead of the session. The portlet should put all state information it needs to redisplay itself correctly into render parameters (for example, which screen to render). This facilitates saving bookmarks and provides better support for the use of the browser's back button.

  When the portlet is the target of an action, render parameters are reset to represent the new navigational state.

  The developer can use render URLs (RenderResponse.createRenderURL()) to set render parameters directly without having to go through an action. As render parameters may be bookmarked, portlets should be prepared to handle parameters that are not valid (for example, that could be the result of an outdated bookmark).

  Such parameter values should be handled gracefully and should not lead to exceptions.

  From the JSP, the portlet can set render parameters using the <portlet:renderURL/> tag.

• Portal context

  To allow portlets to adapt to the portal that is calling them, the Java Portlet Specification provides the PortalContext to be retrieved from the request. This portal context provides information such as the portal vendor, version, and specific portal properties. This allows the portlet to use specific vendor extensions when called by the portal of that vendor and fall back to some simpler default behavior when called by other portals.

  As the portal context is attached to the request, it may change from request to request. This can be the case in the remote scenario, where one portlet (WSRP provider) may be called from different portals (WSRP consumers).

• Access to the portal user profile

  In the Java Portlet Specification, a portlet can define in the deployment descriptor which user profile information it wants to access. The specification proposes to use a list of standard P3P attributes, however the portlet is free to request any additional user information that is not covered by this attribute list. At deployment time the portal can map the requested user profile attributes to the supported profile attributes or the portal can ignore the requested attributes.

  At runtime the portlet can use the USER_INFO constant of the PortletRequest to determine which of the requested user profile attributes are available. See User information for a list of attributes supported by WebSphere Portal Express.

• Request and response properties

  The portlet and portlet container can exchange vendor-specific information using request and response properties.

  These properties are available in the action request and response and the render request and response. Properties are propagated for includes, but not between the action and render phase. When including a servlet or JSP, the properties are mapped to headers in the servlet API. WebSphere Portal Express does not support any vendor-specific request or response properties.

• Web application session scope

  The standard portlet API supports the Web application session scope, in which every component of the Web application can share information through the APPLICATION_SCOPE field of the portlet session. This can be used to share transient information between different components of the same Web application, for example, between portlets or between a portlet and a servlet.

• Reuse of the HttpSession listeners

  As the standard portlet API reuses the HttpSession, it also allows reusing all the session and attribute listeners that the servlet 2.3 specification defines. The Java Portlet Specification provides a PortletSessionUtil class for decoding the attributes of the HttpSession, as these are namespaced in the private portlet session case.

• Resource bundles

  Portlets can define a resource bundle in the deployment descriptor that can be accessed at runtime using PortletConfig.getResourceBundle().

  This provides localizations of resources, such as the portlet title, search keywords, or preference names and descriptions. At deployment time, all settings in the portlet descriptor that are intended to be viewed or changed by the administrator (for example, portlet description, init parameters, or display name) can be localized by setting the xml:lang attribute on the associated tag (like the servlet 2.4 deployment descriptor). The Java Portlet Specification also recommends a notation for localizing the preference attribute display names, values, and descriptions.

• Multiple response content types

  For each response, portlets can retrieve a list of supported content types using the PortletRequest.getResponseContentTypes() method. This allows portals to indicate to portlets that they have transcoding capabilities.

  Portlets receive only content types that they have defined in the <supports> section of the deployment descriptor.

  If the portlet declares support for content types using wildcards (for example, "text/*" or "*/*") in the deployment descriptor, the portlet container may also set these content types as response content type. Therefore portlets specifying wildcard content types in the deployment should handle wildcard content types as response content types accordingly.

• Redirect in action

  During the action phase, the standard portlet API enables portlets to redirect requests to other Web resources. This allows portlets to process the request from different resources (for example, an accounting servlet) in response to an action.

• Preference validator

  Portlets can provide a class that validates the set of preference values in the PortletPreferences object. The class is defined in the portlet.xml. The preference validator can incorporate logic to check cross-dependencies between different preference properties.

  The portlet container always calls the validator before storing a preference set to ensure that only consistent preference sets are stored.

 

Concepts unique to the IBM portlet API

• Portlet events

  The IBM Portlet API has the concepts of events.

  This event concept is based on the JetSpeed event model, which is similar to the Java event model. The IBM Portlet API provides the following events:

  • ActionEvent
  • MessageEvent
  • PortletApplicationSettingsAttributeEvent
  • PortletSettingsAttributeEvent
  • WindowEvent

• Additional listeners

  The listener concept of the IBM Portlet API allows the portlet to get notifications not only for events as described in the section above, but also for events related to the session lifecycle, event phase lifecycle or render phase lifecycle. The IBM Portlet API provides the following listeners to implement this functionality:

  • PortletPageListener
  • PortletSessionListener
  • EventPhaseListener

• Portlet menus

  The portlet menu service allows the portlet to contribute content to the portal navigation menu, providing users easier navigation through portal pages.

• Invalidation-based caching

  Portlet can actively invalidate the cache using the invalidate method on the portlet request as result of an action. This allows for more fine-grained cache control as the portlet can determine, as a result of this action, whether to invalidate the cache content for only the current portlet mode and markup or for all of the portlet's modes and markups. In the Java Portlet Specification, an action invalidates all cached markup.

 

User attributes for standard portlets

The following table lists the attributes from the appendix of the Java Portlet Specification, PLT.D User Information Attribute Names, and the corresponding attribute name in Member Manager (wmmAttributeName). The portlet container also supports arbitrary user attributes. To specify arbitrary user attributes, the portlet needs to specify the Member Manager attribute name in the portlet.xml deployment descriptor under the <user-attribute/> element and can obtain the attribute value by inspecting the USER_INFO map in the request.

User attribute name	Member Manager equivalent
user.gender	ibm-gender
user.employer	o
user.department	ou
user.jobtitle	ibm-jobTitle
user.name.prefix	ibm-personalTitle
user.name.given	givenName
user.name.family	sn
user.name.middle	ibm-middleName
user.home-info.telecom.telephone.number	homePhone
user.home-info.online.email	ibm-otherEmail
user.business-info.postal.street	street
user.business-info.postal.stateprov	stateOrProvinceName
user.business-info.postal.postalcode	postalCode
user.business-info.postal.country	countryName
user.business-info.telecom.telephone.number	telephoneNumber
user.business-info.telecom.fax.number	facsimileTelephoneNumber
user.business-info.telecom.mobile.number	mobile
user.business-info.telecom.pager.number	pager
user.business-info.telecom.online.email	ibm-primaryEmail

 

Limitations

The standard portlet container for WebSphere Portal Express has the following limitations:

RenderResponse.setTitle(java.lang.String title)

This method is not supported by WebSphere Portal Express.

Portlet URL security

The setsecure() method of the PortletURL interface is not supported.

The portlet URL will always be the same security level of the current request.

Likewise, the secure attribute of the <portlet:actionURL/> and <portlet:renderURL/> tags is not supported. See PLT.7.1.2 Portlet URL security in the specification for more information.

Programmatic security

Programmatic J2EE authorization using the isUserInRole() method of the portlet request is not fully supported, since any <security-role-ref/> elements in the portlet deployment descriptor are ignored. Role assignments for J2EE roles declared by means of <security-role> elements in the web.xml deployment descriptor can still be verified via the isUserInRole() method.

The getUserPrincipal() method of the portlet request always returns null if application server security is not enabled. The getRemoteUser() method of the portlet request always returns a unique value for each user, even with security disabled, so that it can be used for personalization purposes, such as storing user-specific preferences. Therefore, you can always use the code fragment request.getRemoteUser() != null to check if a user has logged in.

The return value with disabled security might not be a human-readable string and will be different from the value returned when security is enabled.

See PLT.20.3 Programmatic Security in the specification for more information.

Specifying security constraints

The <security-constraint/> element in the portlet deployment descriptor is not supported. See PLT.20.3 Specifying Security Constraints in the specification for more information.

 

Related information

• Migrating from the IBM Portlet API

---