JSR 286 The Eventing feature

In order to provide coordination between portlets the Java Portlet Specification, JSR 286 introduces the following mechanisms

• Eventing: portlet events that a portlet can receive and send
• Public Render Parameters: render state that can be shared between portlets

In this blog, i will explain the Eventing feature and in a later blog i will explain the Public Render Parameter feature.

Eventing can be described as a loosely coupled, brokered means of communication between portlets. It is intended to allow portlets to react on actions or state changes not directly related to an interaction of the user with the portlet.
Events are a lifecycle operation that occurs before the rendering phase.

Now let us get into the details of writing portlets that use this feature

The portlet can declare the events in its deployment descriptor using the event-definition element in the portlet application section. In the portlet section each portlet can specify the events it would like to publish via the supported-publishing-event element and the events it would like to process via the supported-processing-event element. The supported-publishing-event and supported-processing-event element must reference the event name defined in the portlet application section in a event-definition element.

The portlet issues events via the setEvent method during the action processing. This will be processed by the portlet container after the action processing has finished.

In order to receive events the portlet must implement the javax.portlet.EventPortlet interface. The portlet container will call the processEvent method for each event targeted to the portlet with an EventRequest and EventResponse object.
The portlet can access the event that triggered the current process event call by using the EventRequest.getEvent method. This method returns an object of type Event encapsulating the current event name and value.

Event names are represented as QNames in order to make them uniquely identifiable. The event name can be either retrieved with the getQName method that returns the complete QName of the event, or with the getName method that only returns the local part of the event name. The value of the event must be based on the type defined in the deployment descriptor.

Following are the steps to write portlets that make use of eventing feature

1.Declare the events in the portlet.xml
1.1 Set the event definition at the portlet application level. This specifies the event name and the object type.
Note: The object must be serializable.



x:Address.Create

com.test.Address


1.2 In the portlet section, specify the event name defined above for those portlets that want to publish this event.

.................

x:Address.Create


1.3 In the portlet section, specify the event name defined above for those portlets that want to process this event.

.................

x:Address.Create



2.Issue an event in the portlet that was specified as supported-publishing-event in the portlet
@XmlRootElement
public class Address implements Serializable
{
private String street;
private String city;
public void setStreet(String s) {street = s;}
public String getStreet() { return street;}
public void setCity(String c) { city = c;}
public String getCity() { return city;}
}

void processAction(ActionRequest request, ActionResponse response)
{
String myStreet = request.getParameter("street");
String myCity = request.getParameter("city");
Address sampleAddress = new Address();
sampleAddress.setStreet(myStreet);
sampleAddress.setCity(myCity);
QName name = new QName("http:sun.com/events", "Address.Create");
response.setEvent(name, sampleAddress);
}

3.Process the event in the portlet that has specified as supported-processing-event in the portlet
void processEvent(EventRequest request, EventResponse response)
{
Event event = request.getEvent();
if ( event.getName().equals("Address.Create") )
{
Address payload = (Address) event.getValue();
.......
}
}

You can checkout the sources from OpenPortal Portlet Container that has the implementation of the eventing feature. Write a portlet that uses the eventing feature and try it.