This article, the fifth in a series, describes the design and binary of the Portlet Bridge, the procedure for modifying JSF applications to comply with JSR 168, as illustrated by a sample application, and the Portlet Bridge's tag library.

The JSF Portlet Bridge provides portlet-specific implementation for the following classes or interfaces of the JSF Framework:

javax.faces.context.FacesContextFactory

javax.faces.context.FacesContext

javax.faces.lifecycle.LifecycleFactory

javax.faces.lifecycle.Lifecycle

javax.faces.context.ExternalContext

javax.faces.application.ViewHandler

As documented in the JSF specification, the preceding six classes in the JSF Portlet Bridge play the same role in the portlet environment as they do in the servlet environment, as follows:

In the portlet environment, when you call a portlet's render() method, you execute RenderResponsePhase of the JSF life cycle. When you call the action() method, you execute the other four phases: RestoreViewPhase, ApplyRequestValuesPhase, ProcessValidationsPhase, and UpdateModelValuesPhase. Since you can call render() without the action being performed on the portlet, the JSF Portlet Bridge manages multiple render requests by storing the Faces View in the portlet session during the action life cycle and retrieving it during the render life cycle of the portlet.

Binary

Because the JSF 1.1 and 1.2 releases are significantly different, the JSF Portlet Bridge binary has two versions, each supporting a JSF release:

JSF Portlet Bridge 1.1  Supports JSF 1.1. If the Web container on which the Portlet Container is running does not support JSF technology or supports JSF 1.1 only, use this 1.1 binary.

To deploy JSF technology-based applications as portlets in Sun Java System Portal Server 7 or Pluto, the reference implementation of the Java Portlet Specification, use this 1.1 binary.

JSF Portlet Bridge 1.2  Supports JSF 1.2. If the Web container on which the portlet container is deployed supports JSF 1.2, use this 1.2 binary.

To enable a JSF application to comply with JSR 168, modify the application before running it as a portlet. The portlet framework requires a deployment descriptor and imposes restrictions on the markup fragment. That framework also introduces the concept of three modes: VIEW, EDIT, and HELP, all supported by the JSF Portlet Bridge.

In the faces-config.xml file, set the navigation rule so that when EDIT is successful or cancelled, the <to-view-id> tag points to the first view page (for example, greetings.jsp) of your portlet, that is, the page tagged com.sun.faces.portlet.INIT_VIEW. See this example:

The Edit page can also have a navigation rule. However, success on the final page must point to the first view page.

To give the user the choice of cancelling EDIT mode and return to VIEW mode, set up a a Cancel button on the Edit page. Here, point cancel to the first view page.

Set the HELP capability for the JSF portlet: In the portlet.xml file, point the portlet parameter com.sun.faces.portlet.INIT_HELP to the Help page (for example, help.jsp) of your portlet. See this example:

To display the Edit page, as shown in Figure 2, click the Edit icon, denoted by a pen.

Figure 2: Edit Window

To display the Help page, as shown in Figure 3, click the Help icon, denoted by a question mark.

Figure 3: Help Page

Tag Library

The tag library ( jsf-portlet.tld) contains tags for the JSF components in the portal environmentcomponents that are not part of the standard JSF specification. To have multiple instances of the same portlet reside on the same portal page, embed the portlet's JSF tags within a tag. Here is the syntax: