Comparing JSR 168 to the IBM portlet API

 

---

Overview

Between JSR 168 and WebSphere Portal, 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 receives the client request for a page, calls the portlets for the page and calls the container to provide the output for each portlet. The portal server aggregates the output from all portlets on the page to provide a complete portal page in the response to the client. The following topics describe the differences between the APIs used by portlets running in the portlet container.

1. Relationship to servlet API
2. Comparing common portlet API concepts
3. Comparing elements of the API
4. Concepts unique to JSR 168
5. Concepts unique to the IBM portlet API
6. Limitations

 

Relationship to servlet API

The IBM portlet API extends the servlet API and many of the main interfaces (request, response, session). JSR 168 API does not extend the servlet API, but shares many of the same characteristics. JSR 168 takes advantage of much of the functionality provided by the servlet specification, such as deployment, classloading, web applications, web application lifecycle management, session management and request dispatching.

JSR 168 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.

				Portlet
				1   PortletSettings
		concrete portlet				concrete portlet
				2  PortletData
	concrete portlet instance		concrete portlet instance		concrete portlet instance		concrete portlet instance
			3  PortletSession + Portlet.Mode + PortletWindow.State
user portlet instance		user portlet instance				user portlet instance		user portlet instance

Logical representation of portlets in the IBM portlet API

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, which is a concrete portlet instance parameterized with the session, a mode and window state ( 3 ).

 

Logical representation of portlets in JSR 168

In WebSphere Portal, JSR 168 portlets, like IBM portlets, can also be configured on two levels, by an administrator and by individual users. However, JSR 168 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 JSR 168. JSR 168 adds render parameters as a new 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 ).

				Portlet
				1   PortletPreferences (administrator)
		portlet definition				portlet definition
				2  PortletPreferences (user)
	portlet entity		portlet entity		portlet entity		portlet entity
			3  session + mode + state + render parameters
portlet window		portlet window				portlet window		portlet window

Logical representation of portlets in JSR 168

 

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.

• JSR 168 compliant 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 JSR 168 compliant portlets.

IBM Portlet API	JSR 168	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	JSR 168 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(), and doHelp(). In JSR 168, this method is invoked when the portal receives a render request.
none	processAction()	Used by the portlet to received parameters, update state, and 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	JSR 168 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

JSR 168

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	JSR 168
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. JSR 168 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 does not support any custom modes other than config mode.

 

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, the portlet's output is not displayed at all.

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

IBM Portlet API	JSR 168
Solo	Supported only as a custom window state. WebSphere Portal does not support solo state for JSR 168 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 does not support custom window states for JSR 168.

 

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

JSR 168

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 JSR 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	JSR 168
PortletResponse.encodeNamespace(name)	RenderResponse.getNamespace(name)

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	JSR 168
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	JSR 168
<portletAPI:init/> - provides access to the PortletRequest, PortletResponse, and PortletConfig objects.	<portlet:defineObjects/> - provides access to the RenderRequest, RenderResponse, and PortletConfig objects
<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. See Portlet URLs for more information on render and action URLs.
<portletAPI:encodeNamespace/>	<portlet:namespace/>
Other tags provided by the IBM portlet API tag library	Use JSTL tags

 

URLs to portlet resources

In WebSphere Portal, 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	JSR 168
Use the encodeURL() method of the response and specify the path to the resource, for example: <%= portletResponse.encodeURL("/images/photo01.jpg") %>	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, as in: <%= 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	JSR 168
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	JSR 168
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 JSR 168

 

• Render parameters

  These are 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. In the action, the portlet can set new render parameters to represent the new navigational state after the action is completed. The developer can use render URLs (see 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, JSR 168 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 JSR 168, 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.

   

• 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 does not support any vendor-specific request or response properties.

   

• Web application session scope

  Both, the JSR 168 API and the IBM Portlet API, have the concept of a session that is private to the portlet entity. In this scope the portlet can store information that is needed across user requests.

  JSR 168 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 JSR 168 reuses the HttpSession, it also allows reusing all the session and attribute listeners that the servlet 2.3 specification defines. JSR 168 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). JSR 168 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, JSR 168 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 JSR 168, an action invalidates all cached markup.

   

 

Limitations

The JSR 168 portlet container for WebSphere Portal has the following limitations:

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. See PLT.7.1.2 Portlet URL security in the specification for more information.

Programmatic security

The isUserInRole() method of the portlet request is not supported and always returns false. Any <security-role-ref/> elements in the portlet deployment descriptor are ignored.

The getUserPrincipal() method of the portlet request always returns null if appserver 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.

User information

The following attributes are supported in the portlet container for WebSphere Portal. The second column shows the corresponding attribute name in Member Manager (wmmAttributeName).

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

All other user attributes not listed here are not supported. See PLT.17 User Information in the specification for more information.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.