Using WSRP with WebLogic Portal

Establishing Interportlet Communications with Remote Portlets

WebLogic Portal 8.1 with service pack 4 supports interportlet communication (IPC) between Producers and Consumers. In other words, local portlets on a Consumer can react to events on a federated portlet from a Producer and vice versa; for example, minimizing a local portlet would change the contents of a remote portlet that was listening for a minimize event.

This document describes the IPC model used by WebLogic Portal and shows how to apply it to WSRP-compliant portlets. It includes information on the following subjects:

Note: For a list of supported portlets, please refer to WSRP Portlet Type Support in Introduction to WSRP.

The WebLogic Portal IPC Model

Earlier versions of WebLogic Portal allowed you to establish interportlet communications by using such techniques are adding listenTo() methods or backing files on page flow portlets. WebLogic Portal 8.1 with service pack 4 introduces a new IPC model based upon event handlers, Java objects that listen for predefined events on other portlets in the portal and fire actions when that event occurs.

Event Handlers

Event handlers "listen" for events raised on subscribed portlets and fire an action when a specific event is detected. Event handlers can listen and react to the following types of events:

Portal Event
Generic Event
Page Flow Event
Custom Event
Struts Event

Events

Event actions depend upon the type of event being raised. Except for portal events, all other events can be identified in the Events field on the Event Handler tool. Events available with the portal event handler are listed in Table 3-1.

Table 3-1 Events Available to a Portal Event Handler

This event...	Fires an action when the portlet...
onActivation	Becomes visible.
onDeactivation	Ceases to be visible.
onMinimize	Is minimized
onMaximize	Is maximized
onNormal	Returns to its normal state from either a maximized or minimized state
onDelete	Is deleted from the portal.
onHelp	Is in the help mode
onEdit	Is in the edit mode
onView	Is in the view mode
onRefresh	Is refreshed

Event Actions

Event handlers fire an action on the host portlet when that handler detects an event from another portlet in the application; 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 a backing file attached to it.

Table 3-2 lists the event actions available.

Table 3-2 Event Actions

This action...	Does this...
Change Window Mode	Changes the window's mode from its current mode to a user-specified mode; for example, from help mode to edit mode.
Change Window State	Changes the window's state from its current state to a user-specified state; for example, from maximized to delete state.
Activate Page	Opens a user-specified page.
Fire Generic Event	Fires a user-specified generic event.
Fire Custom Event	Fires a user-defined custom event. This event needs to be included in the portlet file.
Invoke BackingFile Method	Runs the backing file attached to the portlet. Backing files allow you to programatically add functionality to a portlet to enable preprocessing (for example, authentication) prior to rendering the portal controls. For more information, please refer to Special Considerations for Remote Portlets.

How IPC is Implemented

The IPC Tool included in WebLogic Workshop makes implementing event handlers relatively easy. To launch the tool, do the following:

Open a portlet in WebLogic Workshop.

In the Property Editor for that portlet, click the ellipses button (...) next to Event Handlers (if no event handlers have been added, the Event handler field will show that. If any event handlers have been added, the field will indicate the number added).

The tool will appear, as shown in Figure 3-1 Figure 3-1 Event Handler Tool

Click Add Handler to open the event handler drop-down menu and select a handler.

The dialog box will expand, opening up additional fields you can use to set up the handler (Figure 3-2). Figure 3-2 Expanded Event Handler Tool

The entire process of setting up an event handler can all be handled by using this tool. What you need to do is:

Select an event handler.

Determine the portlet(s) to which that handler will listen.

Select an event that the handler will listen for.

Select and configure an action to fire when the event occurs.

Save the event handler.

Implementing IPC with WSRP: Example

This section describes the process of setting up interportlet communications between a Consumer and a Producer by using the Event handler tool in BEA WebLogic Workshop. This is a simple example in which minimizing the local portlet on the Consumer will change the text string in the portlet federated from the Producer.

Note: Currently when a change is made to a producer's metadata, consumers are not notified of the change. For example, if you add an event handler to a portlet on the producer after you create a remote proxy to that portlet, the remote portlet is not made aware of the change: it will not fire the event. The correct procedure is to add the event handler to the portlet on the producer before you create the remote portlet on the consumer. This is a basic limitation of Web Services in general.

This exercise is comprised of four main steps:

Step 1: Set Up Your Environment

