Portlet events contain information about an event to which a portlet might need to respond. For example, when a user clicks a link or button, this generates an action event. To receive notification of the event, the portlet must have an event listener implemented within the portlet class.
Action events: generated when an HTTP request is received by the portlet container that is associated with an action, such as when the user clicks a link.
Message events: generated when another portlet within the portlet application sends a message.
A portlet has a different processing and rendering sequence than a servlet. A servlet does all of its processing in the service() method. A portlet, on the other hand, uses a two phase processing that is split between an event phase and a render phase. This split is necessary to accommodate communication between portlets before rendering output in the service stage. The event phase is guaranteed to complete before a portlet is called to render.
During the event phase, the portlet implements an ActionListener interface. The ActionListener interface provides the actionPerformed() method, to which an ActionEvent object is passed. When a user clicks on a link or a submit button, an ActionEvent can be generated. The portlet action can be obtained from the ActionEvent, which describes the triggering event. When the actionPerformed() method is invoked, a response object is not available because this is not a rendering step. All state changes should be handled during action processing.
Portlets should use the render phase only to render portlet output. The service() method is not only called following the actionPerformed() processing when a user clicks on a link or button in a portlet, but is also called when the portal page is refreshed. Thus, given a page with two portlets, A and B, when the user clicks on a link in portlet A, actionPerformed() and doView() is called for portlet A, but only the doView() method is called for portlet B. Once the content generation phase has started, no further events will be delivered. For example, messages cannot be sent from within the beginPage(), service() and endPage() methods. The resulting message event would not be delivered and essentially discarded.
The event listener is implemented directly in the portlet class. The listener can access the PortletRequest from the event and respond using the PortletRequest or PortletSession attributes.
Action events
An ActionEvent is sent to the portlet when an HTTP request is received that is associated with a portlet action. To receive action events, the portlet class must implement the ActionListener interface and a portlet action. A portlet action can be one of the following types:
Simple portlet action String
PortletAction object
These actions are explained below. See Using persistence for code examples that show how to add a portlet action and create an ActionListener .
Simple portlet action String
Actions created as simple actions can be executed multiple times, enabling a user's back button to work. Links created with simple portlet actions are represented in the URL rather than in the session. Therefore, portlets with simple actions can be placed on an anonymous page where no session exists. Simple portlet actions are associated with action events by using the getActionString() method.
PortletURI.addAction(String simpleAction);
String ActionEvent.getActionString();
Simple portlet actions are not available in the Portlet API prior to WebSphere Portal Version 4.2. A portlet can determine if the portal server it is running on supports simple actions or not by checking the Portlet API version. The version of the Portlet API on servers that support simple actions has changed from 1.1 to 1.2. Here is example code that illustrates how to check for simple action support:
if ( (portletContext.getMajorVersion() <= 1 ) && (portletContext.getMinorVersion() <= 1) )
{
// cannot use simple actions
} else {
// simple action support is present on this server
}
Note: Some portlets should be designed so that their actions are not executed every time a user refreshes their browser. In this case, set the following parameter and value either as an <init-param/> or <config-param/> in the appropriate descriptor.
com.ibm.wps.portlet.action.redirect = true
This allows the page and portlet to be reloaded without the action parameters in the URL.
PortletAction object
The PortletAction object has been deprecated in favor of simple portlet action strings. It is maintained in the Portlet API to support existing portlets that use PortletActions. You should always use simple portlet actions instead of PortletAction objects.
Message events
IBM portlets that either implement the PortletMessage interface or extend the DefaultPortletMessage class can send information to other portlets on the page. Portlets receiving the message must implement the MessageListener interface and an object with the type PortletMessage. However, it is recommended that you use the property broker service for interportlet communication. See Cooperative portlets for more information.
Message events can be sent from one portlet to others if the recipient portlets are members of the same portlet application and are placed on the same page as the sending portlet. Additionally, a DefaultPortletMessage can cross portlet application boundaries and may be send to all portlets on a page. A MessageEvent can be sent actively to other portlets only when the portlet is in the event processing cycle of the portlet container, otherwise an exception is thrown. There are two different types of messages:
Single addressed messages: Messages sent to a specific portlet by specifying the portlet name on the send() method.
Broadcast messages: Messages sent to all portlets on the page.
Message events are useful when changes in one portlet should be reflected in another one. An object with the type PortletMessage has to be implemented which is passed via the MessageEvent. The portlet receiving the message must implement the MessageListener interface and an object with the type PortletMessage.