Open-Source Portal Initiative at Sun, Part 5: JavaServer Faces Technology-Based Portlet Bridge

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.

See also the other four parts of this series:

• Open-Source Portal Initiative at Sun, Part 1: Overview
• Open-Source Portal Initiative at Sun, Part 2: Portlet Repository
• Open-Source Portal Initiative at Sun, Part 3: Portlet Container
• Open-Source Portal Initiative at Sun, Part 4: Web Services for Remote Portlets

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

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.

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 deploy JSF technology-based applications as portlets in OpenPortal Portlet Container, which runs on GlassFish, 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.

Process
Modify your JSF application as follows:

1. Download the appropriate JSF Portlet Bridge binary ( jsf-portlet.jar) and copy it to the WEB-INF/lib directory of the JSF application.
   
   
2. Add a deployment descriptor for the portlet by creating a portlet.xml file in the WEB-INF directory of the application. In that file—
   
   
   1. Set portlet-class to com.sun.faces.portlet.FacesPortlet.
      
      
   2. Point the portlet parameter com.sun.faces.portlet.INIT_VIEW to the first page of the JSF application, for example, greetings.jsp.
   
   Here is the content of the portlet.xml file in the sample application ( guessnumberportlet), described in the next subsection:
   
   

   <?xml version="1.0" encoding="UTF-8"?> <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"> <portlet> <description>JSF GuessNumber Portlet</description> <portlet-name>guessnumber</portlet-name> <display-name>JSF GuessNumber Portlet</display-name> <!-- You must use this Portlet implementation class --> < portlet-class>com.sun.faces.portlet.FacesPortlet </portlet-class> <!-- This is a required parameter and must point to the first page of the JSF application --> <init-param> <description>Portlet init view page</description> <name>com.sun.faces.portlet.INIT_VIEW</name> <value>/greeting.jsp</value> </init-param> <supports> <mime-type>text/html</mime-type> <portlet-mode>VIEW</portlet-mode> <portlet-mode>EDIT</portlet-mode> <portlet-mode>HELP</portlet-mode> </supports> <portlet-info> <title>GuessNumber Portlet</title> <short-title>guessNumber</short-title> </portlet-info> </portlet> </portlet-app>

    
   
3. Set the EDIT capability for the JSF portlet:
   
   
   1. In the portlet.xml file, point the portlet parameter com.sun.faces.portlet.INIT_EDIT to the edit page (for example, edit.jsp) of your portlet. See this example:
      
      

      <init-param> <description>Portlet edit page</description> <name>com.sun.faces.portlet.INIT_EDIT</name> <value>/edit.jsp</value> </init-param>

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

      <navigation-rule> <from-view-id>/edit.jsp</from-view-id> <navigation-case> <from-outcome>success</from-outcome> <to-view-id>/greeting.jsp</to-view-id> </navigation-case> </navigation-rule> <navigation-rule> <from-view-id>/edit.jsp</from-view-id> <navigation-case> <from-outcome>cancel</from-outcome> <to-view-id>/greeting.jsp</to-view-id> </navigation-case> </navigation-rule>

       
      
   Note the following:
   
   
   • 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.
   
   
4. 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:
   
   

   <init-param> <description>Portlet init help page</description> <name>com.sun.faces.portlet.INIT_HELP</name> <value>/help.jsp</value> </init-param>

    
   
5. Revise the JSP pages:
   
   
   1. Delete the <html>, <head>, and <body> tags.
      
      
   2. Update forward and redirect. The new page will replace the existing portal pages.
   
   Note: Avoid coding in the JavaScript scripting language: Portlets only minimally support client-side scripts such as those in JavaScript.
   
   
6. Deploy the Web archive (WAR) file to your portal server.

Sample Application
As an illustration, here is a sample application, compressed as a ZIP file. Download the guessnumberportlet.war file and then deploy and run it in the OpenPortal Portlet Container.

Figure 1 shows the GuessNumber Portlet in the OpenPortal Portlet Container.

Figure 1: GuessNumber Portlet

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

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:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://java.sun.com/jsf/portlet/components" prefix="p" %>

See this example:

<%--
Embed JSF tags within portletPage tag to enable multiple instances of this portlet to reside on
the same portal page.
--%>

<f:view>
<p:portletPage>
.....................
.....................
</p:portletPage>
</f:view>

You can find the tag library at these two locations:

• The jsf-portlet/src/java/com/sun/faces/portlet directory in the source
• The META-INF directory in the Java archive ( jsf-portlet.jar)

• Open-source portal-related projects
  • OpenPortal
  • Portlet Repository
  • Portlet Container
  • WSRP
  • JavaServerFaces Technology-Based Portlet Bridge
  • NetBeans Portal Pack
  
  
• Sun Java System Portal Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Java Application Platform SDK
  • Update 2
  • Update 3 Preview
  
  
• Weblogs and Community Wiki
  • The Portal Post
  • The Aquarium
  • Community Wiki
  
  
• Sun developer services
  • Support
  • Training and certification