GateIn provides a portlet to configure access (among other functions) to remote WSRP Producers graphically. However, it is not installed by default, so the first thing you need to do is to install the WSRP configuration portlet using the Application Registry.

Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default installment, you can just go to 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. Also, note that a Consumer can be marked as required refreshing, 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, it is required to validate the information again.

Next, you need create a new Consumer called oracle. Type "oracle" in the "Create a consumer named:" field, then click "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 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 this case, querying the service description will allow us to learn that the Producer requires registration but did not request any registration property:

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

Now, assuming that the producer required a value for an email registration property, GateIn's WSRP consumer would have informed you that you were missing some information:

If you entered "example@example.com" as the value for the registration property and press "Save & Refresh" once more, you would have seen something similar to:

While it is recommended that you use the WSRP Configuration portlet to configure Consumers, eXo Platform provides an alternative way to configure consumers by editing the .xml file located at $GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml.

<?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="self" expiration-cache="300" ws-timeout="30000">
         <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url>
         <registration-data>
            <property>
               <name>email</name>
               <lang>en</lang>
               <value>example@example.com</value>
            </property>
         </registration-data>
      </wsrp-producer>
   </deployment>
   <deployment>
      <wsrp-producer id="oracle" expiration-cache="300">
         <endpoint-wsdl-url>http://portalstandards.oracle.com/portletapp/portlets?WSDL</endpoint-wsdl-url>
         <registration-data/>
      </wsrp-producer>
   </deployment>
</deployments>

The file as shown above specifies access to two producers: self, which consumes GateIn's own WSRP producer albeit in a version that assumes that the producer requires a value for an email registration property, and oracle, which consumes Oracle's public producer, both in configurations as shown in the walk-through above.

We will look at the details of the meaning of elements later on.

If we go back to the Application Registry and examine the available portlets by clicking the Portlet link, you will now be able to see the remote portlets after clicking the REMOTE tab in the left column:

These portlets are available to be used. For example, the regular portlets can be used in categories and added to pages. If you use the Import Applications functionality, they will also be automatically imported into categories based on the keywords they define.

More specifically, if you want to add the WSRP portlet to a category, you can access these portlets by selecting wsrp in the Application Type drop-down menu:

Now, look at which information needs to be provided to configure access to a remote producer.

First, you need to provide an identifier for the producer we are configuring so that you 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 end-points 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.

It is also possible to provide addtional configuration. In some cases, the additional configuration 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. It is recommended that you use this caching facility to minimize the bandwidth usage.

It is also possible to define a timeout after which the WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, waiting forever 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.

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 the <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 select to provide a consumer name, please remember that this should uniquely identify your consumer.

Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties.

There might also be cases where you just want to update the registration information because it has changed. For example, the producer required you to provide a valid email and the previously email address is not valid anymore and needs to be updated.

It is therefore sometimes necessary to modify the registration that concretizes the service agreement between a consumer and a producer. Let's take the example of the producer requiring an email you configured in Section 7.6.2.1, “Using the configuration portlet”. If you recall, the producer was requiring registration and required a value to be provided for the email property.

Suppose that you want to update the email address that you provided to the remote producer. To do so, you need to tell the producer that our registration data have been modified. Let's see how to do this. In case that you want to configure access to the producer as previously described, please go to the configuration screen for the self producer and modify the value of email to foo@example.com instead ofexample@example.com:

Now, click "Update properties" to save the change. A "Modify registration" button should now appear to let you send the new data to the remote producer:

Click this new button and, if everything went well and your updated registration has been accepted by the remote producer, you should see something similar to:

It can also happen that a producer administrator decided to change its requirement for registered consumers. In this case, invoking operations on the producer will be failed with an OperationFailedFault. GateIn will attempt to help you in this situation. Let's walk through an example using the self producer. Let's assume that registration is requiring a valid value for an email registration property (as we have seen so far). If you go to the configuration screen for this producer, you should see:

Now suppose that the administrator of the producer also requires a value to be provided for a name registration property. We will actually see how to perform this operation in GateIn when we examine how to configure GateIn's producer in Section 7.8, “Configure GateIn's WSRP Producer”. Operations with this producer will now be failed. If you suspect that a registration modification is required, you should go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh & Save":

As you can see, the configuration screen now shows the currently held registration information and the expected information from the producer. Enter a value for the name property and then click "Modify registration". If all went on well and the producer accepted your new registration data, you should see something similar to:

Registration handling behavior can be customized by users to suit their Producer needs. This is accomplished by providing an implementation of the RegistrationPolicy interface. This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs.

While the default registration policy provides the default behavior for most registration-related aspects, there is still one aspect that requires configuration: whether a given value for a registration property is acceptable by the WSRP Producer. This is accomplished by plugging a RegistrationPropertyValidator in the default registration policy. This allows you to define their own validation mechanism.

Please refer to the Javadoc™ for org.jboss.portal.registration.RegistrationPolicy and org.jboss.portal.Registration.policies.RegistrationPropertyValidator for more details on what is expected of each method.

Defining a registration policy is required for the producer to be correctly configured. This is accomplished by specifying the qualified class name of the registration policy. Since we anticipate that most users will use the default registration policy, it is possible to provide the class name of your custom property validator instead of customizing the default registration policy behavior. Note that property validators are only used by the default policy.