In this step, you will create a domain, an enterprise application, and two web applications (web projects) under the enterprise application.

Note: In this exercise, the root directory for your domain should be BEA_HOME\user_projects\domains; for the applications and all of their components, it's BEA_HOME\user_projects\applications. These are default directories that are created when you install BEA WebLogic Platform.

Create the Domain

To create a domain, do the following:

Launch WebLogic Workshop.

Open the Tools menu and select WebLogic Server>Configuration Wizard.

The Configuration Wizard launches.

Follow the prompts using the value specified in Table 3-3. Click Next when you are finished with each dialog box

Table 3-3 Configuration Wizard Values

On...	Select or Enter...
Create or Extend a Configuration	Create a new WebLogic Configuration
Select a Configuration Template	Basic WebLogic Portal Domain
Choose Express or Custom Configuration	Express
Configure Administrative Username and Password	Username: `weblogic` Password: `weblogic` Confirm Password: `weblogic`
Configure Server Start Mode and Java SDK	Sun SDK 1.4.2_05
Create WebLogic Configuration	Configuration Name:ipcWsrpDomain

Once the domain is created, click Done.

Create the Portal Application

To create a portal applications, do the following:

Open the File menu and select New>Application...

The New Application dialog box appears.

Select Portal Application and do the following:

In Name, enter ipcWsrpTest.
In Server, click Browse to display the Select WebLogic Server config.xml File dialog box. Navigate to the ipcWsrpDomain directory and select config.xml.

Click Create.

When the application is successfully created, it will appear in the application panel, as shown in Figure 3-3. Figure 3-3 Producer Portal Application Created

Create the Web Applications (Web Projects)

Create Producer and Consumer portal web applications (Projects) under the ipcWsrpTest portal application by doing the following:

In the file tree, right-click ipcWsrpTest and select New>Project...

The New Project dialog box appears.

Select Portal and Portal Web Project and in Name, enter producerWeb.

Click Create.

producerWeb will now appear under the ipcWsrpTest application in the application tree (Figure 3-4). Figure 3-4 Portal Web Application (Project) Added to the Producer

Repeat steps 1 through 3, this time entering consumerWeb in the Name field on the New Project dialog box.

When the web applications are successfully created, they will appear under ipcWsrpTest in the Application panel, as shown in Figure 3-5. Figure 3-5 Portal Web Applications (Projects) Added to the Portal Application

Start WebLogic Server by opening the Tools menu and selecting WebLogic Server>Start WebLogic Server.

Summary

With the completion of Step 1: Set Up Your Environment, you have created a domain, a portal applications, and two portal web applications, producerWeb (the Producer) and consumerWeb (the Consumer). You can verify that these components exist by looking in your file system at BEA_HOME\user_projects\, as shown in Figure 3-6.

Figure 3-6 File System Showing New Domain and Applications

File System Showing New Domain and Applications

Step 2: Create the Producer Portlets

In this step, you will create two JSP files on the Producer-side, along with the JSP portlets that will surface these files. You will also create a backing file that will contain the instructions necessary to complete the communication between two portlets (for more information on backing files, please refer to Understanding Backing Files) and add an event handler to one of the portlets. Once you have created the portlets and attached the backing file, you will test the application in your browser.

Note: Before continuing with this procedure, ensure that WebLogic Workshop is running and the producerWeb Web application node is expanded.

Create the JSP Files and Portlets

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

Under the producerWeb node, double-click index.jsp.

The JSP file opens in Design View (Figure 3-7). Figure 3-7 index.jsp in Design View

Click the phrase New Web Application Page to highlight it

A box will appear around the text and an inner text field will appear in the Property Editor, under General (Figure 3-8). Figure 3-8 Properties Menu inner Text Field

In the inner text field, click the ellipses button (...) to open the inner text dialog box and replace New Web Application Page with the phrase Minimize Me!!! Click OK.

The dialog box closes and Minimize Me!!! appears in the inner text field and in the Design View, as shown in Figure 3-9. Figure 3-9 New Text Added to the JSP File

Open the File menu and select Save As...

Save the file as aPortlet.jsp.

Right click aPortlet.jsp in the Application tree and select Generate Portlet... from the context menu (Figure 3-10).

Figure 3-10 Generating a Portlet from index.jsp

The Portal Details dialog box appears (Figure 3-11). Note that /aPortlet.jsp appears in the Content URI field. Figure 3-11 Portal Details Dialog Box for aPortlet

