apache > cocoon

- Home

# WSRP Support

## General information

The Web Services for Remote Portlets (WSRP) specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. This documentation explains the usage of WSRP portlets including explanation about the functional process.

The latest version of the Cocoon Portal implements a WSRP consumer to allow the usage of WSRP portlets. A WSRP portlets is provided by WSRP producers that allow access over standardized web services - the WSRP interfaces. The Cocoon Portal supports verson 1.0 of the WSRP specification by integrating the Apache WSRP4J framework.

For further information about WSRP see:

- Oasis: Committee that defines the WSRP specification (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp)
- Apache: Standard open source implementation of WSRP in Java (http://ws.apache.org/wsrp4j)

## Enabling WSRP

The demo of the Cocoon Portal included in the Cocoon distribution comes with WSRP enabled. However, depending on your use case it's possible to disable/enable the WSRP support of the portal in the cocoon.xconf. If you're just interested in how to use WSRP, you can skip this section for now.

The WSRP consumer of the portal makes use of four components in the cocoon.xconf: the WSRP event aspect, the WSRP coplet adapter, the WSRP portlet window aspect and the user context provider. If you want to disable WSRP, you should uncomment these four components and their usage (explained below).

      <!-- Event Aspect configuration -->
     <component class="org.apache.cocoon.components.ExtendedComponentSelector"
                role="org.apache.cocoon.portal.event.aspect.EventAspectSelector">
          ...
       <!-- This aspect is required for wsrp: -->
       <aspect class="org.apache.cocoon.portal.wsrp.adapter.WSRPEventAspect" logger="portal" name="wsrp"/>
     </component>

        <!-- Coplet Adapter configuration -->
        <component class="org.apache.cocoon.components.ExtendedComponentSelector"
                   role="org.apache.cocoon.portal.coplet.adapter.CopletAdapterSelector">
          ...
       <!-- This is the wsrp adapter -->
       <coplet-adapter class="org.apache.cocoon.portal.wsrp.adapter.WSRPAdapter" logger="portal" name="wsrp">
         <!-- This is the wsrp configuration containing the producers etc. -->
      <parameter name="wsrp-config" value="profiles/wsrp-config.xml"/>
       </coplet-adapter>
     </component>

     <!-- Renderer Aspect configuration -->
     <component class="org.apache.cocoon.components.ExtendedComponentSelector"
                role="org.apache.cocoon.portal.layout.renderer.aspect.RendererAspectSelector">
       ...
          <aspect class="org.apache.cocoon.portal.wsrp.adapter.WSRPPortletWindowAspect" logger="portal" name="wsrp-window"/>
          ...
        </component>

        <!--  User Context Provider for WSRP -->
        <component class="org.apache.cocoon.portal.wsrp.consumer.UserContextProviderImpl" logger="portal"
                   role="org.apache.cocoon.portal.wsrp.consumer.UserContextProvider"/>

All of these components have to be configured to be used by the various parts of the Cocoon Portal. Again, if you want to disable the WSRP support, you have to uncomment the usage as well.

The event manager needs to be aware of the events dealing with WSRP, therefore we have to configure the WSRP event aspect on the event manager:

        <component class="org.apache.cocoon.portal.event.impl.DefaultEventManager" logger="portal" role="org.apache.cocoon.portal.event.EventManager">
       <event-aspects>
             ...
            <!-- Comment the following out if you don't need WSRP: -->
            <aspect type="wsrp"/>
             ...
       </event-aspects>
     </component>

The portal manager needs to be aware of dealing with WSRP portlets, therefore we have to configure the WSRP coplet adapter as an aspect of the portal manager:

        <component class="org.apache.cocoon.portal.impl.PortalManagerImpl" logger="portal" role="org.apache.cocoon.portal.PortalManager">
          <aspects>
            ...
            <!-- wsrp support: -->
            <aspect adapter="wsrp"/>
          </aspects>
        </component>

The last step is to configure an own renderer for the WSRP portlets. You can configure/define this renderer according to your needs, but be sure to include the wsrp-window aspect. This aspect is required for rendering the title bar containing the icons.

        <!-- Renderer configuration -->
        <component class="org.apache.cocoon.components.ExtendedComponentSelector" role="org.apache.cocoon.portal.layout.renderer.RendererSelector">
          ...
       <renderer class="org.apache.cocoon.portal.layout.renderer.impl.AspectRenderer"
                 logger="portal"
                 name="wsrp-window">
         <aspects>
        <aspect type="xslt">
       <parameter name="style" value="{portal-skin:skin.basepath}/styles/window.xsl"/>
        </aspect>
              <aspect type="parameter">
                <parameter name="tag-name" value="window"/>
        </aspect>
              <aspect type="wsrp-window">
                <parameter name="root-tag" value="false"/>
              </aspect>
              <aspect type="coplet-removing"/>
              <aspect type="history"/>
              <aspect type="coplet-cinclude"/>
            </aspects>
          </renderer>
          ...
        </component>

## Defining WSRP portlets

### The WSRP Coplet Adapter

The Cocoon Portal uses the concept of coplet adapters to integrate different types of portlets (Cocoon pipelines, JSR 168, WSRP etc.). The adapter component is configured in the cocoon.xconf as we have seen above. The portal application defines a coplet base data using the adapter. You can find the configuration for the demo portal in the profiles/copletbasedata directory which is located in the directory containing the portal demo. The portal.xml contains the configuration:

        <coplet-base-data id="WSRP">
          <coplet-adapter>wsrp</coplet-adapter>
            <configuration>
              <name>buffer</name>
              <value xsi:type="java:java.lang.Boolean">true</value>
            </configuration>
          </coplet-adapter>
        </coplet-base-data>

This file defines a corresponding adapter to use WSRP. The configuration "buffer" decides if the streamed content should be buffered before it is send into the pipeline. Buffering is required if during streaming of the portlet content an error might occur. Without buffering a part of the portlet content has been already streamed into the pipeline and can't be reset on an error. This results in a broken page. Therefore buffering should always be turned on for WSRP.

### The WSRP Configuration

The Cocoon Portal uses a central configuration for WSRP. Currently this configuration holds all WSRP producers. The demo of the portal contains already a sample configuration for the WSRP4J producers running locally.

The WSRP configuration is in the profiles/wsrp-config.xml file inside the portal directory. If you want to use a different location, you can configure it as a parameter on the WSRP coplet adapter in the cocoon.xconf. This is the sample wsrp-config.xml:

       <wsrp-config>
          <producers>
            <producer id="prod_localhost_8081">
              <markup-interface-url>http://localhost:8081/wsrp/wsrp4j/WSRPBaseService</markup-interface-url>
              <service-description-interface-url>http://localhost:8081/wsrp/wsrp4j/WSRPServiceDescriptionService</service-description-interface-url>
              <registration-interface-url>http://localhost:8081/wsrp/wsrp4j/WSRPRegistrationService</registration-interface-url>
              <portlet-management-interface-url>http://localhost:8081/wsrp/wsrp4j/WSRPPortletManagementService</portlet-management-interface-url>
            </producer>
          </producers>
        </wsrp-config>

Each producer has to be registered here.A producer is uniquely identified by it's id. The id is specified as an attribute on the producer element. As the identifier has to be unique, it is advisable to include the host and the port of the producer, like in the example: "prod_<host>_<port>".

The producer requires some configuration: the urls of the different web-services. Whereas the markup-interface-url and the service-description-interface-url are required, the registration-interface-url and the portlet-management-url are optional. Each url is configured using an element with the value being the url of the web-service.

Once the producer is configured, we can start defining portlets using this producer. This is done in the usual fashion as a configuration of the coplet data.

### Coplet Data Configuration

You can have a look at the global coplet data configuration in the "profiles/copletdata" directory of the demo portal. In the portal.xml you will find a WSRP sample using the standard WSRP4J test portlet:

        <coplet-data id="wsrp-test-portlet" name="standard">
          <title>WSRP-Test-Portlet</title>
          <coplet-base-data>WSRP</coplet-base-data>
          <attribute>
            <name>producer-id</name>
            <value xsi:type="java:java.lang.String">prod_localhost_8081</value>
          </attribute>
          <attribute>
            <name>portlet-handle</name>
            <value xsi:type="java:java.lang.String">0.1</value>
          </attribute>
          <attribute>
            <name>use-pipeline</name>
            <value xsi:type="java:java.lang.Boolean">true</value>
          </attribute>
        </coplet-data>

The coplet-base-data element references the coplet base data object for the WSRP support as explained above. Using the title element you can set a standard window title for this portlet. This title will be used if the WSRP portlet doesn't provide its own title.

The following elements define the required attributes for this portlet. The first attribute sets the producer to be used. The name of the attribute is "producer-id" and the value contains the unique name of the WSRP producer as defined in the WSRP configuration (see above). A producer can define more than one portlet, therefore each portlet offered by the producer has a unique handle. With the "portlet-handle" attribute, you have to define this unique handle for the portlet you want to use.
The content of a WSRP portlet is by default not send through the pipeline. This is in order to avoid unnecessary HTML parsing. Instead the content is added by the
serializer after the pipeline has finished. If you want to send the content of a WSRP portlet through the pipeline for further processing, you can set the attribute "use-pipeline" to "true".

### Creating Instances

The final step is to create one or more instances of the WSRP portlet for the acutal user. Again, this is done in the usual way by adding instances to the coplet instance data profile. The sample portal contains already such a definition in the file "profiles/copletinstancedata/portal.xml":

       <coplet-instance-data id="WSRP-Test-1" name="standard">
          <coplet-data>wsrp-test-portlet</coplet-data>
        </coplet-instance-data>

It is possible to create more than one instance of the same WSRP portlet. Each coplet instance data gets a unique id (using the id attribute) and has a reference to the defined coplet data (using the coplet-data element).

## Using WSRP portlets

As usual the final step is to add the WSRP portlet somewhere in the portal page of the user. The demo portal already contains a WSRP portlet: if you log into the portal there is a separate tab named "WSRP" containing the portlet.

If you look into the layout file at "profiles/layout/portal.xml", you will see the usage of the portlet:

     <coplet-layout name="coplet" layout-renderer-name="wsrp-window">
       <coplet-instance-data>WSRP-Test-1</coplet-instance-data>
     </coplet-layout>

It is required that the coplet layout uses the special "wsrp-window" renderer for rendering a WSRP portlet. The "wsrp-window" renderer is responsible for rendering the special title bar containing the icons for the WSRP functions like view, edit or help.

## Layouting

The WSRP specification defines some css styles for the consumer. The Cocoon Portal already contains an empty css definition for WSRP. You'll find the file in the corresponding skin directory: "css/wsrp.css". The following sections can be configured: fonts, messages, sections, tables, forms and menus.

## Pipelining

The WSRP portlet might use/display different resources like images. Therefore the portal sitemap contains a special pipeline for delivering these resources:

      <!--  WSRP Resources -->
        <map:match pattern="wsrprsc">
          <map:read src="{request-param:wsrp-url}"/>
        </map:match>

## Logging

The WSRP part of the Cocoon Portal uses the standard portal logger for all logging purpuses. By default, all log entries go into the portal.log in the logs directory. You can adjust the settings in the logkit.xconf.

## Providing User Information

WSRP allows exchanging information about the user between the consumer and the producer. As these information are portal application specific, the default implementation of the Cocoon Portal is only sending the user id (used to authenticate the user).

It is possible to customize this information by implementing a org.apache.cocoon.portal.wsrp.consumer.UserContextProvider and configuring it in the cocoon.xconf.

## Customizing the WSRP4J integration

If you have special needs it's possible to customize the WSRP4J integration. The integration itself is implement in several components you can subclass and then use your own implementation.

You can specify your own implementation using the following parameter names as a configuration on the WSRPAdapter:

- user-registry-class : org.apache.wsrp4j.consumer.UserRegistry.
- session-handler-class : org.apache.wsrp4j.consumer.SessionHandler
- producer-registry-class : org.apache.wsrp4j.consumer.ProducerRegistry
- portlet-registry-class : org.apache.wsrp4j.consumer.PortletRegistry
- url-template-composer-class : org.apache.wsrp4j.consumer.URLTemplateComposer
- url-rewriter-class : org.apache.wsrp4j.consumer.URLRewriter
- portlet-driver-registry-class : org.apache.wsrp4j.consumer.PortletDriverRegistry
- url-generator-class : org.apache.wsrp4j.consumer.URLGenerator
- portlet-driver-class : org.apache.wsrp4j.consumer.PortletDriver

### Adding Producers at runtime

The Cocoon Portal uses the wsrp configuration (as explained above) to configure all available WSRP producers. However, it is possible to add producers at runtime
using the WSRP adapter. Create a "org.apache.cocoon.portal.wsrp.consumer.ProducerDescription" object. You have to set a unique id, the markup interface url and the service description interface url; the registration interface url and portlet management interface url are optional.

Lookup the WSRP adapter from a ServiceManager and invoke the addProducer() method:

    ServiceSelector selector = (ServiceSelector)serviceManager.lookup(CopletAdapter.ROLE + "Selector");
    WSRPAdapter adapter = (WSRPAdapter)selector.select("wsrp");

    adapter.addProducer(description);

    selector.release(adapter);
    serviceManager.release(selector);

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).