Inter Portlet Communication Portlets

This section explains about the steps to develop Inter Portlet Communication (IPC) portlets.
The topics include:

Inter Portlet Communication API
Event Generation and Subscription
Event Handling Life Cycle
Failure and Exception Handling
Samples

Inter Portlet Communication API

Portlets can communicate with each other even if they are in different web applications. It is assumed that all the portlets are on the same instance of the Portlet Container. The Inter Portlet Communication API uses event generation and notification to convey the information or data among portlets. The event notification occurs for the portlets, which are registered themselves for listening to that particular event.

The IPC API is located in the com.sun.portal.portlet package. Portlets that are interested in receiving an event implements a single interface, PortletEventListener.

public interface PortletEventListener {

    public void handleEvent(EventRequest ereq, EventResponse eres) throws PortletException;
}

You can use EventRequest to obtain the event name and event payload data. You can obtain Event payload data either by getting the event stream and reading from it or by calling getEventData() method which returns an Object and then casting it appropriately. If getEventData() is called after getting the event stream an IllegalStateException is thrown. Similarly, if getEventStream() is called after getEventData() an IllegalStateException is thrown.

public interface EventRequest() {
    public String getEventName();
    public InputStream getEventStream();
    public Object getEventData();
}

You can use EventResponse to set the render parameters, so that the information can be passed on to the render method after processing the event received in the handleEvent() method.

public interface EventResponse() {
    public void setRenderParameters(Map parmMap);
    public void setRenderParameter(String key, String value);
    public void setRenderParameter(String key, String[] values);

}

The portlets can generate events only from within the handleEvent() or processAction() methods. Event can be generated by instantiating PortletEventBroker and calling createEvent() method on it. The PortletEventBroker constructor throws an IllegalStateException if you call from methods other than the handleEvent() or processAction().

public class PortletEventBroker {
    //Make sure that the call is coming from handleEvent() or from processAction()
    public PortletEventBroker(PortletRequest pr);
    //to create an event
    public PortletEvent createEvent(String eventName) throws EventNotRegisteredException;
}

You can then use the PortletEventBroker instance to create an event by calling the createEvent() method.

public interface PortletEvent {
    public String getEventName();
    public OutputStream getEventStream();
    public void setEventData(Serializable s);
    public void fire();
}

You can set the event data can on the event stream which can be obtained by calling getEventStream() method. Alternatively, event data can be set by calling setEventData() method. If after obtaining the event stream, attempt to call setEventData() throws the IllegalStateException exception. Similarly, after calling setEventData() an attempt to call the getEventStream() throws the IllegalStateException exception. The event is then fired by calling the fire() method.

Event Generation and Subscription

All the portlets which are interested in listening or generating an event must declare it in the sun-portlet.xml file as shown below:

    portletName
    
   
       eventName1
       eventName2
        ....
       eventName3
       eventName4
   

If a portlet requests an event, which it has not declared in the sun-portal.xml file, an exception NotRegisteredException is thrown.Wildcards cannot be used for declaring the events that are generated. Portlets interested in consuming all the events can use wildcard character (*) as shown below:

   portletName
   
   
       eventName1
        eventName2
        .......
     *
   

Event Handling Life Cycle

The event cycle starts with the response to user interaction from the inside processAction method. These are Generation 1 events. These events are placed in the event queue by the Portlet Container and dispatched in the order they are created. The dispatching of the events continue, until all the events in the event queue are dispatched to appropriate portlets. Dispatching of the events amount to calling the handleEvent methods of the appropriate portlets.

Portlets can generate events in the handleEvent method which are Generation next events.

Failure and Exception Handling

In case of failure, handleEvent() method may throw PortletException. Container will catch that exception and stop sending the events from the event queue. Container then sends another event called PortletEvent.EVENT_HANDLING_FAILED to all the portlets participating in that particular interaction. Container does not take any action if the PortletException is thrown while processing eventHandlingFailed event. Portlets cannot generate and send any events while handling the event PortletEvent.EVENT_HANDLING_FAILED. The portlet developer has the responsibility to take appropriate action needed.

Samples

The IPC sample portlets are located in portlet-container/samples. The portlet samples are divided into ipc1 and ipc2 sub-directories. This is to demonstrate eventing between portlets belonging to different web application and those belonging to the same web application. The interaction between the IPC Portlet samples is as follows:

searchportlet (ipc2) --> listportlet (ipc1)
priceportlet (ipc1) --> considerationportlet (ipc1)
priceportlet (ipc1) -->decisionportlet (ipc2)

Source and Binary for the samples

• ipc1: Binary, Sources
• ipc2: Binary, Sources