|By Manish Gupta, Nithya Subramanian, and Rajesh Thiagarajan, October 2008; updated January 2009|
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:
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:
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:
The WSRP Producer Admin portlet can be used for creating and managing WSRP producers. The default producer, SampleProducer, is disabled by default.
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.
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.
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.
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.
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.
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:
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:
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.
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.
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).
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:
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:
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.
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.
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.
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.
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:
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:
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
serveResourcecall. 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.
getResource() method call on the WSRP Producer that invokes the
serveResource() method on the portlet, and the content is served by the portlet.
serveResource()operation on the portlet via WSRP.
Here is a screenshot of the 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.
Here is a screenshot of the 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:
serveResourcecall 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
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.
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:
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.
The screenshot below shows the WSRP Consumer Admin portlet displaying the lease expiration time.
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.