<?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>
To consume the WSRP portlets exposed by a remote producer, GateIn's WSRP consumer needs to know how to access that remote producer. One 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.
As a way to test the WSRP producer service and to check that the portlets that you want to expose remotely are correctly published via WSRP, two default consumers selfv1 and selfv2 have been configured to consume the portlets exposed by GateIn's WSRP 1 and WSRP 2 producer, respectively.
Configuring a remote producer using the configuration portlet
Let's work through the steps of defining access to a remote producer using the configuration portlet so that its portlets can be consumed within GateIn. 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. Please see this GateIn's wiki page for more details.
/!\ Check if this is still needed
GateIn provides a portlet to configure access (among other functions) to remote WSRP Producers graphically. Starting with 3.2, the WSRP configuration portlet is installed by default. You can find it at http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfigurationp&username=root&password=gtn
You should see a screen similar to:
This screen presents all the configured Consumers 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. 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 netunity. Type "netunity" 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 300 seconds, leave the default timeout value for web services (WS) operations and enter the WSDL URL http://www.netunitysoftware.com/wsrp2interop/WsrpProducer.asmx?Operation=WSDL&WsrpVersion=Two for the producer in the text field and press the "Refresh & Save" button:
This will retrieve the service description associated with the Producer which WSRP interface 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, requested three registration properties and that we are missing values for these properties:
This particular producer requests simple Yes or No values for the three registration properties. Entering No, Yes and No (in that order) for the values and then pressing the "Refresh & Save" button should result in:
At this point, there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Sometimes, the possible values will be indicated in the registration property description but this is not always the case. Please refer to the specific Producer's documentation for more details.
If we had been dealing with a producer which required registration but didn't require any registration properties, as is the case for the selfv2 consumer (the consumer that accesses the portlets made remotely available by GateIn's producer via WSRP 2), we'd have seen something similar to the screenshot below, after pressing the "Refresh & Save" button:
Configuring access to remote producers via XML
While we recommend you use the WSRP Configuration portlet to configure Consumers, we provide an alternative way to configure consumers by adding an XML file called wsrp-consumers-config.xml in the $JBOSS_HOME/standalone/configuration/gatein/wsrp directory.
An XML Schema defining which elements are available to configure Consumers via XML can be found in
$JBOSS_HOME/modules/org/gatein/wsrp/main/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_1.xsd
It is important to note that 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.
Required configuration information
Let's now 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. This is accomplished via the mandatory id attribute of the <wsrp-producer> element.
GateIn also needs to learn 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.
Optional configuration
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 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) 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, GateIn 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, we recommend 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 forever on the service that doesn't 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.
To use WS-Security-secured interactions with the producer, you will need to set the use-wss attribute of the <wsrp-producer> element to true. This attribute is optional and defaults to false if no value is provided. For more details on how to use WS-Security, please refer to Securing WSRP.
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.
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. Since GateIn can generate the mandatory information for you, 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 via <property> elements. See the example below for more details. Additionally, you can override the default consumer name automatically provided by GateIn via the <consumer-name> element. If you choose to provide a consumer name, please remember that this should uniquely identify your consumer.
Examples
Here is the configuration of the selfv1 and selfv2 consumers as found in:
-
{{$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml}}with a cache expiring every 500 seconds and with a 50 second timeout for web service operations.
This file contains the default configuration and you shouldn't need to edit it. If you want to make modifications to it, we recommend that you follow the procedure detailed in consumer_gui.
Here is an example of 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>
Adding remote portlets to categories
If we 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 available to be used. For example, regular portlets 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:
Adding remote portlets to pages
Since remote portlets can be manipulated just like regular portlets, you can add them to pages just like you would do for a regular portlet. Please refer to the appropriate section of the documentation for how to do so.
However, it is possible to also add a remote portlet to a pages.xml configuration file. This is accomplished using the <wsrp> element instead of the <portlet> element in your 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. For more details on pages.xml, please refer to Portal Navigation Configuration.
The format for such a reference to a remote portlet is as follows: first, the identifier of the consumer that accesses the remote producer publishing the remote portlet, then a separator (currently a period (.)) and finally the portlet handle for that portlet, which is a string provided by the producer to identify the portlet.
Since there currently is no easy way to determine the correct portlet handle, we recommend that you use the graphical user interface to add remote portlets to pages instead of using pages.xml.
For remote portlets published by GateIn's WSRP producer, the portlet handles are, at the time of this writing, following the /<portlet application name>.<portlet name> format.
Example
In the following example, we define 2 portlets for a page named Test in the pages.xml configuration file. They are actually references to the same portlet, albeit one accessed locally and the other one accessing it via the selfv2 consumer which consumes GateIn's WSRP producer. You can see that the first one 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 GateIn's 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>