Introduction to OpenPortal WSRP Version 2.0 Beta Software

The Web Services for Remote Portlets (WSRP) specification is defined by the WSRP Technical Committee at the Organization for the Advancement of Structured Information Standards (OASIS). OASIS recently approved the latest version of the WSRP specification, called WSRP version 2.0.

This article covers the basic information necessary to work with OpenPortal WSRP version 2.0 beta software that complies with the OASIS WSRP version 2.0 specifications. In addition, it provides instructions for exploring the various features defined in the specification.

The OASIS WSRP version 2.0 specification defines the following major additional functionality over the existing WSRP version 1.0 specification:

• Eventing
• Shared/Public Render Parameters
• Caching
• Leasing
• Resource Serving
• Support for CC/PP and JSR 188

As part of OpenPortal, the OpenPortal WSRP Project aims to develop a WSRP version that complies with the specification. The OpenPortal WSRP Project implements all the mandatory features and some of the major optional features that are defined in the WSRP version 2.0 specification.

The OpenPortal WSRP Project depends on the OpenPortal Portlet Container Project that implements the JSR 286 specification.

JSR 286 is another related specification from the JCP (Java Community Process), which defines version 2 of portlets. We will try to contrast and compare these two specifications in some places and see how these two specifications complement each other.

OpenPortal WSRP 2.0 Beta and OpenPortal Portlet Container 2.0 Update 1 are bundled with Java Application Platform SDK Update 6. OpenPortal WSRP 2.0 Beta 2 and OpenPortal Portlet Container 2.1 are bundled with Java Application Platform SDK Update 7. If you are using this version, you can try both Portlet Container and WSRP from this bundle. These project binaries are also available from their respective project web sites:

• OpenPortal WSRP Project
• OpenPortal Portlet Container Project

The rest of this article walks though the instructions to try out the WSRP 2.0 Beta features.

The OASIS WSRP version 2.0 specification protocol is not over-the-wire backward compatible with the version 1.0 protocol, even though the version 2.0 specification is a logical extension of the version 1.0 specification. The OASIS WSRP version 2.0 specification addresses backward compatibility by exporting a version 1.0 service in addition to the version 2.0 service.

The WSRP version 1.0 consumer is expected to use the version 1.0 service, while the version 2.0 consumer would use the version 2.0 service. However, the WSRP specification optionally provides support where a WSRP resource (such as registration handle or portlet handle) can be supported across both of these services.

To elaborate, a version 1.0 consumer might have created a registration handle or a portlet handle, and the producer can optionally allow a version 2.0 consumer to use the same registration handle and the portlet handle. By allowing this, the producer facilitates migration of data from a version 1.0 consumer to a version 2.0 consumer, somewhat similar to data migration on moving from version 1.0 to version 2.0.

The OpenPortal WSRP supports this configuration. It has an option where a producer can export both WSRP version 1.0 and WSRP version 2.0 service, or only one of them.

OpenPortal WSRP provides administration functionality through the WSRP Producer and Consumer Administrative portlets. These administration portlets are deployed by default upon successful installation of OpenPortal WSRP, and they show up in the OpenPortal PortletContainer driver page.

You can access the Portlet Container driver page using this URL:

http:// <your_host_name>>: <your_port>/portletdriver

The WSRP Producer Admin portlet can be used for creating and managing WSRP producers. The default producer, SampleProducer, is disabled by default.

1. To enable SampleProducer, edit the producer by clicking the SampleProducer link.
2. Publish some portlets by moving the portlets from the Unpublished Portlets list to the Published Portlets list.
3. Click Submit.
4. Edit SampleProducer again.
5. Enable SampleProducer by selecting the Enable radio button.
6. Click Submit to save the changes.

Note: By default this WSRP Producer exports both WSRP version 1.0 and WSRP version 2.0 services in the exported WSDL. Check the WSDL URL to see both version 1.0 and version 2.0 services.

You can also choose to create a new WSRP Producer by using the WSRP Producer Admin portlet.

1. Click New on the WSRP Producer portlet.
2. Provide a name for the WSRP Producer.
3. This screen also provides the option to export a version of the WSRP service. Choose both v1 and v2 to export both version 1.0 and version 2.0 services.
4. Click Submit to save the changes.
5. The newly created WSRP Producer is disabled by default. Follow the steps in the previous section "Enabling the Default WSRP Producer" to enable it.

