Chapter 9. Web Services for Remote Portlets (WSRP)
Prev |  | Next

## Chapter 9. Web Services for Remote Portlets (WSRP)

### Julien Viet

`<julien@jboss.org>`

### Chris Laprun

`<chris.laprun@jboss.com>`

## 9.1. Introduction

The Web Services for Remote Portlets specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and on the concrete proposals made to the committee.

Scenarios that motivate WSRP functionality include:

- Content hosts, such as portal servers, providing Portlets as presentation-oriented web services that can be used by aggregation engines.
- Aggregating frameworks, including portal servers, consuming presentation-oriented web services offered by content providers and integrating them into the framework.

More information on WSRP can be found on the official website for WSRP. We suggest reading the primer for a good, albeit technical, overview of WSRP.

## 9.2. Deploying JBoss Portal's WSRP services

JBoss Portal provides a base level support of the WSRP 1.0 standard and offers both consumer and producer services. WSRP support is provided by the portal-wsrp.sar service archive, included in the main jboss-portal.sar service archive.

If you've obtained the source distribution of JBoss Portal, you need to build and deploy the WSRP service separately. Please follow the instructions on how to install JBoss Portal from the sources. Once this is done, navigate to JBOSS_PORTAL_HOME_DIRECTORY/wsrp and type:

    build deploy

At the end of the build process, portal-wsrp.sar is copied to JBOSS_HOME/server/default/deploy.

### Note

WSRP is built upon the JBoss WS web service stack. There is a known issue with the version 1.0.0.GA of JBoss WS bundled with JBoss Application Server 4.0.4.GA, issue which prevents the complete deployment of JBoss Portal's WSRP service if the user is not online or behind a firewall/proxy. This has been addressed in version 1.0.2.GA of JBoss WS. Please follow the instructions on how to upgrade JBoss WS as found on JBoss Portal's wiki.

## 9.3. Making a portlet remotable

JBoss Portal does not, by default, expose local portlets for consumption by remote WSRP consumers. In order to make a portlet remotely available, a jboss-portlet.xml deployment descriptor for that portlet must be added to the WEB-INF folder of the web application containing the portlet and must be similar to the example below:

    <?xml version="1.0" encoding="UTF-8"?>
    <portlet>
       <portlet-name>BasicPortlet</portlet-name>
       <remotable>true</remotable>
    </portlet>

Here, the portlet named "BasicPortlet" is specified as being remotable. The "remotable" element is optional.

It is also possible to specify that all the portlets declared within a given jboss-portlet.xml file have a specific "remotable" status by default. Usually, this feature will be used to remotely expose several portlets without having to specify the status for all the declared portlets. Let's look at an example:

    <portlet-app>
       <remotable>true</remotable>
       <portlet>
          <portlet-name>RemotelyExposedPortlet</portlet-name>
          ...
       </portlet>
       <portlet>
          <portlet-name>NotRemotelyExposedPortlet</portlet-name>
          <remotable>false</remotable>
          ...
       </portlet>
    </portlet-app>

In the example above, we defined two portlets with a default "remotable" status set to true. This means that all portlets defined in this descriptor are, by default, exposed remotely by JBoss Portal's WSRP producer. Note, however, that it is possible to override the default behavior by adding a remotable element to a portlet description. In that case, the "remotable" status defined by the portlet takes precedence over the default. In the example above, the RemotelyExposedPortlet inherits the "remotable" status defined by default since it does not specify a remotable element in its description. The NotRemotelyExposedPortlet, however, overrides the default behavior and is not remotely exposed. Note that in the absence of a top-level remotable element, portlets are NOT remotely exposed.

## 9.4. Accessing JBoss Portal's WSRP Producer from a remote Consumer

WSRP Consumers vary a lot as far as how they are configured. Most of them require that you either specify the URL for the Producer's WSDL definition or the URLs for the individual endpoints.

JBoss Portal's Producer is automatically set up when you deploy a portal instance. Assuming you're running a default configuration (i.e. you haven't changed the server's port number), you can access the WSDL file at `http://localhost:8080/portal-wsrp/MarkupService?wsdl`. You can acces the endpoint URLs are:

- http://localhost:8080/portal-wsrp/ServiceDescriptionService
- http://localhost:8080/portal-wsrp/MarkupService
- http://localhost:8080/portal-wsrp/RegistrationService
- http://localhost:8080/portal-wsrp/PortletManagementService

## 9.5. Consuming remote WSRP portlets in JBoss Portal

### 9.5.1. Overview

To be able to consume WSRP portlets from a remote producer, JBoss Portal's WSRP consumer needs to know how to access the remote producer. This is done via -wsrp.xml descriptors that provide JBoss Portal's consumer information about which remote producers to access and with which configuration. These files can be dropped in the deploy directory of the JBoss application server or nested in .sar files for examples. It is possible to configure access to several different producers within a single -wsrp.xml file or use one file per producer.

JBoss Portal's producer exposes its information to the Portal itself as a default consumer with the identifier self. That means that all the remotable portlets are also exposed as remote portlets in the portal. The portal-wsrp.sar file contains the file default-wsrp.xml that contains this default producer. This file can be edited or removed if needed.

Once a remote producer has been configured in a -wsrp.xml file, it becomes available in the list of portlet provider in the Management portlet on the Admin page of JBoss Portal. You can then examine the list of portlets that are exposed by this producer and configure the portlets just like you would for local portlets.

### Note

As of 2.4, the optional Portlet Management interface of WSRP is NOT supported. It is therefore not possible to clone and configure portlets on the consumer side. This will be supported in 2.6.

