Comment lines: Sending parameters to the JSR 286-based Web Content Viewer portlet from external applications

The new JSR 286-based Web Content Viewer portlet that is part of IBM® WebSphere® Portal V6.1.5 adds a lot of new features and has a lot of advantages. However, if you want to send parameters from an external application to the portlet, it works very differently in the new portlet compared to the old one. This article describes how you can easily send parameters to the new portlet and why this difference exists. This content is part of the IBM WebSphere Developer Technical Journal.


Stefan Hepper, WebSphere Portal Programming Model Architect, IBM

Author photoStefan Hepper es arquitecto del producto de Lotus Web Content Management y parte del equipo de desarrollo del producto WebSphere Portal and Lotus Web Content Management. Sus responsabilidades anteriores, entre otras, incluyen haber sido programador en jefe de V6.1.5, líder de Java Portlet Specification V 2.0 (JSR 286). Ha dictado conferencias internacionales tal como JavaOne, ha publicado varios documentos y fue co-autor de los libros Pervasive Computing (Addison-Wesley 2001) y Programming Portlets: From JSR 168 to WebSphere Portal Extensions (McPress, 2007). Stefan recibió un Diploma en Ciencias de la Computación de la universidad de Karlsruhe, Alemania. Se unió al IBM Boeblingen Development Laboratory en 1998 y es parte del IBM Silicon Valley Lab desde el año 2009.

developerWorks Professional author

14 July 2010

Also available in Chinese Portuguese Spanish

Old versus new

The information in this paper refers only to URLs generated by external systems. URLs generated within the WebSphere Portal framework will be simple and should use the IBM Web Content Management UrlCmpnt tag.

The first version of the new Web Content Viewer portlet was provided in the IBM® Lotus® and WebSphere® Portal Business Solutions Catalog in January 2009. An updated version was included in the IBM WebSphere Portal V6.1.5 feature pack that was released at the end of 2009. In addition to many new features, this updated version is based on the second version of the Java Portlet Specification JSR 286. Although this enables many new features, there is one disadvantage when compared to the earlier Web Content Viewer, which was based on the IBM Portlet API: passing a parameter to the viewer portlet became a bit more complex. However, as you'll see in this column, you also get additional benefits.

How the old Web Content Viewer portlet worked

In the IBM Portlet API version of the viewer, you simply added a query parameter to a URL addressing the page and all the IBM portlets on that page received that parameter. You then configured the portlet to listen to broadcasts and created a URL in the format:

Listing 1
<pathCmpnt type="noprefixservlet" />/[LIBRARY]/[SITE]/[SITE_AREA_PATH]/[CONTENT]

For example: http://mysystent/wps/portal/home?WCM_GOBAL_CONTEXT=/mynewslib/usnews/news1.

This portlet is simple to use, but it has the following drawbacks:

Due to display restrictions, some of the URLs shown in this article might appear to be made up of multiple lines. In practice, each URL would in fact be a single continuous line.

  • Since the parameter is not maintained in the URL, it needs to be stored in the session (even in the case of anonymous use) and therefore impacts portal server memory consumption.
  • Once you’ve interacted with the page and the parameter is no longer in the URL -- but stored in the session -- you can no longer bookmark your selection.
  • For static pages, caching in the browser doesn’t work because the selection is not encoded into the URL. This means the browser can’t distinguish between news item 1 and news item 2 and therefore cannot cache on the browser level.

Let's take a look at how the viewer works in the brave new world of JSR 286.

How the JSR 286-based Web Content Viewer portlet works

In the new viewer, you use the URI resolver framework in WebSphere Portal to address pages and content items from external systems. The URI resolver framework is a generic resolver framework that can also be leveraged for custom URI schemes. Web Content Management defines the schema wcm: as follows:

wcm:path:LIBRARY/SITE_AREA_PATH/CONTENT [[& page=unique_name | object_id] &mapping=mapping | &current=true]

This means that you provide the path to the content and then optionally provide one of the following:

  • A target page, using either the unique name of the page or its object ID.
  • A URL mapping.
  • The current page selected in the URL to use before the URI.

If you don't provide any of the above, WebSphere Portal automatically tries to find the right page. This works only if you’re using the Web Content Pages, where you map a Web Content Management site area to a portal page so that WebSphere Portal is aware of the relationship.

So, how do you get a complete URL now? You have a couple of different options:

  • Address the WebSphere Portal resolver framework directly via /wps/poc or /wps/mypoc.
  • Use any URL for WebSphere Portal that is known by the external application.

Let’s look at a sample setup in the Web Content Management Web Content library that contains the following:

  • A site area called NewsUS and content items News1, News2, News3.
  • A site area called NewsEurope and content items News4, News5, News6.
    Figure 1. Library Explorer
    Figure 1. Library Explorer
  • The following portal pages with friendly names:
    • Top level: Products, Company News
    • Second level: Products/Cars, Products/SUVs, Company News/US, Company News/Europe
    • US and Europe are Web Content pages. US is mapped to Web Content Management site area Web Content/NewsUS, and Europe is mapped to Web Content Management site area Web Content/NewsEurope.

Figure 2 shows the advanced section of the Europe page properties displaying the mapping to the NewsEurope Web Content Management site area.

Figure 2. Advanced section of the Europe page properties
Figure 2. Advanced section of the Europe page properties