Note: The administrative portlets have options to create a registration-less producer. Users can get information about the WSRP WSDL version of the newly created producer by clicking on the WSDL URL for the new producer.

The WSRP Consumer Admin portlet can be used for creating and managing WSRP Consumers. To create a consumer, a producer WSDL URL is required. You can choose the WSDL URL from the SampleProducer created in the previous step.

1. Click New on the WSRP Consumer Portlet.
2. Provide the WSRP Producer WSDL URL and click "Get info."
3. The WSRP Consumer automatically recognizes services offered by this WSRP WSDL and provides the user an option to choose a version (version 1.0 or version 2.0), if the producer exports services of both versions.
4. Choose version 2.0/v2 to create a WSRP version 2.0 Consumer.
5. If the producer requires a registration handle, provide the details.
6. In the case of an out-of-band producer, provide the registration handle.
7. Click Save to complete consumer creation.

The administrator is not required to know which versions of services a producer offers. The OpenPortal WSRP Consumer automatically parses the given WSDL and provides the administrator with the correct option to create a WSRP Consumer.

The following screenshots illustrate this sequence of steps.

Figure 1: Admin provides the WSDL URL after clicking New. Click the image to enlarge it.

Figure 2: WSRP Consumer Admin portlet parses the WSDL and provides options to the administrator to choose a WSRP version. Click the image to enlarge it.

Figure 3: The WSRP Consumer Admin portlet provides the option to specify a consumer name. Click the image to enlarge it.

The WSRP Consumer Admin portlets provide a Create link for each of the available consumers. This link enables the user/administrator to create a WSRP portlet window or channel.

1. Click the Create link to create a channel.
2. Choose a portlet from the Available Portlets drop-down menu.
3. Provide a window name in the Window Name text box.
4. Click Finish.

Click the WSRP tab on the portlet container driver to view the remote portlet that you just created.

The preceding sections provided the necessary information to create a WSRP Producer, a WSRP Consumer, and WSRP portlets to view those portlets. The following section assumes that you are comfortable with creating a producer and consumer as previously described and provides instructions to experiment with some of the WSRP 2.0 features. It also provides some background information on each feature.

The following section uses JSR 286 portlet samples listed here. These sample portlets are bundled by OpenPortal Portlet Container. You can get the following portlet binaries here.

• WSRP Eventing (EventingMap.war): Includes ContinentMapPortlet, ContinentPortlet and ContinentInfoPortlet.
• WSRP Shared render parameter (WeatherMap.war): Includes MapPortlet and WeatherPortlet.
• WSRP Caching (MarkupCachePortlet.war and ResourceCachePortlet.war): Includes MarkupCachePortlet (to demonstrate MarkupCaching) and ResourceCachePortlet (to demonstrate MarkupCaching).
• WSRP serveResource (InvoiceAjaxPortlet.war): Includes InvoiceAjaxPortlet.
• JSF GuessNumber

If you need more information on how to write a JSR 286 portlet, refer to the article Understanding the Portlet Container 2.0 Beta.

The Portlet 2.0 specification (JSR 286) allows portlets to communicate with each other using events. Events allow portlets to respond to user actions or state changes that might not be directly related to user actions.

The WSRP version 2.0 specification complements this mechanism by extending these events to portlets that are published or consumed via the WSRP. WSRP version 2.0 provides a mechanism by which a consumer can coordinate events between portlets. These portlets could be from different producers or even local portlets. Consumer-managed coordination provides an option by which a consumer can distribute events across the portlets that it consumes.

WSRP consumer-coordinated eventing allows the following usages:

• It allows a remote portlet (consumed from a producer) to subscribe or publish events to local portlets on the consumer portal.
• It allows a remote portlet (say, consumed from producer A) on the consumer portal to subscribe or publish events to another remote portlet it consumed from another producer (say, producer B).

To demonstrate the WSRP eventing functionality we will use the Eventing Sample Portlet, EventingMap.war.

This application defines the following portlets that participate in the event:

• World Map
• Continent Information
• Continent Map Portlets

