Portlet messaging

---

The Portlet API supports messaging between portlets on a page. For example, if four portlets (Left, Right, Top, Bottom) are part of a portlet application called Sides, then the portlet Left can send information to portlet Right, Top, and Bottom as long as they are on the user's same page. The following conditions apply to portlets that send and receive messages.

• The portlets must be on the same page. You can create a portlet configuration file for your portlet application that configures the portlets on a page at installation time, using XML configuration interface. See The XML configuration interface for more information.

• The portlets must be part of the same portlet application. This condition applies only to portlets implementing the PortletMessage interface. Portlets that extend DefaultPortletMessage do not have to be members of the same portlet application.

• Portlets that are deployed as Web services cannot send and receive messages.

Typically a message is sent from a portlet's action listener and received by another portlet's message listener. The user performs an action in one portlet. The action event is captured and processed. Based on the results of that action, the portlet can send a message to other portlets using the send() method of the PortletContext object.

Example: ActionListener that sends a message

---

...

public void actionPerformed (ActionEvent event) {

...

   if (action.getName().equals("browse")) {
      log.debug("BookmarkActionListener - browse action");
      String url = (String) action.getParameters().get("url");
      log.debug("BookmarkPortletActionListener - opening link: " + url);
...
      try {
         portlet.getConfig().getContext().send(null, new DefaultPortletMessage(url));
      }
      catch (AccessDeniedException ade) {
         log.error("BookmarkPortletActionListener - unable to send message.");
         log.error("URL = " + url + " - AccessDenied");
      }
   }

...

}

---

In this sample, the "browse" action has been defined in the bookmark portlet.

   DefaultPortletAction browseAction = new org.apache.jetspeed.portlets.DefaultPortletAction("browse");
   browseAction.addParameter("url", url);
   PortletURI portletURI = response.createReturnURI();
   portletURI.addAction(browseAction);
   String actionURI = portletURI.toString();

The send() method takes the following arguments :

portletName

The name of the portlet that receives this request. In the example above, the message is sent to null, which means it is broadcast to all portlet's in the same portlet application. To send the message to a specific portlet, specify the name of the portlet as it is defined by the <portlet-name> tag in portlet.xml.

message

The message to be sent. The message must be a PortletMessage object or any subclass that implements that interface. In the example above, the message is instantiated in a DefaultPortletMessage object containing the url string from the action that was performed.

The receiving portlet has a message listener that retrieves the message using the getMessage() method of the message event.

Example: MessageListener that receives a message

---

    public void messageReceived (MessageEvent event)
    throws PortletException
    {
        PortletMessage msg = event.getMessage();

        if (msg instanceof DefaultPortletMessage) {
            String url = ((DefaultPortletMessage)msg).getText();
            PortletAdapter portlet = (PortletAdapter)event.getPortlet();
            portlet.getPortletLog().debug("BookmarkPortletMessageListener messageReceived");
            PortletRequest request = event.getRequest();
            PortletSession session = request.getSession();
            session.setAttribute("url",url);
        }
    }
}

---

Since the MessageListener set the received message as an attribute of the session, the receiving portlet must get the "url" parameter from the session.

For more information about action events and message events, see Portlet events.

See also

• Click-to-Action
• IBM WebSphere Developer Domain - Portal Zone
• Themes and skins