Establishing Interportlet Communications

Understanding Backing Files

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. Backing files can be attached to portals either by using WebLogic Workshop or coding them directly into a .portlet file.

This section is primer on backing files. It includes information on the following subjects:

• What are Backing Files?
• Which Controls Support Backing Files?
• How Backing Files are Executed
• Thread Safety with Backing Files
• Creating a Backing File
• Adding a Backing File to a Portlet

 

---

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()

Figure 5-1 illustrates the lifecycle of a backing file.

Figure 5-1 Backing File Lifecycle

 

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 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.

Note: roadstead() and savviest(), shown in Figure 5-1 are part of the control lifecyle, not the backing file lifecycle.

Other Execution Notes

If the backing file is part of a floated portlet, when that portlet is floated, only its contents are executed.

If a book is embedded within a portlet, then the book would get called; however, if the book is the parent of the portlet then it would not get called as it is not contained within the portlet.

 

---

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.

 

---

Creating a Backing File

As previously discussed, a backing file must be an implementation of com.bea.netuix.servlets.controls.content.backing.JspBacking interface or an extension of the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking abstract class. You only need to modify these files as necessary to implement the backing functionality you desire.

Listing 5-1 is the backing file used in Establishing IPC by Using Custom and Page Flow Events In this example, the AbstractJspBacking class is extended to provide the backing functionality required by the portlet.

Listing 5-1 Backing File Example

package backing;

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

public class ListenCustomerName extends AbstractJspBacking
{
    public void listenCustomerName( HttpServletRequest request,
       HttpServletResponse response, Event event)
    {

        CustomEvent customEvent = (CustomEvent) event;
        
        String message = (String) customEvent.getPayload();

        HttpSession mySession = request.getSession();        

        mySession.setAttribute("customerName", message);

    }

} 

You should follow these guidelines when creating a backing file:

• Ensure netuix_servlet.jar is included in the in the project classpath, otherwise compilation errors will occur.
• When implementing the init() method, avoid any heavy processing.

 

---

Adding a Backing File to a Portlet

As a best practice, you should always store backing files in the web application's WEB-INF/src/backing directory, as the /src directory is the first place the application looks for a backing file (if you are storing the first backing file for a web application, you will need to create the /backing directory under WEB-INF/src).

Adding the Backing File by Using WebLogic Workshop

You can add a backing file to a portlet either from within WebLogic Workshop or by coding it directly into the file to which you are attaching it. For all other portlet types, simply specify the backing file in the Backing File field under the General Properties section of the Property Editor, as shown in Figure 5-2. You need to specify the backing directory and, following a dot-separator, just the backing file name. Do not include the backing file extension; for example enter this:

backing.ListenCustomerName

Not this:

backing.ListenCustomerName.java

If you include the file extension, the application will interpret is as the file name—because the file path is specified by a dot-separator—and look for a non-existent file called java in a non-existent directory called ListenCustomerName (or whatever your backing file is named).

Figure 5-2 Adding a Backing File by Using the IDE

 

Adding the Backing File Directly to the .portlet Code

To add the backing file by coding it into a .portlet file, use the backingFile parameter within the <netuix:jspContent> element, as shown in Listing 5-2.

Listing 5-2 Adding a Backing File to a .portlet File

<netuix:content>
   <netuix:jspContent
   backingFile="portletToPortlet.pageFlowSelectionDisplayOnly.menu.
      backing.MenuBacking"
   contentUri="/portletToPortlet/pageFlowSelectionDisplayOnly/menu/
      menu.jsp"/>
</netuix:content>