Select Minimizable, Maximizable, and Deletable and click Finish.

aPortlet.portlet will appear under producerWeb in the application tree.

When the Portlet Wizard closes, aPortlet.jsp should still be open. If it isn't, double-click it in the application tree to reopen it.

Open the File menu and select Save as.

In the Name field of the Save "aPortlet.jsp" as dialog box, enter bPortlet.jsp and click Save.

On the JSP display, click Source View.

The JSP code appears (Figure 3-12). Figure 3-12 JSP File Source View

Copy the code from Listing 3-1 into the JSP, replacing everything from <netui:html> through </netui:html>. This code displays event handling from the backing file that you will create and attach in a subsequent step.

Listing 3-1 New JSP Code for bPortlet.jsp

<netui:html>
   <% String event = (String)request.getAttribute("minimizeEvent");%>
      <head>
         <title>
            Web Application Page
         </title>
      </head>
      <body>
         <p>
            Listening for portlet A minimize event:<%=event%>
         </p>
      </body>
</netui:html>

The source should look like example in Figure 3-13. Figure 3-13 Updated JSP Source

Save the file either by clicking the save button or by opening the File menu and selecting Save.

Repeat steps 6 and 7 to create a JSP portlet for bPortlet.

Create the Backing File

To create the backing file, do the following:

In producerWeb, expand the WEB-INF node and right-click src to open a context menu.

Select New>Folder.

The Create New Folder dialog box appears.

In Enter a new folder name, type backing and click OK.

The folder backing will appear under WEB-INF/src, as shown in Figure 3-14. Figure 3-14 backing Folder Under WEB-INF/src o.

Right-click backing and select New>Java Class.

The New File dialog box appears.

In Name, enter Listening.java and click Create.

The Source View of the new Java class appears (Figure 3-15). Figure 3-15 Listening.java Source File

Copy the code from Listing 3-2 into Listening.java.

Listing 3-2 Backing File Code for listening.java

package backing;

import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
import com.bea.netuix.events.Event;
import com.bea.netuix.events.GenericEvent;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class Listening extends AbstractJspBacking

{ 
    private static boolean minimizeEventHandled = false;

     public void handlePortalEvent(HttpServletRequest request,
        HttpServletResponse response, Event event)

    {
        minimizeEventHandled = true;
    }

    public boolean preRender(HttpServletRequest request, HttpServletResponse
         response)
    {
        if (minimizeEventHandled){

                request.setAttribute("minimizeEvent","minimize event handled");
        }else{
                request.setAttribute("minimizeEvent",null);
        }

        // reset
        minimizeEventHandled = false;

         return true;
    }
}

The source should now look like that shown in Figure 3-16. Figure 3-16 Listening.java with Updated Backing File Code

Save Listening.java either by opening the File menu and selecting Save or clicking the save button.

Attach the Backing File

Now you will attach the backing file created in Create the Backing File to bPortlet. Do the following:

In the Application tree, double-click bPortlet.portlet to open it.

In the Property Editor, under Portlet Properties, type backing.Listening into the Backing File field, as shown in Figure 3-17 and press Tab.

Figure 3-17 Attaching the Backing File in the Property Editor

Save the file.

Add the Event Handler to bPortlet

You now add the event handler to bPortlet. 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, do the following:

Note: bPortlet.portlet should be displayed in WebLogic Workshop. If it isn't, locate it under producerWeb in the application panel and double-click it.

In the Property Editor, click the ellipses button (...) next to Event Handlers.

The Event Handler dialog box appears (Figure 3-18). Figure 3-18 Event Handler Dialog Box

Click Add Handler to open the Event Handler drop-down list.

Select Handle Portal Event.

The Event Handler dialog box expands to allow entry of more details (Figure 3-19). Figure 3-19 Event Handler Dialog Box Expanded

Accept the defaults for all fields except Portlet.

In Portlet, click the ellipses button (...).

The Open dialog box for producerWeb appears.

Double-click aPortlet.portlet.

The Open dialog box closes and Portal_1 appears in the Listen to: list and the Portlet field (Figure 3-20). Portal_1 is the definition label of the portlet to which the event handler will listen. Figure 3-20 Adding portlet_1

Click the Event drop-down control to open the list of portal events that the handler can listen for and select onMinimize, as shown in Figure 3-21.

Figure 3-21 Event Drop-down List