We'll also define a URL mapping for /coolCars to the Products/Cars page so that the URL http://host_name/wps/portal/coolCars will take you to http://host_name/wps/portal/Products/Cars.

Following are some sample URLs:

  • Addressing the portal resolver framework directly:


    This URL tells the portal to render the content item with the library path Web Content/NewsUS/News1. WebSphere Portal will look up the Web Content Page that is mapped to the NewsUS site area (Company News/US), redirect to that page, and set the context of that page to the content item library path.

  • http://host_name/wps/mypoc?urile=wcm%3Apath%3A/Web+Content/NewsUS/News1&mapping=/coolCars

    This URL tells WebSphere Portal to render the content item the same way as the previous URL, but instead of doing the dynamic page look-up to do a redirect to the page /Products/Cars, which is mapped to the URL /coolCars, as shown in Figure 3.

    Figure 3. Addressing the target page by mapping /coolCars to the selected Products/Cars page
    Figure 3. Addressing the target page by mapping /coolCars to the selected Products/Cars page
  • Addressing the portal via a friendly URL:


    This URL tells WebSphere Portal to select the page /Company News/Europe and render the content item Web Content/NewsUS/News2 on this page. Notice that without the parameter current=true, WebSphere Portal would redirect to the page /Company News/US, because that is the page that is mapped to the NewsUS site area.

Figure 4. Addressing the page using the friendly URL path Company News/Europe and rendering the USNews site area
Figure 4. Addressing the page using the friendly URL path Company News/Europe and rendering the USNews site area

There must be at least one JSR 286 web content viewer portlet on the target page and it must be configured to receive links from Other portlets and this portlet, as show in Figure 5.

Figure 5. JSR 286 Web Content Viewer Portlet configured to receive links from other portlets
Figure 5. JSR 286 Web Content Viewer Portlet configured to receive links from other portlets

Why are these URLs, being used to address the new viewer portlet, not as pretty as the simple schema indicated above, but instead contain all these special characters? We’ll talk about that next.

URL and URI encoding rules

You might know that valid URLs need to follow specific encoding rules defined in RFC 1738, and must replace reserved characters, such as " " (space) or ":". In the example above, the " " (space) character was replaced with "+" and the ":"character was replaced with a %3A.

One detail we didn’t explain is the "urile" that comes before the schema part. You actually have two choices: you can specify "uri" or "urile." The difference is that if you use the uri scheme, you need to follow the URI encoding rules in addition the URL encoding rules, so the URL:


would look like this using the "uri" scheme:

http://host_name/wps/portal/Company+News/NewsEurope?uri=wcm%253Apath%253A%2FWeb%2BContent%2F NewsUS%2FNews2%26current%3Dtrue

See RFC 3986 for more information on how to encode special characters for URIs. Because these URIs would be difficult to construct by hand, WebSphere Portal provides a simplified URI version that only needs to be URL encoded rather than URI encoded using the urile scheme.

Why the JSR 286 solution is different

The Java Portlet Specification V 2.0 (JSR 286) defines something called a render parameter that is provided to the portlets for each request. For example, when the user presses the browser's reload button, the portlet gets the same render parameters again and can render the same view. This means that the portlet does not need to store this navigational state information in the session any longer, as was the case with the IBM Portlet API based portlets.

There are two different types of render parameters: private, which are private for each portlet window on the page, and public, which are shared. The public parameters give you the ability you had in the old IBM Portlet API to add a query parameter to the URL and receive it with the portlets on the page. The query parameter solution of the old IBM Portlet API has two disadvantages:

  • You only get the parameter for one request; after that each portlet on the page needs to store the value in the session. This requires having sessions even in the case of anonymous use.
  • You don't know what parameter a portlet understands, as the portlets don’t formally declare this. You can even run in a situation where two portlets define the same parameter name, but with different semantics that would prevent you from putting these two portlets onto the same page, and you wouldn’t know this beforehand.

In order to overcome these limitations, the JSR 286 specification defines public parameters and uses the QName naming schema, well known from XML documents (see Namespaces in XML 1.0) for the name of the parameter. WebSphere Portal stores the parameter name and value as part of the URLs on the page so that those URLs are bookmark-able and avoid using a session. Because you might have many public and private render parameters that you need to store in the URL, you need to make sure that the URLs don't get too long. WebSphere Portal does this by zip-encoding that part of the URL, which then looks something like this:

Listing 2!

If a specific parameter gets too large, it is stored in the session and only the reference key is stored in the URL. This helps to keep the URL below the 2K size limit enforced by many browsers or other HTTP infrastructure components, such as proxies.

The disadvantage of this solution is that you are now no longer able to create these parameters by hand because of the encoding. Therefore, Portal provides you with the above mechanism of adding a simple URI at the end of a portal URL. Voila! You now have the best of both worlds: you are leveraging the navigational state pattern defined via the JSR 286 public render parameters and you can easily set parameters on a specific URL.


When moving from the old Web Content Viewer, a Web Content Management rendering portlet, to the new JSR 286-based version, you gain a lot of new functionality, like bookmark-ability by storing the selected context in the URL. However, you also seem to lose a simple way to send parameters from an external application to the Web Content Management rendering portlet. This column described a simple way to gain back that ability without losing any of the new features by using a URI attached to the URL.



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

Zone=WebSphere, Lotus
ArticleTitle=Comment lines: Sending parameters to the JSR 286-based Web Content Viewer portlet from external applications