+

Search Tips   |   Advanced Search


Comparing the standard portlet API to the IBM portlet API

Find out about the similarities and differences between the standard portlet API and the IBM portlet API.

Between the Java Portlet Specification and the IBM portlet API, the fundamental concepts of portal servers are the same. The portlet container is the run time 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.


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 shares many of the same characteristics (see Relationship with the Servlet Specification in the Java Portlet Specification).

The standard portlet API takes advantage of much of the functionality provided by the servlet specification, such as deployment, class loading, Web applications, Web application lifecycle management, session management and 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, which is a concrete portlet instance parameterized with the session, a mode and window state ( 3 ).

Logical representation of portlets in the Java Portlet Specification

In WebSphere Portal, 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(), and doHelp(). Using the standard portlet API, 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 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 run time, 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 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, 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 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 run time portlets use PortalContext.getSupportedWindowStates() to retrieve the modes supported by the portal and adapt accordingly.

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/> - 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/> 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, 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. Example: 

<%=  portletResponse.encodeURL(renderRequest.getContextPath()
     +  "/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. Example: 

<%= renderResponse.encodeURL("/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

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, 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 run time the portlet can use the USER_INFO constant of the PortletRequest to determine which of the requested user profile attributes are available. For a list of attributes refer to the JSR portlet specification.

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

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 run time using PortletConfig.getResourceBundle().

This provides globalizations 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 globalized 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 globalizing 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


Parent topic:

IBM Portlet API


Related tasks


Enable customization of portlet title


Related information


Converting IBM portlets