Inter Portlet Communication API

This section contains the following:

• Overview

• Event Generation and Subscription

• Event Handling Life Cycle

• Scope of Event Processing

• Infinite Event Cycle Detection

• Deterministic Behavior

• Failure and Exception Handling

Overview

This API uses event generation and notification to convey the information/data among portlets. The event notification will be for the portlets which have registered themselves for listening to that particular event. Portlets interested in receiving an event will implement a single interface PortletEventListener.

The EventRequest interface can then be used to obtain the event name and event payload data. Event payload data can be obtained either by getting the event stream and reading from it or by calling getEventData() method which returns an Object and then casting it appropriately.

The EventResponse interface can then be used to set the render parameters so that the information can be passed on to the render method after processing the event received in handleEvent() method. 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.

Event Generation and Subscription

Event generation starts with an event generated in processAction() method of a portlet. Further events can also be generated in handleEvent() method in portlet class while handling the event received. The handleEvent() method will be called if and only if an event is fired and the portlet has subscribed to listen to that event. The events can also be generated in response to other events in handleEvent() method.

To create portlets which are interested in listening to certain events and taking some action in response to these events, the portlet must implement PortletEventListener interface. This interface has only handleEvent() method. The portlet gets the data from EventRequest and can take appropriate action. The developer can set any information required for the correct rendering of the portlets on EventResponse as render parameters.

All the portlets which are interested in listening or generating an event must declare it in sun-portlet.xml file. If a portlet requests an event which has not been declared in the sun-portlet.xml file, an exception NotRegisteredException will be thrown. Wild cards can not be used for declaring the events that will be generated. However, portlets interested in consuming all the events can use wildcard character (*) only inside <consumes—event></consumes—event> block.

Event Handling Life Cycle

The event cycle begins with the response to user interaction from inside processAction() method referred to as 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 continues till 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 referred to as Generation next events. If a portlet has subscribed to events which are generated in different generations, it will receive the events in proper order; that is, the handleEvent() method will be called with Generation i event first and upon completion of that method, handleEvent() method will be called with event from Generation i+1.

Scope of Event Processing

The events are sent to all the portlets obtained by recursively calling getSelectedChannels() method on the top level container (if any) as referenced by the request.

Infinite Event Cycle Detection

Events are generated in response to the user interaction (Generation 1) or in response to other events (Generation next). This could lead to more and more generations being created. To control the number of generations, the maxEventGenerations parameter in the desktopConfig.properties file can be configured for maximum number of generations of events per request. When the event creation exceeds the specified maximum number, a failure event, eventHandlingFailed will be sent to all the participating portlets.

Deterministic Behavior

If a portlet generates events X and Y in that order, then events X and Y will be delivered to the portlets in that same order. If portlet A and B are interested in Event X , either A or B can get event X first. If portlets A and B are interested in Event X, and upon receipt of that event generate events Y and Z respectively, and Portlet C is interested in Event Y and Z, then portlet C can receive events Y and Z in any order.

Failure and Exception Handling

In case of failure, the handleEvent() method may throw PortletException. The container catches that exception and will stop sending the events from the event queue. The container will then send another event called eventHandlingFailed to all the portlets participating in that particular interaction. The container will not take any action if the PortletException is thrown while processing eventHandlingFailed event. Portlets can not generate and send any events while handling the event eventHandlingFailed.