Chapter 28. Web Services for Remote Portlets

⁠Chapter 28. Web Services for Remote Portlets

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

Content hosts, such as portal servers, providing Portlets as presentation-oriented web services that can be used by aggregation engines.
Aggregating frameworks, including portal servers, consuming presentation-oriented web services offered by content providers and integrating them into the framework.

More information on WSRP can be found on the official website for WSRP. Further suggested reading is the primer for a good, albeit technical, overview of WSRP.

Report a bug

⁠28.1. WSRP Support

The WSRP Technical Committee defined WSRP Use Profiles to help with WSRP interoperability. See http://www.oasis-open.org/committees/download.php/3073 for more information. This section references terms defined in this document.

The portal provides a Simple level of support for the WSRP Producer except that out-of-band registration is not currently handled. In-band registration and persistent local state (which are defined at the Complex level) are supported.

On the Consumer side, the portal provides a Medium level of support for WSRP, except that the consumer only handles HTML markup (because the portal itself does not handle other markup types). The portal does support explicit portlet cloning and it fully supports the PortletManagement interface.

As far as caching goes, the component has a Level 1 Producer and Consumer. Cookie handling is supported properly on the Consumer and the Producer requires initialization of cookies (it has been found that it improves interoperability with some consumers). The component does not support custom window states or modes, because the portal does not. The component does, however, support CSS on both the Producer (though it is more a function of the portlets than inherent Producer capability) and Consumer.

While a complete implementation of WSRP 1.0 is provided, the community developers do need to review the Conformance statements declared at http://www.oasis-open.org/committees/download.php/6018, and perform more interoperability testing.

The portal supports WSRP 2.0 with a complete implementation of the mandatory features with the exception of support for lifetimes, and leasing support.

Note

As of version 6.1 of the portal, WSRP is only activated and supported using the portal deployed on Red Hat JBoss Enterprise Application Platform 6.

Report a bug

⁠28.2. Deploying Services

⁠28.2.1. Deploying Web Services for Remote Portlets services

The portal provides complete support for WSRP 1.0 and 2.0 standard interfaces, and offers both consumer and producer services. Starting with version 2.1.0-GA of the component, WSRP is packaged as a portal extension, and is contained in a package named JPP_HOME/gatein/extensions/gatein-wsrp-integration.ear .

The only files of interest from a user perspective are located in the JPP_HOME/standalone/configuration/gatein/wsrp directory.

gatein-wsse-consumer.xml, which allows you to configure WS-Security support for the consumer.
gatein-wsse-producer.xml which allows you to configure WS-Security support for the producer.

The extension itself is composed of the following components:

META-INF contains files necessary for EAR packaging.
The extension-component-6.1.0.jar, which contains the components needed to integrate the WSRP component into the portal. It also includes the default configuration files for the WSRP producer and the default WSRP consumers.
The extension-config-6.1.0.jar, which contains the configuration file needed by the GateIn extension mechanism to properly register this EAR as an extension.
The extension-war-6.1.0.war, which contains the configuration files needed by the portal extension mechanism to setup the WSRP service. It includes wsrp-configuration.xml which, configures options for the WSRPServiceIntegration component of the WSRP integration in the portal.
The file $RHJP_HOME/gatein/extensions/gatein-wsrp-integration.ear/extension-war.war/WEB-INF/conf/wsrp/wsrp-configuration.xml contains the location of file wsrp-consumers-config.xml defined under the configuration key consumersConfigLocation.
The lib directory, which contains the different libraries needed by the WSRP service.
The wsrp-admin-gui-2.2.2.Final.war, which contains the WSRP Configuration portlet with which you can configure consumers to access remote servers and how the WSRP producer is configured.
The wsrp-producer-jb5wsss-2.2.2.Final.war, which contains the producer-side support for WS-Security.

If WSRP is not required, it will not adversely affect your installation to leave it as is. Otherwise, remove the gatein-wsrp-integration.ear file from your AS deploy directory.

See Also:

Section 30.1, “About Web Services Security Configuration”

Report a bug

⁠28.2.2. Considerations to use WSRP

The web service stack that the portal uses is based on JBoss WS. It updates the port and host name used in WSDL. For more information, see the Web Services chapter in the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration User Guide.

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 the platform's producer.

Report a bug

⁠28.3. Remote Portlets

⁠28.3.1. Making a Remote Portlet

The portal does not expose local portlets for consumption by remote WSRP consumers by default. In order 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 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.

Important

Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality.

Report a bug

⁠28.3.2. Making a Single Remote Portlet

⁠

Example 28.1. Single Portlet Remotable Example

The "BasicPortlet" portlet is specified as being remotable.

<?xml version="1.0" standalone="yes"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
             version="2.0">
<portlet-app>
   <portlet>
      <portlet-name>BasicPortlet</portlet-name>

      ...

      <container-runtime-option>
         <name>org.gatein.pc.remotable</name>
         <value>true</value>
      </container-runtime-option>
   </portlet>
</portlet-app>

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.

Report a bug

⁠28.3.3. Making Multiple Remote Portlets

The example defines two portlets. The org.gatein.pc.remotable container-runtime-option being set to true at the portlet-app level, all portlets defined in this particular portlet application are exposed remotely by the WSRP producer.

<?xml version="1.0" standalone="yes"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
             version="2.0">
<portlet-app>

   <portlet>
      <portlet-name>RemotelyExposedPortlet</portlet-name>
      ...
   </portlet>
   <portlet>
      <portlet-name>NotRemotelyExposedPortlet</portlet-name>
      ...
      <container-runtime-option>
         <name>org.gatein.pc.remotable</name>
         <value>false</value>
      </container-runtime-option>
   </portlet>

   <container-runtime-option>
      <name>org.gatein.pc.remotable</name>
      <value>true</value>
   </container-runtime-option>
</portlet-app>

It is possible to override the default behavior by specifying a value for the org.gatein.pc.remotable container-runtime-option at the portlet level.

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 to true, portlets are not remotely exposed.

Report a bug

⁠28.3.4. Make portlets aware of WSRP requests

A portlet can check if a request is coming from WSRP by referring to the WSRP attributes. WSRP sets the org.gatein.invocation.fromWSRP (defined by the org.gatein.wsrp.WSRPConstants.FROM_WSRP_ATTRIBUTE_NAME constant) request attribute to Boolean.TRUE when the request is initiated from WSRP.

⁠

Example 28.2. Checking if a request is issued from WSRP inside a portlet

if (!Boolean.TRUE.equals(request.getAttribute(WSRPConstants.FROM_WSRP_ATTRIBUTE_NAME)))
{
  // do something
}

Report a bug

⁠28.3.5. Using WSRP Portlets from a Remote Consumer

WSRP Producers vary greatly from a configuration perspective. Most of them require that you specify the URL for the Producer's WSDL definition. See the remote producer's documentation for specific instructions. For instructions on how to configure the WSRP producer in the portal, see the Consumer Configuration.

The portal'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. To use only the WSRP 1 compliant version of the producer, 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.

Report a bug