Understanding the IBM Portlet API and JSR 168

WebSphere Portal supports several emerging standards. The Java Community Process (JCP) approved the technical specification for interoperability between portals and portlets in October of 2003. The Java Portlet Specification ( JSR 168) defines a set of APIs so that portlets can be written to be independent of the portal vendor on which they will execute. Continued work on this specification to improve upon the base set of spec requirements is underway.

WebSphere Portal supports two APIs for portlet development: the IBM Portlet API (hereafter called the legacy API) and the industry standard JSR 168. The legacy API is a proprietary API that was available with earlier versions of WebSphere Portal prior to the definition of the industry standard. When JSR 168 was defined, support was provided so that WebSphere Portal now supports both APIs.

We discuss both APIs in this article so that readers familiar with the legacy API can get a quick understanding of the standard API. The focus of ongoing WebSphere Portal and portal development tooling efforts are on the standard API; therefore, the recommendation is to use JSR 168 for all future portal development.

The legacy API extends the servlet API for many of the main interfaces (request, response, session). JSR 168 does not extend the servlet API; instead, it provides similar function by wrapping the base servlet container function. Both APIs restrict certain functions that are available with the servlet API to a subset that makes sense for portlets running in the context of a portal. For example, unlike servlets, portlets can not send errors or redirects as a response to a request. Only the portal can do that, because it controls the overall response page.

JSR 168 portlets can specify a scope for session data, to indicate whether session data should be unique to the portlet or can be shared with any other portlet or servlet deployed within the same WAR. Portlet filters, similar to servlet filters, are available in the legacy API but are not currently supported in JSR 168.

Unlike the legacy API, the JSR 168 permits portlets to write the customization data using the available API in any portlet mode. In the legacy API, updates to user customization data were limited to edit mode and updates to configuration data were limited to config mode. With JSR 168 API a portlet can modify this data in any mode.

JSR 168 specification does not provide inter-portlet communication, or messaging, capabilities. In WebSphere Portal, the legacy API provides Property Broker Service has been enhanced to provide this function for the standard API.

One of the key differences between servlet execution and portlet execution is the two-phase execution process in WebSphere Portal. Before the portlets of the active page are rendered, an event phase takes place during which the portlets can process events (such as actions and portlet-to-portlet messages) and update their internal state. The portlet programming model assumes that state changes in portlets take place during the event phase and that the subsequent render phase only generates markup based on the current state of the portlets. However, the generated markup could still change between multiple portlet render invocations, even if the portlet state stays the same; for example, a portlet displays information retrieved from a backend system.

This design difference is one area that needs specific attention when migrating servlets to portlets. With potentially many portlets getting executed as a result of a single Web page request, developers need to follow good programming practices to make sure that portlets can re-render themselves correctly, even when there is no user interaction with that portlet.

At the start and end of the event phase, optional listener methods of portlets on the page are invoked. User initiated interaction, portlet messaging, and property broker activities can invoke event phase processing over many portlets on a page. Of course, not all portlets will get invoked during the event phase. Only when all event phase processing has completed will the render phase begin.

Legacy portlets can access the same request and response objects between action and rendering phases. Portlet developers sometimes put objects on the request during the action phase that the subsequent rendering phase would reference. JSR 168 provides unique instances of the request and response for each phase, so you cannot share parameters between phases using those objects; instead, use render parameters. Render parameters are unique to JSR 168 and are encoded in the URL itself, so that action and state are represented in the URL and can be bookmarked. Browsers can then return a portlet to a specific rendering state or view. The portlet developer must properly use render parameters to fully represent the portlet state.

Filed in:
0 Comments To ' Understanding the IBM Portlet API and JSR 168 '

Post a Comment