Portlet events based communications

Portlet events provide a powerful and flexible publish/subscribe mechanism for communication between JSR 286 portlets. They can be used to exchange complex data between portlets and to trigger portlet activity such as updates to back end systems. In the portal, they can also interoperate with other communication mechanisms such as Cooperative portlets and click-to-action.

For more information about the portal event distribution mechanism, refer to the documentation about event broker.

Concepts of the Java Portlet Specification 2.0

Programming details for portlet events are defined in the Java Portlet Specification 2.0. Portlets can publish events using the response.setEvent() call and receive events in the processEvent method. The GenericPortlet class provides a default event handling mechaniso that dispatches events based on the @ProcessEvent annotation.

As a portlet programmer, declare all events that a portlet can publish or receive in the portlet.xml deployment descriptors.

Example declaration in the deployment descriptors:

<portlet-app xmlns:x="http://acme.com/portlet" 
             xmlns:std="http://somestandardsbody.org/interop-events">
    <portlet>
        ...
        <supported-processing-event>
            <qname>x:address.showForUpdate</qname>
        </supported-processing-event>
        <supported-publishing-event>
            <qname>x:address.updated</qname>
        </supported-processing-event>
    </portlet>
    <event-definition>
        <qname>x:address.showForUpdate</qname>
        <alias>std:address</alias>
        <value-type>com.acme.portlets.common.Address</value-type>
    </event-definition> 
    <event-definition>
        <qname>x:address.updated</qname>
        <alias>std:address</alias>
        <value-type>com.acme.portlets.common.Address</value-type>
    </event-definition> 
</portlet-app>

This declares a publishing and a processing event with a Java payloads of class com.acme.portlets.common.Address and global names address.showForUpdate and address.updated in the namespace http://acme.com/portlet. In addition, the alias address in the namespace http://somestandardsbody.org/interop-events of some presumed standardization organization indicates that these events are compatible with any events of another portlet that has the same alias and can therefore work with input or output values of the provided address type. Here is a coding example:

public class MyPortlet extends GenericPortlet {
    public static String NAMESPACE = "http://acme.com/portlet";
    
    @ProcessAction(name="address.updated")
    public void addressUpdated(ActionRequest request, ActionResponse response) {
      ...
      Address myAddress = ...;
      response.setEvent(new QName(NAMESPACE, "address.updated"), myAddress);
    } 
    @ProcessEvent(name="address.showForUpdate")
    public void addressUpdated(EventRequest request, EventResponse response) {
      Address myAddress = (Address) request.getEvent();
      ...
    }

Controlling event distribution in the portal

The Java Portlet Specification intentionally leaves open how events are passed between portlets, but only specifies how they are published and received. In IBM WebSphere Portal v8.0, event distribution is based on the same event broker and wiring techniqueused to connect cooperative portlets. That means that when you place a portlet on a page, it will initially not be able to publish or receive any events. Use the portlet wiring tool link to connect the events declared by the portlet to outputs or inputs of other portlets.

Portlets can declare localized display names and descriptions for portlet events in the application resource bundle. Provide at least a display name, as the portlet wiring tool needs this information to display event sources and targets properly.

The portlet EventDistributionService provides the option to have user interface elements displayed dependent on whether a given event is wired to targets or not. The wiring information provided by this portlet service is available for all requests in which the property com.ibm.portal.portlet.Constants.FEATURE_EVENT_DISTRIBUTION_SERVICE is set and available. For incoming WSRP requests this property is not available.

Support for complex event types

As noted previously, portlet events support complex Java types as payloads. The Java Portlet Specification requires that such payload classes support Java serialization as well as XML serialization using Java XML Binding (JAXB) annotations. The portal supports transfer of such payloads between portlets, even if they are deployed in different WAR files. However, if the payload class is packaged as part of the portlet WAR file, it is necessary to serialize and deserialize values during the transport because both portlets use different class loaders, which will result in less than optimal run time performance.

To obtain optimal performance for transferring complex Java payloads, at the cost of a more complicated deployment process, remove the payload classes from the WAR file and deploy them in a class loadethat is shared by both portlets. We can do this using the IBM WAS shared libraries, or by placing the shared classes in the WP_PROFILE/PortalServer/config directory.

Parent: Portlet communication
Related:
Shared portlet state
Publish/subscribe message based communication
Special purpose techniques for data exchange
Cooperative portlets
Interoperability between events and cooperative portlets
Event broker
Portlet wires
Public render parameters
Known issues and restrictions with portlet communication