Skip navigation.
Downloads | Product Documentation | Support

Interportlet Communication Guide

# Understanding Backing Files

In Sample 4: Non-Pageflow Portlet to Pageflow Portlet sample shown in Using the Interportlet Communication Samples, a "backing file"—`menuBacking.java`—is used. 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 2-1 illustrates the lifecycle of a backing file.

Figure 2-1 Backing File Lifecycle

On every request, the following occurs:

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

3. Next, all `preRender()` methods are called for all controls on an active (visible) page.
4. 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.
5. Finally, the `dispose()` method gets called on the backing file.

Note: `roadstead()` and `savviest()`, shown in Figure 2-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 2-1 is the backing file used in the Sample 4: Non-Pageflow Portlet to Pageflow Portlet example in Using the Interportlet Communication Samples. In this example, the `AbstractJspBacking` class is extended to provide the backing functionality required by the portlet.

Listing 2-1 Backing File Example

>     package portletToPortlet.pageFlowSelectionDisplayOnly.menu.backing;

>     import com.bea.netuix.nf.UIControl;
>     import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
>     import com.bea.netuix.servlets.controls.page.PageBackingContext;
>     import com.bea.netuix.servlets.controls.portlet.backing.PortletBackingContext;
>     import com.bea.netuix.servlets.controls.window.WindowMode;
>     import com.bea.p13n.management.ApplicationHelper;
>     import com.bea.wlw.netui.pageflow.ActionResolver;
>     import com.bea.wlw.netui.pageflow.ActionResult;
>     import com.bea.wlw.netui.pageflow.PageFlowUtils;
>     import com.bea.wlw.netui.pageflow.scoping.ScopedRequest;
>     import com.bea.wlw.netui.pageflow.scoping.ScopedResponse;
>     import com.bea.wlw.netui.pageflow.scoping.ScopedServletUtils;
>     import javax.servlet.ServletContext;
>     import javax.servlet.http.HttpServletRequest;
>     import javax.servlet.http.HttpServletResponse;
>     import java.util.List;
>     import java.util.ListIterator;

>     public class MenuBacking extends AbstractJspBacking
>     {

>        public boolean preRender(HttpServletRequest request, HttpServletResponse
>           response)
>        {
>           talkToPageFlowPortlet(request, response);
>           return true;
>        }

>        private void talkToPageFlowPortlet(HttpServletRequest request,
>           HttpServletResponse response)
>        {
>           //First, check to see if we should even do anything.
>           if ( request.getParameter("selectedItem") == null )
>              return;

>           //The servlet context is necessary for getting the scoped request.
>           ServletContext context = ApplicationHelper.getServletContext(request);

>           //Get the scoped request associated with the pageflow portlet we want to
>           //talk to.
>           ScopedRequest sRequest =
>                   ScopedServletUtils.getScopedRequest(request,
>                                                  "",
>                                                  context,
>                                                  "portlet_pfdo_display_
>                                                       instance");

>          //Likewise, get the scoped response.
>             ScopedResponse sResponse =
>                      ScopedServletUtils.getScopedResponse(response,
>                                                             sRequest);

>          //Using the pageflow utilities, get an ActionResolver. This object can have
>          //the pageflow execute certain actions.
>         ActionResolver resolver = PageFlowUtils.getCurrentActionResolver(sRequest);

>         try
>         {
>            //Set an attribute in the scoped request that the page flow can use.
>            sRequest.setAttribute("selectedItem",
>                request.getParameter("selectedItem"));

>            //Execute the "readSelection" action in the pageflow. The ActionResult
>            //object that is returned contains a URI that can be used to update the
>            //pageflow portlet's content. Although this method is called "lookup,"
>            //the action is actually executed.
>            ActionResult ar = resolver.lookup("readSelection",
>                                                context,
>                                                sRequest,
>                                                sResponse,
>                                        "portletToPortlet.pageFlowSelectionDisplayOnly.
>                                          selectionReader.
>                                                                        selectionReaderController");

>               //Now, the final step: Find the control for the page portlet, using
>               //its label, and update the current content uri for the pageflow
>                //portlet. To do this, we need to search threw all the window contexts
>               //until we find the portlet we're looking for.
>              PageBackingContext pbc =
>                  PageBackingContext.getPageBackingContext(request);
>                  ListIterator backingContexts =
>                      pbc.getWindowBackingContexts().listIterator();

>                  while ( backingContexts.hasNext() )
>                  {
>                      Object nextContext = backingContexts.next();
>                      if ( nextContext instanceof PortletBackingContext )
>                      {
>                          PortletBackingContext portletBC =
>                             PortletBackingContext)nextContext;
>                             if ( "portlet_pfdo_display_instance".
>                                  equals(portletBC.getLabel()) )
>                              {

>                             //Found it! Update the portlet with the uri from the
>                             //Action Result.
>                             WindowMode wm = portletBC.getWindowMode();
>                             wm.setCurrentContentUri(ar.getURI());
>                              break;

>                         }
>                    }
>              }
>        }

>        catch ( Exception e )
>        {
>             e.printStackTrace();
>         }

>       }

>     }

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

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. You cannot use the IDE to attach a backing file to a Java Page Flow portlet or to a Struts portlet. Instead, you will need to physically code it into the `.portlet` file, as described in Listing 2-2.

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

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

To add the backing file by coding it into a `.portlet` file, as required for Java Page Flow portlets and Struts portlets, use the `backingFile` parameter within the `<netuix:jspContent>` element, as shown in Listing 2-2.

Listing 2-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>