Click Add Action... to open the action drop-down list and select Invoke BackingFile Method, as shown in Figure 3-22

Figure 3-22 Add Action Drop-down List

Invoke BackingFile Method appears on the Events list as a child to Handle Portal Event, as shown in Figure 3-23. Figure 3-23 Event List with Action Added

Open the Method drop-down control and select handlePortalEvent (Figure 3-24).

Figure 3-24 Adding the Backing File Method

Click OK.

The event handler is added. Note that the Event Handler field in the Property Editor now reads "1 Event Handler."

Test the Application

To test the application, do the following:

Note: Before you begin, ensure that all files are saved.

Create a portal called ipcLocal.portal by doing the following:

Right-click producerWeb and select New>Portal.

In the New File dialog box's File Name field, enter ipcLocal.

Click Create.

When the portal is successfully created, its layout will appear in WebLogic Workshop.

Drag both aPortlet and bPortlet from the Data Palette onto the portal layout, as shown in Figure 3-25.

Figure 3-25 Portal Layout with Portlets Added

Save the portal either by clicking the save button or opening the file menu and selecting Save.

Open the Portal Menu and select Open Current Portal...

The portal will render in your browser (Figure 3-26). Figure 3-26 ipcLocal Portal in Browser

Minimize aPortlet.

Note the content change in bPortlet. Figure 3-27 ipcLocal Portal with aPortlet Minimized

Summary

In this step, you added to the portal application components created in Step 1: Set Up Your Environment two JSP portlets built on the Producer. One portlet, aPortlet, was fairly simple, while the second portlet, bPortlet, surfaced a more complex JSP file, leveraged a backing file, and contained a portal event handler. When you tested the Producer application, you observed how the two portlets communicated when an event occurred on aPortlet. This is called local interportlet communications.

Step 3: Create the Consumer Portlets

In this step, you will create two portlets on the Consumer, one a JSP portlet and the other a remote portlet. As in Step 2: Create the Producer Portlets, the JSP portlet will surface the aPortlet.jsp file while the remote portlet will consume bPortlet you created in Create the JSP Files and Portlets.

Set Up the Exercise

Before you continue with this exercise, do the following:

Ensure that WebLogic Workshop is open and WebLogic Server is running.
Go to your file system and copy aPortlet.jsp from:

BEA_HOME \user_projects\applications\ipcWsrpTest\producerWeb

to

BEA_HOME\user_projects\applications\ipcWsrpTest\consumerWeb.
Note: This step is necessary to streamline this exercise and because WebLogic Workshop does not allow you to copy files between folders. If you don't want to copy aPortlet.jsp from producerWeb to consumer Web, you can create it from scratch, as described in Create the JSP Files and Portlets.

Create the JSP Portlet

To create a the JSP portlet, do the following:

Right-click aPortlet.jsp and select Generate Portlet...

The Portlet Details dialog box appears, with /aPortlet.jsp already in the Content URI field (Figure 3-28). Figure 3-28 Portlet Details Dialog Box

Fill out the details as described here:

Minimizable: select
Maximizable: select
Deletable: select.

Click Finish.

WebLogic Workshop refreshes and the new portlet layout appears, as shown in Figure 3-29. Figure 3-29 New Portlet

Create the Remote Portlet

To create the remote portlet, do the following:

Right-click consumerWeb and select New>Portlet.

The New File dialog box appears.

In File Name, enter bPrime.portlet and click Create.

The Portlet Wizard is launched, showing the Select Portlet Type dialog box (Figure 3-28). Figure 3-30 Select Portlet Type Dialog Box

Select Remote Portlet and click Next.

The Find Producer/Select Producer dialog box appears (Figure 3-31). Figure 3-31 Find Producer/Select Producer Dialog Box

Select Find Producer and enter the producer's service description (Web Services Description Language, or WSDL) in the service description field. The WSDL communicates interface information between web service Producers and Consumers, allowing you to leverage a service's capabilities without possessing the source code for the service. For this exercise, enter:

http://localhost:7001/producerWeb/producer?WSDL

Click Retrieve.

After a few seconds, the dialog box refreshes, showing the Producer Details.

Click Register.

The Register dialog box appears (Figure 3-32). Figure 3-32 Register Dialog Box

In Producer Handle, enter myProducer and click Register.

The Find Producer dialog box reappears with myProducer in the Select Producer field.

Click Next.