Clicking on any continent in the "World Map" triggers an event. This event is processed by the "Continent Information" and "Continent Map" portlets to show the relevant information.

The following screenshot displays these portlets being shown in the portlet driver.

Figure 4: Map portlets in the portlet driver

Use the following steps to configure WSRP Eventing within a single installation of WSRP. This is a loopback configuration where a Consumer points to a Producer that is deployed on the same application server.

Note: Even though both the Producer and Consumer are within the same JVM, all communication happens over the wire (within the same server and in the same process) between the Consumer and the Producer.

1. Deploy the EventingMap.war portlet application using the portletdriver --> admin tab.
2. These portlets appear on the portlets tab. Make sure eventing is working for local portlets by clicking on a continent in the World Map and verifying that the other portlets display relevant information.

1. Create a WSRP Producer, for example, "EventProducer," by clicking the New button on the WSRP Producer Admin portlet.
2. Publish the EventingMap.ContinentPortlet and enable this WSRP Producer.
3. Now create a Consumer named "EventConsumer" that points to the above WSRP Producer WSDL URL. Make sure you choose version 2.0 (v2) while creating this consumer.
4. Click the Create link to create a WSRP Remote Portlet Window. The Continent Portlet appears in the WSRP tab on successful configuration.
5. Click on a continent in the portlet to verify that the local portlets displayed in the Portlets tab are displaying the relevant information.

This configuration demonstrates a mechanism whereby an event fired by a remote portlet is propagated to the local portlet that is displayed or consumed by a consumer portal.

In this configuration, we will try to consume the WSRP Producer deployed on a different machine.

Prepare two machines for this configuration, referred to here as Producer machine and Consumer machine. Alternatively you can have two domains on a single GlassFish server installation or two GlassFish installations on the same machine).

1. Install the GlassFish application server.
2. Install Portlet Container binary version 2.1.
3. Install OpenPortal WSRP version 2.0 beta.
4. Deploy the Eventing Sample Portlet application.
5. Create a WSRP Producer by publishing only the EventingMap.ContinentPortlet.

1. Install the GlassFish server.
2. Install Portlet Container binary version 2.1.
3. Install OpenPortal WSRP version 2.0 Beta.
4. Deploy the Eventing Sample Portlet application.
5. Create a WSRP Consumer that points to the Producer created on machine 1 (the Producer machine).
6. Create a WSRP remote window for ContinentPortlet. This portlet will appear on the WSRP tab.

Now click on a continent in the ContinentPortlet on the producer machine to verify that the remote portlet in the consumer machine displays the relevant information.

This configuration demonstrated a use-case where a remote portlet from a producer threw an event that got propagated to the local portlets deployed on the consumer portal. The difference as compared to the sample configuration is that the WSRP producer and consumer are deployed on separate machines or installations.

You can choose to play with the following configurations:

• A local portlet throwing a event and a remote portlet receiving the event.
• A remote portlet from machine A throwing an event to another remote portlet on machine B, where these two portlets are consumed by a consumer portal on machine C.

Now that you are familiar with eventing functionality associated with WSRP 2.0, we will introduce you to public navigational/public render parameters.

Because public render parameters are encoded in the URL, the restrictions of the URL are applied to the types of objects that can be shared between two portlets, whereas in eventing it's possible for two portlets to share a complex data type.

Another coordination mechanism that is introduced in WSRP 2.0 is public navigational parameters. The JSR 286 specification calls it public render parameters. The public render parameters work like events; the only difference is that the state is encoded in the URL and shared across portlets. Public render parameters are lightweight coordination mechanisms where the coordination happens over the parameters that are encoded in the URL.

To demonstrate the WSRP public navigational parameters functionality we will use the Weather Sample portlet, WeatherMap.war.

The Weather Sample Application has two portlets:

• Weather portlet
• Map portlet

The Weather portlet sets the ZIP code (zip) that is declared as a public render parameter. This parameter is shared by both Weather and Map portlets. Any change in the value of zip by the Weather portlet is reflected during the render phase of both weather and map portlets.

The following screenshot displays these portlets being shown in the portlet driver.

Figure 5: Weather and map portlets in the portlet driver

