Exploiting the WebSphere Application Server V6.1 portlet container: Part 4. Migrating portlets between WebSphere Application Server and WebSphere Portal

This article series examines the JSR 168 portlet container available in IBM WebSphere Application Server V6.1 and differentiates its use from IBM WebSphere Portal.

Part 1 introduced the portlet container and described how to install and access a portlet, and how to use URL Addressability.

Part 2 illustrated some extended capabilities of the container including how to render a portlet within a window frame, display multiple portlets, get information about deployed portlets, and change the default portlet behaviour.

Part 3 showed how to use performance monitoring and measurement techniques to analyze performance bottlenecks with the portlet container.

Part 4 compares the extended portlet programming model of WebSphere Portal to portlet support in WebSphere Application Server so that you can determine what if anything you need to change if you decide to migrate your portlets between the two environments. You can download the sample portlet, and then deploy and run it in both platforms.

This series is for Java™ programmers, portlet programmers, and Web administrators who are familiar with the Java Portlet API. See Resources for links to information that can help you gain those skills.


Birga Rick (brick@de.ibm.com), Portlet Runtime Technical Lead, IBM

Birga Rick is Technical Lead for WebSphere Application Server Portlet Runtime at the IBM Boeblingen Lab in Germany. In 2003, she was part of the team implementing the JSR168 Reference Implementation, Pluto. Following her work on JSR 168 within the WebSphere Portal development team, she integrated the Portlet Runtime into WebSphere Portal and WebSphere Application Server.

Stephan Hesmer (stephan.hesmer@de.ibm.com), Performance Chief Developer, IBM

Stephan HesmerStephan Hesmer is currently working as Performance Chief Developer. In his previous role he worked as Portlet Runtime architect in WebSphere Portal and WebSphere Application Server. He is responsible for integrating the JSR 168 portlet container into WebSphere Application Server. Stephan worked on the JSR 168 Java™ Portlet Specification, and designed and implemented the initial version of the JSR 168 Reference Implementation, Pluto. Stephan received a Diploma of Information Technology from the University of Cooperative Education Stuttgart, Germany, in 2000. After graduating, he joined the IBM Böblingen Development Laboratory to work in the WebSphere Portal Team.

01 November 2006

Also available in Japanese


Today, portal developers are accustomed to having a variety of features and rich functionality in portals. Two main capabilities of these platforms are an extended portlet runtime environment supporting the portlet programming model and a sophisticated portal framework that aggregates and manages portal artifacts such as portlets and pages.

WebSphere Portal offers a wide variety of portal features, many of which support the portlet programming model and enrich the portlet experience through the extended portlet runtime. In contrast, the WebSphere Application Server V6.1 portal related feature set concentrates on the portlet runtime; it provides only a minimal set of portal features.

In this article, you learn the portlet runtime and portal feature differences provided by these two products. To develop portlets which can leverage the capabilities in the deployment runtime, you need to understand the extended programming model. By understanding which parts of the model are supported in each platform, you can implement portlets that can gracefully degrade (when you migrate them between the two runtimes) in those cases where the runtimes support different capability sets.

About the samples

The world clock sample code provided with the article, Converting the WorldClock portlet from the IBM Portlet API to the JSR 168 portlet API is a good example of a JSR 168 portlet that was written to run on WebSphere Portal only; it uses the bidi tag that belongs to the extended portal programming model which is beyond the standard Portlet API. For more information, see the JSP tags for standard portlets topic in the WebSphere Portal InfoCenter. While the use of this extended capability is not required for the simple world clock portlet, this is also a good example where graceful degration would be recommended.

You can either remove this dependency or add an intelligent Java class to gracefully degrade the functionality and then the portlet can run on other platforms as well. The World Clock sample portlet provided with this article series is adapted accordingly to run on both platforms.

Portlet programming model

All IBM products that support the JSR 168 Portlet Specification are based on the same technology. However, they are embedded into different technology stacks and offer different supported extensions, depending on the portal framework and plug-points provided by the corresponding environment.

WebSphere Portal and WebSphere Application Server vary in the capabilities provided by their portal frameworks. WebSphere Application Server concentrates on the portlet runtime for executing single portlets, whereas WebSphere Portal provides full-support for administration and management of simple and sophisticated page aggregations and integration to several back-end systems, such as databases for persistence storage.