The Select Portlet From List dialog box appears (Figure 3-33 Figure 3-33 Select Portlet From List Dialog Box

Select bPortlet and click Next.

The Proxy Portlet Details dialog box appears.

Click Finish.

The remote portlet will be created and will appear as bprime.portlet under consumerWeb in the Application panel.

In the Property Editor for bPortlet, set Render Cachable to False (Figure 3-34) and press Tab.

Figure 3-34 Setting Render Cachable Property to False

Save the portlet.

Summary

With the completion of the two Consumer portlets, you have now created all of the necessary components to demonstrate interportlet communications between a remote and a local portlet. In the next step, you will add the Consumer portlets to a Consumer portal and raise an event on one portlet that will cause a reaction on the other.

Step 4: Test the Application

In this step, you will test the Consumer application to verify that minimizing aPortlet will change the content of bPrime. You will create a portal and add the two portlets created in Step 3: Create the Consumer Portlets. You will then build the application and view the portal in a browser.

Build the Portal

To create a portal for testing the application, do the following:

Note: Ensure all files are saved.

Right-click consumerWeb and select New>Portal.

In the New File dialog box's File Name field, enter ipcConsumer.

Click Create.

When the portal is successfully created, its layout will appear in WebLogic Workshop.

Drag both aPortlet and bPortlet (which identifies bPrime) from the Data Palette onto the portal layout, as shown in Figure 3-35.

Figure 3-35 ipcConsumer Portal Layout

Save the portal.

Test the Portal

When the build completes, verify that an event on aPortlet can affect the content of bportlet by doing the following:

Open the Portal menu and select Open Current Portal.

A browser opens displaying the ipcConsumer portal (Figure 3-36). Figure 3-36 ipcConsumer Portal in a Browser

In aPortlet, click the minimize button.

aPortlet minimizes and the contents of bPortlet changes, as shown in Figure 3-37. Figure 3-37 ipsConsumer Portal in Browser After Minimize Event

Special Considerations for Remote Portlets

If an event has one or more events that must be handled by the Producer (for example., netuix:invokePageFlowAction, netuix:invokeStrutsAction, netuix:invokeJavaPortletMethod, and netuix:invokeBackingFileMethod), the Producers adds a dispatchToRemotePortlet() method. This element indicates that the Consumer must dispatch the event to the Producer.

Understanding Backing Files

The portal you created in Implementing IPC with WSRP: Example uses backing files to achieve communication between two portlets. Backing files allow you to programatically add functionality to a portlet by implementing (or extending) a Java class, which enables preprocessing (for example, authentication) prior to rendering the portal controls.

What are Backing Files?

Backing files are simple Java classes that implement the com.bea.netuix.servlets.controls.content.backing.JspBacking interface or extend the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking interface abstract class. The methods on the interface mimic the controls lifecycle methods (see How Backing Files are Executed) and are invoked at the same time the controls lifecycle methods are invoked.

Which Controls Support Backing Files?

At this time, the following controls support backing files:

Desktops
Books
Pages
Portlets

How Backing Files are Executed

All backing files are executed before and after the JSP is called. In its lifecycle, each backing file calls these methods:

init()
handlePostBackData()

raiseChangeEvents()

preRender()
dispose()

On every request, the following occurs:

All init() methods are called on all backing files on an "in order" basis (that is, in the order they appear in the tree). This method gets called whether or not the control (that is, portal, page, book, or desktop) is on an active page.

Next, if the operation is a postback and the control (a portlet, page, or book) is on a visible page, all handlePostbackData() methods are called. In other words if a portlet is on a page but its parent page is not active, then this method will not get called.

If _nfpb="true" is set in the request parameter of any handlePostbackData() methods called, raiseChangeEvents() is called. This method causes events to fire.

Next, all preRender() methods are called for all controls on an active (visible) page.

Next, the JSPs get called and are rendered on the active page by the <render:beginRender> JSP tag. Rendering is stopped with the <render:endRender> tag.

Finally, the dispose() method gets called on the backing file.

Thread Safety with Backing Files

A new instance of a backing file is created per request, so you don't have to worry about thread safety issues. New Java VMs are specially tuned for short-lived objects, so this is not the performance issues it once was in the past. Also, JspContent controls support a special type of backing file that allows you to specify whether or not the backing file is thread safe. If this value is set to true, only one instance of the backing file is created and shared across all requests.