JBoss.orgCommunity Documentation

Chapter 7. Web Services for Remote Portlets (WSRP)

7.1. Introduction
7.2. Level of support in GateIn 3.2
7.3. Deploy GateIn's WSRP services
7.3.1. WSRP use when running GateIn on a non-default port or hostname
7.3.2. Considerations to use WSRP with SSL
7.4. Make a portlet remotable
7.5. Consume GateIn's WSRP portlets from a remote Consumer
7.6. Consume remote WSRP portlets in GateIn
7.6.1. Overview
7.6.2. Configure a remote producer walk-through
7.6.3. Configure access to remote producers via XML
7.6.4. Examples
7.7. Consumers maintenance
7.7.1. Modify a currently held registration
7.7.2. Consumer operations
7.7.3. Import and export portlets
7.7.4. Erase local registration data
7.8. Configure GateIn's WSRP Producer
7.8.1. Overview
7.8.2. Default configuration
7.8.3. Registration configuration
7.8.4. WSRP validation mode

The Web Services for Remote Portlets specification defines a web service interface for accessing and interacting with 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 motivating the WSRP functionality include:

More information on WSRP can be found on the official website for WSRP. It is suggested that you read the primer for a good, and albeit technical overview of WSRP.

The WSRP Technical Committee defined WSRP Use Profiles to help with the WSRP interoperability. You can refer to terms defined in that document in this section.

GateIn provides a Simple level of support for our WSRP Producer except that out-of-band registration is not currently handled. eXo Platform supports the in-band registration and persistent local state (which are defined at the Complex level).

On the Consumer side, GateIn provides a Medium level of support for WSRP, except that eXo Platform only handles the HTML markup (as GateIn itself does not handle other markup types). eXo Platform supports the explicit portlet cloning and provides the full support the PortletManagement interface.

As far as caching goes, eXo Platform has Level 1 Producer and Consumer. eXo Platform supports the Cookie handling properly on the Consumer and our Producer that requires initialization of cookies. eXo Platform does not support custom window states or modes. However, eXo Platform supports CSS on both the Producer (though it's more a function of the portlets than inherent Producer capability) and Consumer.

While eXo Platform provides a complete implementation of WSRP 1.0, you need to go through the Conformance statements and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical Committee and Community at large).


As of version 3.2 of GateIn, WSRP is only activated and supported when GateIn is deployed on the JBoss Application Server.

GateIn provides a complete support of WSRP 1.0 standard interfaces and offers services to both consumers and producers. The WSRP support is provided by the following files, assuming $GATEIN_HOME is where GateIn has been installed, $WSRP_VERSION (at the time of the writing, it was 1.1.0-GA) is the version of the WSRP component and $PORTAL_VERSION (at the time of the writing, it was 3.0.1-GA) is the current GateIn version:

If you are not going to use WSRP in GateIn, you can remove $GATEIN_HOME/lib/gatein.portal.component.wsrp-$PORTAL_VERSION.jar from your GateIn distribution to easily deactivate the WSRP support. Of course, if you want to trim your installation, you can also remove all the files mentioned above.

JBoss WS (the web service stack that GateIn uses), you need to pay attention to details of updating the port and host name used in WSDL. See the JBoss WS user guide on that subject for more details.

Of course, if you have modified the host name and port on which your server runs, you will need to update the configuration for the consumer used to consume GateIn's 'self' producer. Please refer to the ??? to learn how to do so.

GateIn does not expose local portlets for consumption by remote WSRP consumers by default. To make a portlet remotely available, it must be made "remotable" by marking it as such in the associated portlet.xml. This is accomplished by using a specific org.gatein.pc.remotable container-runtime-option. Setting its value to true makes the portlet available for the remote consumption, while setting its value to false will not publish it remotely. As specifying the remotable status for a portlet is optional, you do not need to do anything if you do not need your portlet to be available remotely.

In the following example, the "BasicPortlet" portlet is specified as being remotable.

It is also possible to specify that all the portlets declared within a given portlet application to be remotable by default. This is done by specifying the container-runtime-option at the portlet-app element level. Individual portlets can override that value to not be remotely exposed. Let's look at an example:

In the example above, two portlets are defined. The org.gatein.pc.remotable container-runtime-option is set to true at the portlet-app level, meaning that all portlets defined in this particular portlet application are exposed remotely by GateIn's WSRP producer. Note, however, that it is possible to override the default behavior: specifying a value for the org.gatein.pc.remotable container-runtime-option at the portlet level will take precedence over the default. In the example above, the RemotelyExposedPortlet inherits the remotable status defined at the portlet-app level since it does not specify a value for the org.gatein.pc.remotable container-runtime-option. The NotRemotelyExposedPortlet, however, overrides the default behavior and is not remotely exposed. Note that in the absence of a top-level org.gatein.pc.remotable container-runtime-option value set totrue, portlets are not remotely exposed.

WSRP Consumers vary a lot as far as how they are configured. Most of them require you to specify the URL for the Producer's WSDL definition. Please refer to your Consumer's documentation for specific instructions. For instructions on how to do so in GateIn, please refer to ???.

GateIn's Producer is automatically set up when you deploy a portal instance with the WSRP service. You can access the WSDL file at http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl. If you wish to use only the WSRP 1 compliant version of the producer, please use the WSDL file found at http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl. The default hostname is localhost and the default port is 8080.