Let's discuss the steps to configure WSRP public navigational parameters within a single WSRP installation. This is a loopback configuration where a Consumer points to a Producer deployed on the same application server.

Note: Even though both the Producer and Consumer are within the same JVM, all communication happens over the wire between the Consumer and the Producer.

1. Deploy the Weather sample application portlet application using the portletdriver --> admin tab.
2. These portlets appear on the portlets tab. Verify public render parameter functionality for JSR 286 local portlets as follows: Make sure that editing the portlet and adding a ZIP code in the Weather portlet changes the state in the Map portlets by displaying relevant map information.

Note: The Weather portlet uses the Yahoo weather service. If you are behind a firewall, make sure your GlassFish installation has the necessary proxy information.

1. Create a WSRP Producer named SharedRenderProducer by clicking the New button on the WSRP Producer Admin portlet.
2. Publish the WeatherMap.WeatherPortlet and enable this WSRP Producer.
3. Now create a Consumer named SharedRenderConsumer that points to the SharedRenderProducer WSRP Producer WSDL URL. Make sure you choose version 2.0 (v2) when you create this Consumer.
4. Click the Create link for the SharedRenderConsumer consumer to create a WSRP Remote Portlet Window.
5. Upon successful configuration, the Weather Portlet appears on the WSRP tab.
6. Sign in to the portlet driver (default user ID/password for GlassFish are admin/adminadmin) and click the WSRP tab.
7. Edit the remote Weather Portlet and provide a ZIP code. It should bring up the weather report for the provided ZIP code.
8. Now click the Portlet tab to verify that the local portlets (Weather and Map ortlets) display the information according to new the ZIP code.

This configuration demonstrates a mechanism whereby a remote portlet's public render parameters are propagated to the local portlet that is displayed or consumed by a consumer portal.

In this configuration, we will consume the WSRP Producer deployed on a separate machine.

Prepare two machines for this configuration, Producer machine and Consumer machine. Alternatively you can have two domains on a single GlassFish server installation or two GlassFish installations on the same machine.

1. Install the GlassFish application server.
2. Install Portlet Container binary version 2.1.
3. Install WSRP version 2.0 Beta.
4. Deploy the Weather Sample application.
5. Create a WSRP Producer by publishing only WeatherMap.WeatherPortlet.

1. Install the GlassFish application server.
2. Install Portlet Container binary version 2.1.
3. Install WSRP version 2.0 Beta.
4. Deploy the Weather Sample application.
5. Create a WSRP Consumer that points to the Producer created on Machine 1 (the producer machine).
6. Create a WSRP remote window for WeatherPortlet. This portlet will appear on the WSRP tab.

Edit the Weather portlet on the Producer machine and provide a ZIP code to verify that the portlet (Map portlet) in the Consumer machine displays the relevant map information.

This configuration demonstrates a mechanism whereby shared render parameters of a remote portlet are propagated to the local portlets that are displayed or consumed by a consumer portal. The difference as compared to the sample configuration is that WSRP Producer and Consumer are deployed on separate machines or installations.

You can choose to play with these configurations:

• A local portlet that produces a public render parameter to a remote portlet that consumes it.
• A remote portlet from machine A shares a render parameter with another remote portlet from machine B, where these two portlets are consumed by a consumer portal on machine C.

Now that you are familiar with the public navigational/render parameters feature of WSRP 2.0, we will  introduce you to resource serving.

The resource serving feature enables a portlet to serve a resource. Portlets can create two kinds of resource links to serve requests:

• Direct links to the resources in the same portlet web application. Direct links are not guaranteed to pass through the portal server and do not have portlet context available. So a direct link should be used in cases where access to the portlet context and access through the portal server is not needed.
• Resource URL links that point back to the portlet. These links call the serveResource() method of the ResourceServingPortlet. This way, the portlet can serve a resource that is protected by the portal security and can leverage the portlet context. The portlet container does not render any output in addition to the content returned by the serveResource call. Thus, the serveResource() method provides more flexibility to you by giving access to modify the response object, whereas the portal server acts only as a proxy.

In WSRP these two ways of serving resources are captured, which we will refer to in this document as in-band and out-of-band mechanisms of resource serving.