While WebSphere Application Server's programming model lets you work with portlet components, WebSphere Portal lets you work with composite applications. It includes a sophisticated application framework for business users to easily assemble and customize linked applications, and to process components into composite applications.

To understand the differences between the extended portlet programming models of WebSphere Portal and the Portlet API programming model of WebSphere Application Server, we compare their portal features provided to support JSR 168 portlets.

URL (Uniform Resource Locator) addressability in WebSphere Application Server is the simplest form of a portal framework. It lets you render a single portlet on the page; it is very easy to use and is best suited for development. You can customize portal aggregations to leverage and extend URL addressability, to some extent, and to enhance its capabilities. (See Part 2 of this article series.)

WebSphere Portal provides a feature-rich portal framework with many extensions. Explaining all features would go beyond the scope of this article. (see the WebSphere Portal InfoCenter). This article discusses those features that have an effect on the portlet programming model, and compares them with WebSphere Application Server.

Table 1 shows the features that we compare. You will see how they work in each environment and the differences that can cause an impact to portlets that you expect to run on both runtimes or to migrate.

Table 1. List of features that make a difference in migration.

Portal featuresShort explanation
Page aggregationEnvironment specific aggregation framework that have to deal with long portal URLs
User managmentEnvironment specific handling of user, groups and access control
Portlet preferencesStorage location for portlet preferences to enable persistency
Portlet modesSupport of custom portlet modes such as CONFIG or EDIT_DEFAULTS
Portlet fragment cachingEnvironment specific cache configuration

Page aggregation dealing with URL handling

The WebSphere Portal portal page aggregation framework lets you easily organize portlets on pages, and it makes the most complex page structure an easy task to handle. WebSphere Application Server lets you easily display one portlet on a page; therefore, it requires no special handling to deal with multiple portlets and pages. Even so, there are still challenges that we will address within this section. For example, the navigational state handling is handled slightly different, although its conceptually similar in both environments.

Each portlet can render several portlet URLs within its markup that refers to a portlet on the same page. Usually this is done by calling createRenderURL or createActionURL.

Usually the intention of adding render parameters to the portlet url, as part of the navigational state of a portlet, is to make a particular view to a portlet bookmarkable, and to enable back and forward button behavior. However, this behavior is not enforced by the JSR 168 Portlet Specification. With those parameters attached to a portlet URL, the user can directly address a particular view to a portlet. This benefit is constrained by the maximum possible URL length.

To enable bookmarking and direct address, we recommend that each URL contain the navigational state information, including all render parameters of all portlets on (at least) the requested page. As you can easily imagine, a URL containing this kind of information can easily be very long.

WebSphere Portal takes care of URLs that become too long by using a variety of advanced features (such as compression) and other storage (such as the HttpSession) because the risk that page aggregations create long URLs is very high. Therefore, all URLs created by WebSphere Portal are valid, but they might not all be bookmarkable. You can be influence the outcome through the highly configurable URL handling.

WebSphere Application Server does not provide advanced features to configure URL handling like WebSphere Portal. WebSphere Application Server appends all render parameters to the portlet URL, even if the URL becomes too long. Therefore, all URLs created by portlets based on WebSphere Application Server can be bookmarked; however, the unfortunate side-effect is that portlets that use long or a lot of render parameters might cause invalid URLs. However, the risk is lower than for portal frameworks that normally include several portlets per page.

In general, we recommend that portlets minimize the number and size of render parameters as much as possible so that the risk of invalid URLs decreases. Because of the differences in parameter handling, the risk when a URL is very long is that portlets that run fine on WebSphere Portal can fail on WebSphere Application Server.

On WebSphere Application Server, the portlet might run into browser limitations and errors caused by URLs that are too long. For example, a portlet URL with 80,000 characters can be rendered using Mozilla Firefox, while Microsoft® Internet Explorer does not react to a link that references such a long URL.

User management with security aspects

WebSphere Portal provides full support for user management and extended security concepts. A user logging into portal can only see and work with those for which portlets the user has the necessary access rights. Portlets can retrieve information about the current user according to the User Information programming model as specified by the JSR168 Portlet Specification (PLT17).

