Portlet Development Guide

Local Interportlet Communication

Interportlet communication (IPC)—also called portlet-to-portlet communication—allows multiple portlets to use or react to data. For example, you might want to use IPC in a self-service or sales implementation where common data elements, such as order ID or customer ID, are used across multiple projects. All portlet types supported by WebLogic Portal can implement IPC. Examples of IPC include:

IPC in WebLogic Portal is based on the use of event handlers—objects that listen for predefined events on other portlets in the portal and fire actions when that event occurs. You can set up interportlet communication in two ways: using the Workshop for WebLogic interface, or using the WebLogic Portal API.

This chapter includes a tutorial-based example of establishing interportlet communications using an out-of-the-box portal event handler (Basic IPC Example). This example will familiarize you with event handlers and show you some of their common uses.

This example is specific to interportlet communications within a single portal web project. For information on establishing IPC with federated portals (WSRP), refer to the Federated Portals Guide.

This chapter includes the following sections:

Definition Labels and Interportlet Communication

IPC behavior is based on portlet definition labels; that is, all portlet instances of a given .portlet file respond to the same events. You can use the event handler options Only If Displayed and From Self Instance Only to discriminate among the instances of the same .portlet file. For a description of these options, refer to Portlet Event Handlers Wizard - Add Handler Field Descriptions.

Portlet Events

Portlet events (not to be confused with page flow events) allow portlets to communicate. One portlet can create an event and other portlets can listen for that event. A portlet event can also carry accompanying data called a payload, where the payload is a serializable Java object.

This section contains the following topics:

Event Handlers

Event handlers listen for events raised on subscribed portlets and fire one or more actions when a specific event is detected. An event handler tag is a child of the <portlet> tag, and a portlet can have any number of events associated with it. The following event handlers are available with WebLogic Portal:

Generic Event Handlers

The generic event handler, with an event attribute value of myEvent, will be triggered on the following conditions:

Using a generic event handler allows you to more effectively decouple your portal design, because your application does not need to know the source or type of an event. You can change the portlet type (for example, from a page flow portlet to a JSP portlet, with a backing file firing custom events) without affecting how you events are processed.

Event Types

An event action depends upon the type of event being raised. Except for portal events, all other events can be identified in the Events field on the Portlet Event Handlers Wizard, as described in Portlet Event Handlers Wizard Reference. Events available with the portal event handler are listed in Table 7-1.

Event Actions

Event handlers fire an action on the host portlet when that handler detects an event from another portlet in the application (or possibly the same portlet, for example in the case of a page flow portlet). For example, when the user minimizes the appropriate portlet, a portal event called onMinimize might cause the handler listening for it to fire an action that invokes an attached backing file.

Table 7-2 lists the event actions available for portlets.

Portlet Event Handlers Wizard Reference

The Portlet Event Handlers wizard included in Workshop for WebLogic allows you to implement several types of event handlers and actions without programming. The following steps summarize the process of setting up an event handler using the wizard:

The following sections describe the dialogs of the wizard and provide information about the information required in each field of the dialogs.

For a specific procedural example of how to use the event handler wizard, refer to Basic IPC Example.

Portlet Event Handlers Wizard Dialogs

The wizard opens when you open a portlet in Workshop for WebLogic and click the ellipsis button next to Event Handlers in the Properties view.

The wizard appears, as shown in Figure 7-1.

When you click Add Handler, the event handler drop-down menu allows you to select a handler; to add an action, click Add Action to open the event action drop-down menu.

Based on your selection, the dialog box expands, displaying additional fields that you can use to set up the handler or action. Figure 7-2 shows an example of the expanded dialog for adding an event handler.

Portlet Event Handlers Wizard - Add Handler Field Descriptions

Table 7-3 explains the fields in the Add Handler dialog and how your selections affect the behavior of the event.

Portlet Event Handlers Wizard - Add Action Field Descriptions

The available fields for the action depend on the type of action that you select. Table 7-4 explains the possible fields in the expanded Add Action dialog and how your selections affect the behavior of the action.

IPC Example

This section contains the following topics:

Before You Begin - Environment Setup

Before you use the interportlet communication example in this chapter, you must have an existing portal development environment, consisting of a domain, Portal EAR project, Portal Web project, Datasync project, and portal. To complete the pre-requisite tasks, perform the tasks described in the Getting Started with WebLogic Portal tutorial, using the information in Table 7-5 to enter the necessary values.

Figure 7-3 shows how your workbench should look after you complete the pre-requisite tasks:

With a development environment set up, you can complete the steps described in this section:

In this exercise, you create individual page flows, portlets, JSPs, and backing files to establish interportlet communications within the portal project. You then add these portlets to a portal and test the project to ensure that communication is successful.

Basic IPC Example

This section describes the process of setting up interportlet communications between two portlets by using the Portal Event Handlers wizard in Workshop for WebLogic. This is a simple example in which minimizing one portlet changes the text string in another portlet in the portal.

You should become familiar with the Portal Event Handlers Wizard and backing files before attempting to replicate this example. For more information about the wizard, refer to Portlet Event Handlers Wizard Reference. For more information on backing files, refer to Backing Files.

This exercise includes five main tasks:

Create the Portlets

In this section, you create two JSP files and the JSP portlets that surface these files. You also create a backing file that contains the instructions necessary to complete the communication between the two portlets, and you add an event handler to one of the portlets. After you have created the portlets and attached the backing file, you test the project in your browser.

Create the JSP Files and Portlets

To create the JSP files that the portlets will surface, do the following:

Checkpoint: At this point the ipcWebProject/WebContent folder contains these files: aPortlet.jsp, aPortlet.portlet, bPortlet.jsp, and bPortlet.portlet.

Create the Backing File

To create the backing file, do the following:

package backing;

import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
import com.bea.netuix.servlets.controls.portlet.backing.PortletBackingContext;
import com.bea.netuix.events.Event;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class Listening extends AbstractJspBacking
{
   static final long serialVersionUID=1L;
   public void handlePortalEvent(HttpServletRequest request,
   HttpServletResponse response, Event event)
   {
      String attributeId= this.getPortletInstanceLabel(request) +       "_minimizeEventHandled";

   // NB: Use the HttpSession to pass data between lifecycle phases
   // (that is, to the pre-render phase). Passing data between
   //     backing file callback methods using the HttpRequest or static
   //     instance variables should be avoided.
   // The portlet instance label is used to create a unique
   //     attribute name for the session attribute.

      request.getSession().setAttribute(attributeId, "minimized!");
   }
   public boolean preRender(HttpServletRequest request, HttpServletResponse
   response)
   {
      String attributeId= this.getPortletInstanceLabel(request) +
      "_minimizeEventHandled";

         if (request.getSession().getAttribute(attributeId) != null)
         {
            // Reset the session flag
             request.getSession().removeAttribute(attributeId);

            // Pass minimize event notification to the JSP via the request.
            request.setAttribute("minimizeEvent", "Minimize event handled");
         }
         else
         {
            request.setAttribute("minimizeEvent", null);
         }

      return true;
   }

   private String getPortletInstanceLabel(HttpServletRequest request)
   {
      PortletBackingContext context=
      PortletBackingContext.getPortletBackingContext(request);
      return context.getInstanceLabel();
   }
}

Figure 7-9 shows the top portion of the Listening.java file as it should look after you paste the code into it.

Attach the Backing File

Now you will attach the backing file created in the previous section to bPortlet.portlet. Perform the following steps:

Add the Event Handler to bPortlet

You now add the event handler to bPortlet.portlet. This handler will be set up so that it will listen for an event on a specific portlet and fire an action in response to that event. To add the event handler, perform the following steps:

Test the Project

Test the communication between your portlets by following these steps:

Summary

In this example, you set up your environment and you added two JSP portlets to a local portal. One portlet, aPortlet, was fairly simple, while the second portlet, bPortlet, surfaced a more complex JSP file, used a backing file, and contained a portal event handler. When you tested the communication between the portlets, you observed how the bPortlet changed when an event occurred on aPortlet. This is called local interportlet communication.

IPC Special Considerations and Limitations

The following sections describe special considerations that you should keep in mind as you implement interportlet communications.

This section contains the following topics:

Using Asynchronous Portlet Rendering with IPC

Although IPC is not supported when asynchronous content rendering is enabled, WebLogic Portal provides some features that allow these two mechanisms to coexist in your portal environment. In addition, you can disable asynchronous rendering for single requests using the mechanisms described in Asynchronous Content Rendering and IPC.

Generic Event Handler for WSRP

Use a generic event handler to work with WebLogic Portal WSRP. To do this, first select Generic Event Handler, then select Add Action and select Window Mode|State. Then manually type in the event name—for example, onMinimize.

Consistency of the Listen To Field

Pay attention to the Listen To field when you set up the listener portlet. The portlet definition you use on the consumer must match the WSRP portlet's portlet definition. For example, if you have “portlet_2” listening to “portlet_1”, the WSRP portlet corresponding to “portlet_1”—the proxy on the consumer—must also have its portlet definition label set to “portlet_1”. For more information on using IPC with WSRP, refer to the Federation Guide.