To demonstrate the WSRP in-band resource serving functionality, we will use the Invoice Portlet, InvoiceAjaxPortlet.war.

In the case of Invoice portlet, when the user selects an invoice number from the drop-down box, an asynchronous request (Ajax call) is made by the client-side JavaScript to the WSRP Consumer. The WSRP Consumer translates this to a getResource() method call on the WSRP Producer that invokes the serveResource() method on the portlet, and the content is served by the portlet.

1. Deploy the InvoiceAjaxPortlet.war portlet application WAR using the portletdriver--> admin tab.
2. Make sure that the local portlet is working by testing the portlet under the Portlets tab.
3. Create a WSRP Producer named "ServeResourceProducer" using the WSRP Producer Admin portlet.
4. Publish the portlet and enable the producer.
5. Create a WSRP Consumer using the WSRP Consumer Admin portlet. Provide the WSDL URL of the producer.
6. Upon successful Consumer creation, create a WSRP remote window by clicking the Create link on the WSRP Consumer Admin portlet.
7. View the portlet on the WSRP tab.
8. Choose an invoice from the drop-down menu on the remote portlet to invoke the serveResource() operation on the portlet via WSRP.

Here is a screenshot of the InvoicePortlet application.

Figure 6: InvoicePortlet application

To demonstrate the WSRP out-of-band resource serving functionality, we will use the GuessNumber portlet, guessnumberportlet.war.

This GuessNumber portlet generates a link to an image (resource) that is deployed within the same portlet application. This portlet does not implement the serveResource() method; rather, the resource/image is served by the web container. So the portlet developer has no control over generating the resource.

1. Deploy the guessnumberportlet.war portlet application WAR using the portletdriver--> admin tab.
2. Make sure that the local portlet is working by testing the portlet on the Portlets tab.
3. Create a WSRP Producer named "OutbandResourceProducer" using the WSRP Producer Admin portlet.
4. Publish the portlet and enable the producer.
5. Create a WSRP Consumer using the WSRP Consumer Admin portlet. Provide the WSDL URL of the producer.
6. Upon successful Consumer creation, create a WSRP remote window by clicking the Create link on the WSRP Consumer Admin portlet.
7. View the portlet on the WSRP tab.
8. The Duke image that this portlet displays is fetched out-of-band by the WSRP Consumer.

Here is a screenshot of the GuessNumber Portlet application.

Figure 7: GuessNumber Portlet application

Now that we are familiar with the resource serving functionality associated with WSRP 2.0, let's look into the WSRP 2.0 caching feature.

Caching is an optional feature of WSRP specifications. It helps improve the portal performance.

There are two kinds of caching defined by WSRP specifications:

• Markup caching: In the case of markup caching, the WSRP consumer caches the content generated by the render call of a portlet.
• Resource caching: In case of resource caching, the WSRP consumer facilitates caching of the content/resource generated by the serveResource call of a portlet.

The WSRP Consumer implementation in OpenPortal WSRP version 2.0 Beta provides support for both markup and resource caching. Both markup and resource caching support expiration as well as validation caching, as mentioned in the WSRP version 2.0 specification. The caching feature is available for authenticated users only. Hence to test the caching functionality, make sure you are logged in using the Portlet Container driver sign-in link.

In the case of markup caching, the content is cached by the WSRP Consumer. To demonstrate the WSRP markup caching functionality we will use the Markup Cache Portlet, MarkupCachePortlet.war.

MarkupCachePortlet uses expiration caching and can be modified to add validation caching. The portlet defines expiration time as 120 seconds in portlet.xml. This portlet generates markup that contains the current date-time string. The generated content is cached for the expiration time (for example, 120 seconds) specified in portlet.xml.

Therefore, for any logged-in user, the markup (the date-time string) should not be changed by clicking the browser Refresh button or interacting with other portlets on the page for 120 seconds after the last execution of render. But, after clicking the render or action URL, the portlet should show a new date-time string.

Figure 8: Date-time string in MarkupCachePortlet Click the image to enlarge it.

In the case of resource caching, the content cached by the browser and consumer cache has no data caching at its end. In other words, the WSRP consumer sets the appropriate HTTP headers provided by the producer to enable the browser to cache the content. To demonstrate the WSRP resource caching functionality we will use the Resource Cache Portlet, ResourceCachePortlet.war.