WebSphere Portal user management is based on WebSphere Member Manager (WMM) which lets you easily integrate third party user management systems. Because of the close WMM integration, portlets can request detailed information about a user according to the data that is

  • Available in this back-end User Management System,
  • Mapped to one of the User Information Attribute Names available for portlets (JSR 168 Portlet Specification 1.0, PLT.D), and
  • Configured for the specific portlet within the portlet deployment descriptor according to the JSR 168 Portlet Specification 1.0.

WebSphere Application Server provides a user management system called Virtual Member Manager (VMM). The portlet container and VMM is not currently integrated, because this type of complex capability needs to be provided through a portal framework.

Portlets can reference user information to react to each user’s characteristics differently. Although the portlet container in WebSphere Application Server cannot access a feature-rich user management , user information is available to portlets on both platforms through getRemoteUser() or getUserPrincipal() on the PortletRequest. Portlets can also access the security attribute isUserInRole according to the user-in-role mapping defined within the portlet deployment descriptor, as specified by the JSR168 Portlet Specification (PLT.11.1.6).

For portlet and page specific access control management, WebSphere Portal provides a comprehensive security management that lets you control user actions. For example, only users with sufficient access rights can use edit mode on a portlet to customize portlet preferences.

The security model of portlets within WebSphere Application Server has been aligned with the servlet security model because portlets can be addressed just like servlets through URL addressability. Because the servlet security model does not permit an aggregation scenario, the portlet runtime within WebSphere Application Server does not provide user or access control management to handle portlets or pages.

Portlets run on both platforms as long as they are not based on security role references defined within the portlet deployment descriptor. These security role references are currently only supported by WebSphere Application Server.

In summary, the affinity of the programming model lets you create portlets that act on user information that can run on both platforms. In addition, WebSphere Portal offers sophisticated portlet and page access control management to manage portlet invocations by users.

Portlet preferences and modes

Next, let's look at PortletPreferences and modes.

Preferences are kept in layers that are modifiable based on portlet modes. For example, there is one layer of default preferences defined by the portlet deployment descriptor. This layer is modifiable within the CONFIG mode supported by WebSphere Portal. In WebSphere Application Server, the values of the portlet deployment descriptor are read-only.

WebSphere Portal provides one additional preference layer that enables portal administrators to specify different default values per portlet window. This capability is supported through the portlet mode EDIT_DEFAULTS, and applies to all who use the same portlet window. There is no such preference layer in WebSphere Application Server.

Both products support the standard modes: VIEW, EDIT, and HELP. When a user customizes a portlet on a page in any standard mode, the user can change his personal portlet preferences. Default preferences on a per page or per portlet base cannot be set in any standard mode; you would need to use custom portlet modes instead.

In WebSphere Application Server,end users can invoke a portlet method for any arbitrary custom portlet mode. Unless a customized aggregation framework changes the behavior, only the standard portlet modes act as expected and specified by the JSR 168 Portlet Specification (PLT.A). In other words, all preferences are stored in the same scope as the standard modes (VIEW, EDIT, and HELP ) when calling a portlet within a custom mode. Therefore, the portlets can be invoked within the CONFIG or EDIT_DEFAULTS mode, but the portlet mode has no effect on the preferences layer. Consequently, no default preference value can be modified.

In summary, all standard portlet modes are supported by the two products. The portlet modes EDIT_DEFAULTS and CONFIG allowing to modify default preference values on a page or portlet scope are only fully supported by IBM WebSphere Portal.

Portlet fragment caching

Portlet fragment caching is based on the Dynacache feature of WebSphere Application Server. Therefore, the cache key for portlets running in WebSphere Application Server is configurable in detail using cachespec.xml. For more details, see the Configuring cacheable objects with the cachespec.xml file topic in the WebSphere Application Server InfoCenter.

In contrast, WebSphere Portal permits limited configuration using an ibm-portlet-portal-ext.xmi file. The cachespec.xml has currently no effect on portlets running on WebSphere Portal.

In WebSphere Portal, cache content is scoped per user by default. To enable all users to share the same portlet output using a reverse proxy, you can configure the remote-cache-scope setting to be shared:

<portlet href="RemoteCacheSettingsTestPortlet">