Let's work through the steps of defining access to a remote producer so that its portlets can be consumed within GateIn. You need to configure access to the Oracle's public WSRP producer. First, examine how to do so using the configuration portlet and then show how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet.

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.


The WSRP configuration did not use to be installed by default in previous versions of GateIn. We include here the legacy instructions on how to install this portlet in case you ever need to re-install it.

Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default install, you can just go to http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications functionality, the WSRP Configuration portlet will be automatically added to the Administration category.

Now that the portlet is added to a category, it can be added to a page and used. We recommend adding it to the same page as the Application Registry as operations relating to WSRP and adding portlets to categories are somewhat related as we will see. Go ahead and add the WSRP Configuration portlet to the page using the standard procedure.

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:


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.

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"
             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">
      <wsrp-producer id="self" expiration-cache="300" ws-timeout="30000">
      <wsrp-producer id="oracle" expiration-cache="300">

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.

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.

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.

Here is the configuration of the selfv1 and selfv2 consumers as found in $GATEIN_HOME/lib/wsrp-consumer-$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.

Here is an example of a WSRP descriptor with registration data and cache expiring every minute:

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, “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:


As of WSRP 1, it is rather difficult to ascertain what caused an OperationFailedFault as it is the generic exception returned by producers if something did not quite happen as expected during a method invocation. This means that OperationFailedFault can be caused by several different reasons, one of them being a request to modify the registration data. Please take a look at the log files to see if you can gather more information as to what happened. WSRP 2 introduces an exception that is specific to a request to modify registrations, thus reducing the ambiguity that currently exists.

Import and export are new functionalities added in WSRP 2. Exporting a portlet allows a consumer to get an opaque representation of the portlet which can then be use by the corresponding import operation to reconstitute it. It is mostly used in migration scenarios during batch operations. Since GateIn does not currently support automated migration of portal data, the functionality that we provide as part of WSRP 2 is necessarily less complete than it could be with full portal support.

The import/export implementation in GateIn 3.2 allows users to export portlets from a given consumer. These portlets can then be used to replace existing content on pages. This is accomplished by assiging previously exported portlets to replace the content displayed by windows on the portal's pages. Let us walk through an example to make things clearer.

Clicking the "Export" action for a given consumer will display the list of portlets currently made available by this specific consumer. An example of such a list is shown below:

Once portlets have been selected, they can be exported by clicking the "Export" button thus making them available for later import:

You can re-import the portlets directly by pressing the "Use for import" button or, on the Consumers list page, using the "Import" action for a given consumer. Let's assume that you used that second option and that you currently have several available sets of previously exported portlets to import from. After clicking the action link, you should see a screen similar to the one below:

As you can see this screen presents the list of available exports with available operations for each.

Once you have selected an export to import from, you will see a screen similar to the one below:

The screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. Next, you need to select the content of which window the imported portlet will replace. This process is done in three steps. Let's assume in this example that you have the following page called page1 and containing two windows called NetUnity WSRP 2 Interop - Cache Markup (remote) and /samples-remotecontroller-portlet.RemoteControl (remote) as shown below:

In this example, we want to replace the content of the /samples-remotecontroller-portlet.RemoteControl (remote) by the content of the /ajaxPortlet.JSFAJAXPortlet portlet that we previously exported. To do so, we will check the checkbox next to the /ajaxPortlet.JSFAJAXPortlet portlet name to indicate that we want to import its data and then select the page1 in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the one seen below:

Note that, at this point, we still need to select the window which content we want to replace before being able to complete the import operation. Let's select the /samples-remotecontroller-portlet.RemoteControl (remote) window, at which point the "Import" button will become enabled, indicating that we now have all the necessary data to perform the import. If all goes well, pressing that button should result in a screen similar to the one below:

If you now take a look at the page1 page, you should now see that the content /samples-remotecontroller-portlet.RemoteControl (remote) window has been replaced by the content of the /ajaxPortlet.JSFAJAXPortlet imported portlet and the window renamed appropriately:

The default producer configuration requires consumers to register with it before providing access to 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 producer also uses the default RegistrationPolicy paired with the default RegistrationPropertyValidator. You need to look into property validators in greater detail later in Section 7.8.3, “Registration configuration”. This allows you to customize how Portal's WSRP Producer decides whether a given registration property is valid or not.

GateIn provides a web interface to configure the producer's behavior. You can access it by clicking the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you should see with the default configuration:

As expected, you can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which RegistrationPolicy to use (and, if needed, which RegistrationPropertyValidator), along with required registration property description for which consumers must provide acceptable values to register successfully.

To require consumers to register with the Portal's producer before interacting with it, you need to configure the Portal's behavior with respect to registration. Registration is optional, as registration properties. The producer can require registration without passing any registration properties in case of the default configuration. Let's configure our producer starting with a blank state:

eXo Platform will allow unregistered consumers to see the list of offered portlets, so the first checkbox ("Access to full service description requires consumers to be registered") is unchecked. You will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display:

You can specify the fully-qualified name for your RegistrationPolicy and RegistrationPropertyValidator there. We will keep the default value. See Section, “Customization of Registration handling behavior” for more details. Let's add, however, a registration property called email. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose:

Press "Save" to record your modifications.


At this time, only String (xsd:string) properties are supported. If your application requires more complex properties, please let us know.


If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. We saw the consumer side of that process in Section, “Registration modification on producer error”.

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.