JSR 286 portlet events based communications

Portlet events provide a publish/subscribe mechanism for communication between JSR 286 portlets. Portlet events can also interoperate with other communication mechanisms such as Cooperative portlets and click-to-action.

For more information about the portal event distribution mechanism, read the section about the portal 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 mechanism 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 descriptor.

Example declaration in the deployment descriptor:

<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 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.5, event distribution is based on the same event broker and wiring techniques used 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 Javan 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 loader shared by both portlets. We can do this using the WAS shared libraries, or by placing the shared classes in the WP_PROFILE/PortalServer/config directory.

Parent Define portlet communication capabilities

Related concepts:

Public render parameters