This corresponds to specifying the cache key within the cachespec.xml for not having the sessionid as part of the key. When you define the sessionid to be part of the cache key, the portlet content is cached on a per user base. Sharing portlet cache content is the default behaviour for portlets running in WebSphere Application Server, so that portlet developers have to explicitly specify whenever they want the cached content to be scoped by user:

Suppose you want to migrate a portlet that was originially coded for WebSphere Portal, (where its content is cached per user) to Application Server. To support user-scoped caching, the Application Server administrator would need to specify that the cache key within the cachespec.xml use the sessionid.

    <property name="consume-subfragments">true</property>
       <component id="" type="sessionId"/>

In contrast to shared caching, the expiration-cache specified by the portlet deployment descriptor does commonly configure the expiration time for the cached portlet output, independent of the environment.

Subfragments included by portlets, such as Java Server Pages (JSPs), are cached as portlet content in WebSphere Portal. This is configurable for portlets running on WebSphere Application Server. To enable subfragment caching, you can specify the property consume-subfragments in the cachespec.xml as true. WebSphere Application Server does not cache subfragments by default.

<property name="consume-subfragments">true</property>

From the portlet programming point of view, portlets can configure caching as specified by the Portlet Specification (PLT.18.1). The portlet deployment descriptor can define an expiration-cache time and, it can allow portlets to programmatically change this configuration by setting the pre-defined response property javax.portlet.PortletResponse.EXPIRATION_CACHE during runtime.

You can configure portlet fragment caching more precisely in both environments, but these extensions are portal specific and are different in WebSphere Portal and WebSphere Application Server. Therefore, cache configuration partially requires individual settings that are dependent on the environment.

In summary, both environments let you specify cache settings within the portlet deployment descriptor. Extended cache settings are portal specific; you configure them in the ibm-portlet-portal-ext.xmi file for WebSphere Portal and in cachespec.xml for portlets running on WebSphere Application Server.

Extended programming model

In the previous major section, you learned the differences in the portlet environments implementing the JSR 168 Portlet Specification. In this section, you see the extended programming model that encapsulates all features provided in addition to the JSR168 Portlet Specification.

WebSphere Portal and WebSphere Application Server vary in the environment surrounding the provided portlet runtime; this environment is often called the portal framework or portal engine. To understand the differences between the extended programming models of WebSphere Portal and WebSphere Application Server, we compare their different plug-points and portal features that are not covered by the Portlet Specification.

WebSphere Application Server programming model

This article series has primarily explained the programming model and extensions provided for portlets running on WebSphere Application Server. Some extended features of WebSphere Application Server are provided for portlets, such as the Performance Monitoring Infrastructure or the Request Metrics, as discussed in Part 3.

Other WebSphere Application Server features are extended to support portlet-specific needs. For example, the remote request dispatcher can also be used for URL addressable portlets. This means that portlets can run in different JVMs and can be included using a remote call.

Therefore, the programming model of WebSphere Application Server consists of all mandatory parts of the Portlet Specification JSR168 and of the programming model extensions explained in this article series.

WebSpere Portal programming model

While WebSphere Portal provides a large number of extensions to the portlet standardized programming model, only a few of them are described in this section. Analyzing them all is beyond the scope of this article.

WebSphere Portal delivers a meaningful set of portlet services to provide additional features, such as credential vault and content access services. The PortletServices concept lets you extend the portlet programming model using custom API extensions to portlets. You can also add functionality to the portlet programming model.

In addition WebSphere Portal provides portlet framework support. With its full aggregation platform, WebSphere Portal enables aggregation of multiple portlet frameworks on one page. Therefore, portlet frameworks are supported and should follow best practices such as a good Model-View-Controller design. Examples of supported portlet frameworks are the Java Server Faces (JSF) and Struts frameworks.

Tables 2, 3, and 4 list additional features provided by WebSphere Portal that extend the mandatory JSR168 Portlet Specification.

Table 2. Optional specification parts supported
Portlet modes supportCONFIG, EDIT_DEFAULTS
User attributesMember Manager attributes mapped to the P3P attributes. Additional custom attributes can be accessed.
CachingCaching support
Markup propertyUse to handle markups that are not distinguishable using the MIME type, like cHTML
Enhanced portlet administration capabilitiesFor example, clone portlet applications that allows portlets to be on shared pages
Parallel portlet renderingRendering portlets in parallel threads
Portlet servicesServices providing additional functionality for portlets beyond the portlet API
Table 3. Functions provided in addition to the standard
CC/PP ProfileCC/PP Profile as request parameter (JSR188 support)