ResourceCachePortlet is the same as the InvoiceAjaxPortlet mentioned above. The only change ResourceCachePortlet provides over InvoiceAjaxPortlet is the addition of an expiration cache entry in portlet.xml. Because resource caching is implemented using the browser caching feature, you need to test the snoop HTTP request to see how it works. One way to achieve this is by using the Live HTTP Header Firefox plug-in. Here are the steps to see it working:

1. Download and install the Live HTTP Header Firefox plug-in.
2. Using the Firefox browser, log in to the portlet driver and deploy ResourceCachePortlet.
3. Create a WSRP channel for ResourceCachePortlet.
4. Go to the WSRP tab and see if ResourceCachePortlet is there. Do not select any invoice at this moment.
5. Select Live HTTP Header plug-in using the browser's Tools menu option.
6. Select any invoice, for example, 439089 from the invoice drop-down.
7. View the Live HTTP Header plug-in window. You can see the HTTP resource request entry there. This means the browser is sending a resource request to the server. Clear this data.
8. Repeat steps 6 and 7 for invoice 439090. The Live HTTP Header plug-in window will again show you some data.
9. Repeat Step 6. This time, you will find no request entry in the Live HTTP Header plug-in window. This means the browser has a cache for invoice 439090, and it is serving data from its cache.

Figure 9: ResourceCachePortlet Click the image to enlarge it.

Now that you are familiar with the caching functionality associated with WSRP 2.0, let's introduce WSRP 2.0 leasing.

The WSRP 2.0 specification defines leasing as the concept of scheduled suspension and destruction of items such as Registration Handle and Portlet Handle. It is implemented in the OpenPortal WSRP 2.0 implementation by specifying a Lifetime parameter that denotes the valid period of the artifact in days, hours, and minutes. After the lease period expires, the artifact is made unavailable. This feature is particularly useful when the user wants the registration or the portlet handles to be valid only for a specific period. In such a scenario, this feature saves the trouble of the admin user manually deleting the artifacts from the registration.

OpenPortal WSRP version 2.0 Beta supports leasing for consumer registrations only. This is an optional parameter, so if this is not supplied, the consumer indicates that it does not want scheduled destruction.

When a WSRP Consumer is created for a version 2.0 producer, The WSRP Consumer Admin portlet provides an option to specify a parameter named Lifetime. It is specified as the combination of the number of days, hours, and minutes for which the registration is valid.

By default, during a WSRP Consumer creation the Lifetime Supplied checkbox is unchecked. When you check the box, the valid days, hours, and minutes text boxes appear. The values entered are used by the WSRP Consumer to set up a lease with the WSRP Producer.

Figure 10: Lifetime parameter in WSRP Consumer Admin Click the image to enlarge it.

The screenshot below shows the WSRP Consumer Admin portlet displaying the lease expiration time.

Figure 11: Lease expiration time in WSRP Consumer Admin Click the image to enlarge it.

A portlet window is created for the registered consumer that is leased. On navigating to the WSRP tab, if the system current time is after the termination time specified for the consumer registration, an error is thrown and the remote portlet is not rendered. If the system current time is before the scheduled termination time, the remote portlet is rendered correctly.

For out-of-band registrations, where the registration handles are created by the producer, the Lifetime parameter can be specified while creating a consumer registration for a producer. This is done from the Producer Admin portlet.

Figure 12: Lifetime parameter in WSRP Producer Admin Click the image to enlarge it.

• Open-source portal-related projects
  • Open Portal
  • Portlet Repository
  • Portlet Container
  • WSRP
  • JavaServerFaces Portlet Bridge
  • NetBeans Portal Pack
• Sun Java System Portal Server
  • Main Page
  • Developer Home
• Java Application Platform SDK
  • Update 7
• Blogs and community wiki
  • The Portal Post
  • The Aquarium
  • Community Wiki
• Sun developer services
  • Support
  • Training and certification
• Related articles
  • OpenPortal WSRP introduction
  • Portlet Container 2.0 Update 1
  • Portlet Container 2.1
  • Article on JSF Portlet Bridge