Chapter 31. Using Remote WSRP Portlets
To be able to consume WSRP portlets exposed by a remote producer, the portal's WSRP consumer must know how to access that remote producer. You can configure access to a remote producer using the provided configuration portlet. Alternatively, it is also possible to configure access to remote producers using an XML descriptor, though it is recommended (and easier) to do so via the configuration portlet.
Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages.
31.1. Configuring a Remote Producer using the Configuration Portlet
This section will cover the steps of defining access to a remote producer using the configuration portlet so that its portlets can be consumed within the portal. We will configure access to NetUnity's public WSRP producer.
Some WSRP producers do not support chunked encoding that is activated by default by JBoss WS. If your producer does not support chunked encoding, your consumer will not be able to properly connect to the producer. This will manifest itself with the following error:
Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable. See http://community.jboss.org/wiki/Workaroundwhenchunkedencodingisnotsupported for more details.
The portal provides a portlet to configure access (among other functions) to remote WSRP Producers graphically. Starting with 6.1.0, the WSRP configuration portlet is installed by default. You can find it at http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&username=root&password=gtn
You should see a screen similar to:
A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. 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.
31.2. Access Remote Producers
31.2.1. Configuring Access to Remote Producers using XML
While it is recommended to use the WSRP Configuration portlet to configure Consumers, the component provides an alternative way to configure consumers by adding an XML file called
wsrp-consumers-config.xml in the JPP_DIST/standalone/configuration/gatein/wsrp/ directory.
Note
An XML Schema defining which elements are available to configure Consumers through XML can be found in
JPP_DIST/modules/org/gatein/wsrp/main/wsrp-integration-api-2.2.2.Final.jar/xsd/gatein_wsrp_consumer_1_0.xsd
Important
Once the XML configuration file for consumers has been read upon the WSRP service first start, the associated information is put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore the content of the XML configuration file.
This section covers what information is required to configure access to a remote producer.
Provide an identifier for the producer you are configuring so that you can reference it afterwards using the mandatory
id attribute of the <wsrp-producer> element.
The portal also must know about the remote producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. This is accomplished by specifying the URL for the WSDL description for the remote WSRP service, using the <endpoint-wsdl-url> element.
Both the
id attribute and <endpoint-wsdl-url> elements are required for a functional remote producer configuration.
31.2.2. Additional Configuration to Remote Producers
It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer.
One such optional configuration concerns caching. To prevent useless round-trips 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) for a given duration. The rate at which the information is refreshed is defined by the
expiration-cache attribute of the <wsrp-producer> element which specifies the refreshing period in seconds. For example, providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been somehow accessed. If no value is provided, the portal will always access the remote producer regardless of whether the remote information has changed or not. Since, in most instances, the information provided by the producer does not change often, it is recommended that you use this caching facility to minimize bandwidth usage.
It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, waiting on the service that does not answer. Use the
ws-timeout attribute of the <wsrp-producer> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out and giving up.
Additionally, some producers require consumers to register with them before authorizing them to access their offered portlets. If you know that information beforehand, you can provide the required registration information in the producer configuration so that the 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. This should, however, be sufficient for most cases.
Registration configuration is done via the
<registration-data> element. If the remote producer does not require any registration properties, you only need to provide an empty <registration-data> element. Values for the registration properties required by the remote producer can be provided through <property> elements. Additionally, you can override the default consumer name automatically provided by the portal through the <consumer-name> element. If you choose to provide a consumer name, remember that this must uniquely identify your consumer.
31.3. Configuration Examples
31.3.1. Consumer Configuration
The
extension-component-2.2.2.Final.jar extension and the selfv1 and selfv2 files are fictitious files used to demonstrate the configuration required for Consumers. These files are not present in the default configuration file wsrp-consumers-config.xml.
Example 31.1. selfv1 and selfv2 defined in wsrp-consumers-config.xml
To correctly configure the selfv1 and selfv2 consumers, declare the configuration in the
JPP_HOME/gatein/extensions/gatein-wsrp-integration.ear/lib/extension-component-2.2.2.Final.jar/conf/wsrp-consumers-config.xml file.
For example, this file shows the configuration for
selfv1 and selfv2 consumers consisting of a cache, expiring every 500 seconds with a 50 second timeout for web service operations. Use this example as an indication of the configuration required.
<?xml version='1.0' encoding='UTF-8' ?> <deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0 http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> <deployment> <wsrp-producer id="selfv1" expiration-cache="500" ws-timeout="50000"> <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> <deployment> <wsrp-producer id="selfv2" expiration-cache="500" ws-timeout="50000"> <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> </deployments>
When customizing a file of this type, it is recommended to make a copy of the file as a roll-back point.
31.3.2. Example 2: Registration Data and Cache Expiry
Here is the configuration of the
selfv1 and selfv2 consumers as found in JPP_HOME/gatein/extensions/gatein-wsrp-integration.ear/lib/extension-component-2.2.2.Final.jar/conf/wsrp-consumers-config.xml with a cache expiring every 500 seconds and with a 50 second timeout for web service operations.
Note
This file contains the default configuration suitable for most installations. If changes are required, it is recommended a copy of the file is taken before modifying.
Example 31.2. Registration Data and Cache Expiry Example
This example shows a WSRP descriptor with registration data and cache expiring every minute:
<?xml version='1.0' encoding='UTF-8' ?> <deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0 http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> <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>
31.4. Adding remote portlets to categories
If you go to the Application Registry and examine the available portlets by clicking on the Portlet link, you will now be able to see remote portlets if you click on the REMOTE tab in the left column:
These portlets are, of course, available to be used such as regular portlets: they can be used in categories and added to pages. If you use the Import Applications functionality, they will also be automatically imported in categories based on the keywords they define.
More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by selecting 
wsrp in the Application Type drop-down menu:
31.5. Adding remote portlets to pages
Since remote portlets can be manipulated like regular portlets, you can add them to pages like a regular portlet.
It is possible to add a remote portlet to a
pages.xml configuration file. This is accomplished using the <wsrp> element instead of the <portlet> element in the pages.xml document.
While <portlet> references a local portlet using the name of the application in which the portlet is contained and the portlet name itself to identify which portlet to use, <wsrp> references a remote portlet using a combination of the consumer identifier for the producer publishing the portlet and the portlet handle identifying the portlet within the context of the producer.
The format for such a reference to a remote portlet takes the following format:
- The identifier of the consumer that accesses the remote producer publishing the remote portlet.
- A separator, currently a period (
.). - The portlet handle for that portlet, which is a string provided by the producer to identify the portlet.
Since there is currently is no easy way to determine the correct portlet handle, it is recommended that the graphical user interface is used to add remote portlets to pages instead of using
pages.xml.
Note
For remote portlets published by the portal's WSRP producer, the portlet handles follow the
/<portlet application name>.<portlet name> format.
31.5.1. Example: Adding Portlets
Example 31.3. Adding Portlets
Two portlets are defined for a page named
Test in the pages.xml configuration. They reference the same portlet: one accessed locally and the other accessed through the selfv2 consumer, which consumes the portal WSRP producer.
The first portlet is local (the
<portlet-application> with the 'Added locally' title) and follows the usual declaration. The second portlet (the one with the 'Added from selfv2 consumer' title) comes from the selfv2 consumer and uses the <wsrp> element instead of <portlet> element and follows the format for portlets coming from the portal WSRP producer.
<page>
<name>Test</name>
...
<portlet-application>
<portlet>
<application-ref>richFacesPortlet</application-ref>
<portlet-ref>richFacesPortlet</portlet-ref>
</portlet>
<title>Added locally</title>
...
</portlet-application>
<portlet-application>
<wsrp>selfv2./richFacesPortlet.richFacesPortlet</wsrp>
<title>Added from selfv2 consumer</title>
...
</portlet-application>
</page>