Struts Portlet Framework

Integrates JSR168 portlets into the struts framework

Advanced caching support

Remote caching in edge servers

Inter-portlet communication

Portlets can send events to other portlets on the same page or different pages based on the property broker

Portlet URL generation

Enables portlets to create URLs to other portlets and pages (ActionURL, RenderURL)

Search API

Unified API to search different backend search products

Task processing

Enable portlets to integrate with Process Server

Web Content Management

Enable portlets to leverage Web Content Management

Policy API

Check and modify policies from your portlets

Page launching

Launch transient pages

Prebuilt portlet services

Credential vault service to store backend credentials, Content access service to access content on other

Table 4. System Programming Intefaces (SPIs)
Aggregated Meta Data model SPIEnables inheritance of MetaData
Drag and Drop SPIEnables defining drag sources or drop targets
Puma SPIAllow read/write access to the user registry. Only use this API if the standard user attribute map is not sufficient
Credential Vault SPIEnables customers to provide their own vault implementation
Model SPIGives access to the different portal models, like the content model, navigation model, and so on

When using any of these portal extensions, make sure to gracefully degrade them if they are not available. If portlet developers follow this guideline, the portlets can also run on WebSphere Application Server even though these extensions are not available. The following code snippet shows an example that uses WebSphere Portal’s portlet service extension accordingly:

// check for extension availability
Object obj = null;
javax.naming.Context ctx = 
new javax.naming.InitialContext();
try {  
  obj = (Object) ctx.lookup("portletservice/com.mycomp.CalcService");
  } catch(javax.naming.NameNotFoundException nnfe) {
 ... error handling ...
// service usage (best to move in own class)
if ( obj != null ) {
  PortletServiceHome psh = (PortletServiceHome) obj;
  CalcService service = (CalcService) psh.getService(CalcService.class);  

To increase the range of functionality provided for portlets intended to run on several portal platforms, IBM is helping to define the Java Portlet Specification Standard JSR 286. Many useful extensions already in WebSphere Portal will become standarized in a more generic fashion. For example, the Portlet API 2.0 proposal standardizes inter-portlet communication and portlet filter extensions.

Migration themes

With the comparison of the portlet programming model and extensions in WebSphere Portal and WebSphere Application Server, you now know how they differ and where to expect migration issues.

As a rule of thumb, portlet developers should keep in mind that portlets run on either platform as long as you develop them independently of any portal specific extensions. Table 5 lists migration themes described in this article.

Table 5. Migration quick reference for portlet developers

Programming Model / RecommendationsWebSphere Application ServerWebSphere Portal
Render Parameters too longResult in invalid URLsResult in valid, but not bookmarkable, URLs
Security constraintsSecurity-constraint definition in portlet.xmlHandled by portal when logged in
Portlet modesStandard modesStandard modes and EDIT_DEFAULTS, CONFIG
Window statesStandard statesStandard states and SOLO
Portlet cachingDefinition in cachespec.xmlDefinition in ibm-portlet-portal-ext.xmi
Portlet servicesNot supportedSupported
Portlet frameworkNot explicitly supportedSupported


This part concludes our article series on the portlet container in WebSphere Application Server.

In this final part, you learned to distinguish between the portlet runtimes in WebSphere Portal and WebSphere Application Server. Although the portlet containers are based on the same technology, each portal framework differentiates in goal and extensions.

Understanding the differences between WebSphere Portal and WebSphere Application Server can help you to address migration issues for portlet applications. The explanation and comparison of both programming models discussed those features which you can easily use in both environments. With the awareness of extended features, portlet applications can also be implemented to run differently according to available programming model extensions.

A good understanding of the two products discussed in this article lets you correctly use each product and to create portlet applications that work on both platforms out-of-the-box, and to leverage the set of provided capabilities or degrade gracefully if a capability is not provided by the given runtime.


World clock portletStdWorldClock.war75 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Exploiting the WebSphere Application Server V6.1 portlet container: Part 4. Migrating portlets between WebSphere Application Server and WebSphere Portal