Chapter 5. Action event handling

< Day Day Up >

Chapter 5. Action event handling

This chapter covers the ActionListener interface and the objects you will need to work with when managing event handling. To receive these events, an event listener must be implemented in the portlet class. In addition, the required method, actionPerformed, must be added to process the action event.

< Day Day Up >

5.1 Action event

When a portlet wishes to be notified that a user has performed an action, it has to implement the ActionListener interface and a portlet action. Only the portlet generating the event may listen for that event. There will always be only a single listener for any particular action event. In order to notify other portlets of an event, the listening portlet may choose to send messages. For portlet messaging details, see Chapter 7, "Portlet messaging" on page 225.

A portlet has two phases of processing and rendering sequences. The first phase is the action processing phase. All events are generated, delivered and processed in this phase. Once this phase is complete, the service phase begins, in which portlets' outputs are rendered. Once this phase has begun, no events can be generated without causing an exception. The service method is also called when a portal page is refreshed.

The objects you will need to work with when managing event handling in action events are described below.

ActionListener

The org.apache.jetspeed.portlet.event.ActionListener interface defines a single method to be implemented as illustrated in Example 5-1.

Example 5-1. Implementing ActionListener interface

org.apache.jetspeed.portlet.event.ActionListener

public void actionPerformed(org.apache.jetspeed.portlet.event.ActionEvent

event) throws PortletException;

ActionEvent

An ActionEvent is sent by the portlet container when an HTTP request is received that is associated with a portlet action.

Note

The getAction() method returns the action that this action event carries but it is deprecated in favor of a getActionString() method.

The getActionString() method returns the action string that this event carries. Simple portlet actions use a single string as portlet action which can be executed multiple times and does not require a session.

Example 5-2. Working with the ActionEvent.

public void actionPerformed(ActionEvent event) throws PortletException {

   String actionString = event.getActionString();

   PortletRequest request = event.getRequest();

}

PortletURI

The PortletURI represents a URL that can be used to create navigation between modes. The PortletURI can be used to navigate to a previous mode, such as from Edit to View, or to navigate back to the same mode, such as for a multi-part form in View or Edit. There is no ability to create a PortletURI object pointing to a mode not yet visited by the user.

PortletResponse.createURI returns a portletURI object pointing to the portlet in its current mode. For example, if the portletURI is created in the doView mode, the URL points to the portlet in View. The createReturnURI method returns a PortletURI object pointing to the last mode the portlet was in. This mode is commonly used in the doEdit method when the URI needs to point back to the View mode. The edit.jsp would use the PortletURI to bring the user back to the View mode when the edit or configure process has been completed.

In order for a portlet to be notified of an event, such as the user clicking a button, the portletURI must contain an associated PortletAction. Typical PortletURI construction and usage is shown in Example 5-3.

Example 5-3. Working with PortletURI

PortletURI uri = response.createReturnURI();

uri.addAction("save");

request.setAttribute("uri", uri.toString());

It is possible to add parameters to the PortletURI object. Parameters added to the PortletURI via code or through a form are accessed in the same way via the portlet request object. This provides a mechanism to pass default values or to pass parameters not displayed in the form. Example 5-4 displays the code for adding a parameter. Be aware that parameters set via the PortletURI are not passed in the traditional HTML syntax. Example 5-4 shows how parameters are added to the URI.

Example 5-4. Adding a parameter to the PortletURi

public void

doView

(PortletRequest request, PortletResponse response) throws

                      PortletException, IOException {

   PortletURI viewURI = response.createReturnURI();

   viewURI.addAction("save");

   viewURI.addParameter("Param1", "Param1Value");

   request.setAttribute("viewURI", viewURI.toString());

   getPortletConfig().getContext().include("/jsp/View.jsp", request,

                      response);

   }

Portlet.ModeModifier

When a PortletURI is created, it points to a portlet in a particular mode. When that PortletURI is executed and if it contains a PortletAction, it will notify the appropriate listener. If, in the actionPerformed method, you need to redirect the user to a mode other than the one specified, the request.setModeModifier method can be used to redirect the user to another mode. The ModeModifier can only be set during event processing. Calling this method in doView or doEdit will have no effect. There are three possible modes to which the user can be redirected.

REQUESTED : this ModeModifier will navigate the user to whatever mode was originally set by the PortletURI. Essentially, this is the default. If the ModeModified is changed, it cannot be changed back to REQUESTED .
CURRENT : this ModeModifier will keep the user in the current mode. For example, if the user tries to save some information and the actionPerformed determines it is incorrect, setting ModeModifer to CURRENT will return the user to the edit screen.
PREVIOUS : this ModeModifier will return the user to the mode the user was in prior to CURRENT regardless of previous ModeModification. Therefore, setting ModeModifer to CURRENT in one event process will not make that mode PREVIOUS in the next event process.