Let's see how it works step by step. Let's create a public-bea-wsrp.xml file as follows:

    <deployments>
       <deployment>
          <wsrp-producer>
             <producer-id>bea</producer-id>
             <expiration-cache>120</expiration-cache>
             <endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
             <registration-data>
                <consumer-name>JBoss Portal 2.4 Test</consumer-name>
                <property>
                   <name>registration/consumerRole</name>
                   <lang>en</lang>
                   <value>public</value>
                </property>
             </registration-data>
          </wsrp-producer>
       </deployment>
    </deployments>

This producer descriptor gives access to BEA's public WSRP producer. We will look at the details of the different elements later. Note for now the producer-id element with a "bea" value. Put this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed).

Let's now look at the Admin page and the management portlet. Click on the "Portlets" link at the top to manage the portlets. Once this is done, look at the list of available portlet providers. If all went well, you should see something similar to this:

We have 3 available portlet providers: local, self and bea. The "local" portlet provider exposes all the portlets deployed in this particular instance of Portal. The "self" provider is the default WSRP consumer bundled with Portal that consumes the portlets exposed by the default WSRP producer. The "bea" provider corresponds to BEA's public producer we just configured. Select it and click on "Change portlet provider". You should now see something similar to:

From there on out, you should be able to configure the portlet just as any other, baring the restriction that the WSRP Portlet Management interface is not yet supported in 2.4. If everything went well, you created an instance of the portlet and assigned it to a window in a page. If you go to that page, you should see something similar to below for this portlet:

### 9.5.2. Required configuration information

Let's look at which information needs to be provided to configure access to a remote producer.

First, we need to provide an identifier for the producer we are configuring so that we can refer to it afterwards via the <producer-id> element.

JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the web services and perform the WSRP invocations. Two options are currently provided to inform JBoss Portal of how to connect to the remote web service, both by providing the required information via children elements:

- We can provide the URLs for each of the different WSRP interfaces offered by the remote producer via the <endpoint-config> element and its <service-description-url>, <markup-url>, <registration-url> and <portlet-management-url> children. These URLs are producer-specific so you will need to refer to your producer documentation or WSDL file to determine the appropriate values.
- Alternatively, and this is the easiest way to configure your producer, we can provide a URL pointing to the WSDL description of the WSRP web services offered by the producer via <endpoint-wsdl-url>. JBoss Portal will then heuristically determine from the information contained in the WSDL file how to connect appropriately to the remote WSRP services.

  ### Note

  It is important to note that, when using this method, JBoss Portal will try to match a port name to an interface based solely on the provided name. There are no standard names for these ports so it is possible (though rare) that this matching process fails. In this case, you should look at the WSDL file and provide the endpoint URLs manually, as per the previous method.

Both <producer-id> and either <endpoint-config> or <endpoint-wsdl-url> are required elements for a functional remote producer configuration.

### 9.5.3. Optional configuration

It is also possible to provide addtional configuration, which, in some cases, might be important to establish a proper connection to the remote producer.

One such optional configuration is caching. To prevent useless roundtrips between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets). Such information is refreshed periodically. The rate at which the information is refreshed is defined by the <expiration-cache> element which specifies the refreshing period in seconds.

Additionally, some producers require consumers to register with them before authorizing them to access their offered portlets. JBoss Portal currently only supports a very basic subset of in-band registration and it is thus possible to provide required registration information in the producer configuration so that the Portal consumer can register with the remote producer when required.

### Note

At this time, though, only simple String properties are supported and it is not possible to configure complex registration data.

Registration configuration is done via the <registration-datat> element. We need to provide a consumer name (via the <consumer-name> element) for our consumer and then provide a list of values for the registration properties required by the remote producer via <property> elements. See the example below for more details.

### 9.5.4. Examples

Here is an example of a WSRP descriptor with a 2 minutes caching time and manual definition of the endpoint URLs:

                   <?xml version="1.0" encoding="UTF-8"?>
                   <deployments>
                      <deployment>
                         <wsrp-producer>
                            <producer-id>MyProducer</producer-id>
                            <expiration-cache>120</expiration-cache>
                            <endpoint-config>
                               <service-description-url>http://www.someproducer.com/portal-wsrp/ServiceDescriptionService</service-description-url>
                               <markup-url>http://www.someproducer.com/portal-wsrp/MarkupService</markup-url>
                               <registration-url>http://www.someproducer.com/portal-wsrp/RegistrationService</registration-url>
                               <portlet-management-url>http://www.someproducer.com/portal-wsrp/PortletManagementService</portlet-management-url>
                            </endpoint-config>
                         </wsrp-producer>
                      <deployment>
                   </deployments>

Here is an example of a WSRP descriptor with endpoint definition via remote WSDL file, registration data and cache expiring every minute:

                      <?xml version="1.0" encoding="UTF-8"?>
                      <deployments>
                         <deployment>
                            <wsrp-producer>
                               <producer-id>AnotherProducer</producer-id>
                               <expiration-cache>60</expiration-cache>
                               <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url>
                               <registration-data>
                                  <consumer-name>JBoss Portal 2.4 Test</consumer-name>
                                  <property>
                                     <name>property name</name>
                                     <lang>en</lang>
                                     <value>property value</value>
                                  </property>
                               </registration-data>
                            </wsrp-producer>
                         <deployment>
                      </deployments>

Prev | Up | Next
Chapter 8. Clustering Configuration | Home | Chapter 10. Security