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) that prevents the complete deployment of JBoss Portal's WSRP service if the user is not online or behind a firewall/proxy. For this reason, we recommend that you deploy Portal on JBoss Application Server 4.0.5.GA. Alternatively, you can also perform a manual upgrade of JBoss WS, in which case we recommend that you use JBoss WS version 1.2.1.GA (and later). Please follow the instructions on how to upgrade JBoss WS as found on JBoss Portal's wiki.

If you have modified the port number on which Portal runs, you will also need update the port information for WSRP as found on JBoss Portal's wiki.

It is possible to use WSRP over SSL for secure exchange of data. Please refer to the instructions on how to do so from JBoss Portal's wiki.

To be able to consume WSRP portlets exposed by a remote producer, JBoss Portal's WSRP consumer needs to know how to access that remote producer. One can configure access to a remote producer using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers.

Once a remote producer has been configured, it can be made available in the list of portlet providers 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.

JBoss Portal's default configuration exposes some of the sample portlets for remote consumption. As a way to test the WSRP service, a default consumer has been configured to consume these portlets. To make sure that the service indeed works, check that there is a portlet provider with the self identifier in the portlet providers list in the Management portlet of the Admin page. All local portlets marked as remotable are exposed as remote portlets via the self portlet provider so that you can check that they work as expected with WSRP. The portal-wsrp.sar file contains a WSRP Producer descriptor (default-wsrp.xml) that configures this default producer. This file can be edited or removed if needed.

Let's work through the steps of defining access to a remote producer so that its portlets can be consumed within JBoss Portal. We will configure access to BEA's public WSRP producer. We will first examine how to do so using an XML descriptor then see how the same can be accomplished using the configuration portlet.

<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" standalone="yes"?>
<deployments>
  <deployment>
    <wsrp-producer id="bea" expiration-cache="120">
      <endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
      <registration-data>
        <property>
          <name>registration/consumerRole</name>
          <lang>en</lang>
          <value>public</value>
      </registration-data>
    </wsrp-producer>
  </deployment>
</deployments>

12.6.2.2. Using the configuration portlet

As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers grahically. You can access it at http://{hostname}:{port}/portal/auth/portal/admin/WSRP or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went well, you should see something similar to this:

This screen presents all the configured producers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Deactivating it will remove it from the list of available portlet providers. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information.

Next, we create a new Consumer which we will call "bea". Type "bea" in the "Create a consumer named:" field then click on "Create consumer":

You should now see a form allowing you to enter/modify the information about the Consumer:

Set the cache expiration value to 120 seconds and check the "Use WSDL?" checkbox. The form should now morph to:

Enter the WSDL URL for the producer in the text field and press the "Refresh" button. This will retrieve the service description associated with the Producer which WSRP is described by the WSDL file found at the URL you just entered. In our case, querying the service description will allow us to learn that the Producer requires registration and that it expects a value for the registration property named "registration/consumerRole":

Note

At this point, there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Please refer to the specific Producer's documentation.

Enter "public" as the value for the registration property and press "Refresh" once more. You should now see something similar to:

The Consumer for the "bea" Producer should now be available as a portlet provider and is ready to be used.

12.6.2.3. Configuring access to a remote portlet

Let's now look at the Admin page and the Management portlet. Click on the "Portlet definitions" tab at the top. 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. As explained above, the "self" provider refers to 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". You should now see something similar to:

From there on out, you should be able to configure WSRP portlets just as any other. In particular, you can create an instance of one of the remote portlets offered by BEA's public producer just like you would create an instance of a local portlet and then assign it to a window in a page. If you go to that page, you should see something similar to below for this portlet:

A WSRP Producer descriptor is an XML file which name ends in -wsrp.xml and which can be dropped in the deploy directory of the JBoss application server or nested in .sar files. It is possible to configure access to several different producers within a single descriptor or use one file per producer, depending on your needs. The DTD for the WSRP Producer descriptor format can be found at portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd.

Here is the configuration of the "self" producer as found in default-wsrp.xml with a cache expiring every five minutes:

<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<deployments>
   <deployment>
      <wsrp-producer id="self" expiration-cache="300">
         <!--
         we need to use the individual endpoint configuration because the configuration via 
         wsdl forces an immediate attempt to access the web service description which is not
         available yet at this point of deployment
         -->
         <endpoint-config>
            <service-description-url>
              http://localhost:8080/portal-wsrp/ServiceDescriptionService
            </service-description-url>
            <markup-url>http://localhost:8080/portal-wsrp/MarkupService</markup-url>
            <registration-url>
              http://localhost:8080/portal-wsrp/RegistrationService
            </registration-url>
            <portlet-management-url>
              http://localhost:8080/portal-wsrp/PortletManagementService
            </portlet-management-url>
         </endpoint-config>
         <registration-data/>
      </wsrp-producer>
   </deployment>
</deployments>
            

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

<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<deployments>
   <deployment>
      <wsrp-producer id="MyProducer" expiration-cache="120">
         <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:

<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<deployments>
   <deployment>
      <wsrp-producer id="AnotherProducer" expiration-cache="60">
         <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url>
         <registration-data>
            <property>
               <name>property name</name>
               <lang>en</lang>
               <value>property value</value>
            </property>
         </registration-data>
      </wsrp-producer>
   </deployment>
</deployments>

You can configure the behavior of Portal's WSRP Producer by editing the conf/config.xml file found in portal-wsrp.sar. Several aspects can be modified with respects to whether registration is required for consumers to access the Producer's services.

Let's look at the default configuration:

<!DOCTYPE producer-configuration PUBLIC 
          "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<producer-configuration>
   <registration-configuration fullServiceDescriptionRequiresRegistration="true">
      <registration-property-validator>
      org.jboss.portal.registration.policies.DefaultRegistrationPropertyValidator
      </registration-property-validator>
   </registration-configuration>
</producer-configuration>

The top element <producer-configuration> contains a single <registration-configuration> element that defines a fullServiceDescritpionRequiresRegistration attribute with the value "true". This configuration specifies that the WSRP producer requires registration to access its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The <registration-configuration> element contains a <registration-property-validator> element. We will look into property validators in greater detail later in Section 12.7.4, “Registration configuration”. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not.

Requiring registration is optional: if you don't need your producer to require consumer registration, the only thing you need to do is to provide an empty <producer-configuration> element in portal-wsrp.sar/conf/config.xml.

In order to require consumers to register with Portal's producer before interacting with it, you need to configure Portal's behavior with respect to registration. This is done via the <registration-configuration> element. This element is optional as previously noted. It can be empty if you don't require registration properties. You can also specify whether or not registration is required in order for consumers to access the Producer's full service description, as noted in our discussion of the default configuration, above. This is done via the fullServiceDescriptionRequiresRegistration attribute, which is optional. Acceptable values for this attribute are "true" or "false", defaulting to "false" in which case the Producer will always return the full service description, whether the consumer asking for it is registered or not.

Here is an example of a producer configurations requiring registration, barring consumers from accessing its complete service description until they are correctly registered and requires consumers to provide acceptable values for two String registration properties named "name1" and "name2" respectively. The registration service will use the com.example.portal.SomeCustomRegistrationPolicy class for its registration policy.

<!DOCTYPE producer-configuration PUBLIC
          "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>            
<producer-configuration>
  <registration-configuration fullServiceDescriptionRequiresRegistration="true">
    <registration-policy>com.example.portal.SomeCustomRegistrationPolicy</registration-policy>
    <registration-property-description>
      <name>name1</name>
      <type>xsd:string</type>
      <hint xml:lang="en" resourceName="resource.hint1">hint1</hint>
      <label xml:lang="en" resourceName="resource.label1">label1</label>
    </registration-property-description>
    <registration-property-description>
      <name>name2</name>
      <type>xsd:string</type>
      <hint xml:lang="en" resourceName="resource.hint2">hint2</hint>
      <label xml:lang="en" resourceName="resource.label2">label2</label>
    </registration-property-description>
  </registration-configuration>
</producer-configuration>