Old versus new

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.

Back to top

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:

http://[PORTAL_HOST]/[PORTAL_CONTEXT_ROOT]/[PORTAL_PAGE_URL_MAPPING]/?WCM_GLOBAL_CONTEXT=
<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:

• 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.

Back to top

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
  
  
  
• 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.

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:

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

  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
  
  
  
• Addressing the portal via a friendly URL:

  http://host_name/wps/portal/Company+News/Europe?urile=wcm%3Apath%3A/Web+Content/NewsUS/News2&current=true

  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.

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.

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.

Back to top

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%2FNewsUS%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.

Back to top

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:

http://sh1.svl.ibm.com:10046/wps/myportal/Home/Company-News/us/!
ut/p/b1/hc7LDoIwEIXhZ_EBzExppbIcSxSUi4AidGNIvAQiaiLB6NOLxo0LddbffzKgIRcmsyRyxiEDfSzacl805
elYHCAHreU6Sv3YkbGBkzGZ6LrWwHFtwRElZG25vT4zbX5nZgfyDqgJOUJ6iEOaPoGwpnMaMCT2r19BhmKdVMOzf2
sy767aRXWPsKkiI6jU7WJH1yZYzDdpvByRvULy6q7Rn7OhP1Pd7CzkPFQME-MNfr31AvjlCCFwTvUWat36513i9qn
XewCN50jf/#Z7_QVMRH7R20GFA60II95HID43007

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.

Back to top

Conclusion

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.

Resources

• IBM Lotus and WebSphere Portal Business Solutions Catalog
  
  
• JSR-286 Portlet Specification 2.0
  
  
• Namespaces in XML 1.0
  
  
• IBM developerWorks WebSphere
  
  
• IBM developerWorks WebSphere Portal zone
  
  

About the author

Stefan Hepper is a Lotus Web Content Management product architect and part of the WebSphere Portal and Lotus Web Content Management product development team. His previous responsiblities among others include chief programmer of V6.1.5, lead of the Java Portlet Specification V 2.0 (JSR 286). He has delivered lectures at international conferences such as JavaOne, has published various papers, and was co-author of the books Pervasive Computing (Addison-Wesley 2001) and Programming Portlets: From JSR 168 to WebSphere Portal Extensions (McPress, 2007). Stefan received a Diploma of Computer Science from the University of Karlsruhe, Germany. He joined the IBM Boeblingen Development Laboratory in 1998 and is part of the IBM Silicon Valley Lab since 2009.

Rate this article

Comments

Back to top

Table of contents

• Old versus new
• How the old Web Content Viewer portlet worked
• How the JSR 286-based Web Content Viewer portlet works
• URL and URI encoding rules
• Why the JSR 286 solution is different
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers