Chapter 9 Deploying JSF Application as a Portlet in Portal Server

This chapter describes how to deploy any existing JSF application as a JSR168 portlet in Portal Server. Using the steps mentioned in this document, the entire JSF application can be displayed within a channel on the portal server desktop. It contains the following sections:

Overview

This section contains the following:

Introduction

A jsf-portlet.jar file is included with the Portal Server to enable communication between the Portal Server and JSF. This component allows the execution of commands (to render the information, to perform actions like EDIT, HELP) received from Portal Server and pass the data (such as user defined parameters, or user input in general) to the JSF-based web application and/or to Portal Server.

State Information and High Availability

The JSF application embedded in a JSF portlet can view all user interactions with the portal page that are outside the user interface for the JSF portlet itself as if they were page reloads. The JSF Portlet maintains whatever state information is needed by the JSF application as other pages are selected or while the user interacts with the portal in other ways. The JSF portlet leverages the portlet container HTTP session failover capabilities to enable highly available JSF applications within portlets.

Accessing Portlet APIs

Developers can access the portlet APIs from the FacesContext object as shown here:

FacesContext facesContext = FacesContext.getCurrentInstance();
PortletRequest pRequest = (PortletRequest)facesContext.getExternalContext().getRequest();

To find the portlet window state (like Maximize and Normalize), do the following:

WindowState windowState = pRequest.getWindowState();

Mapping Actions of JSF Application to Portal Application and Vice-Versa

Table 9–1 JSF to Portal Mapping


When the JSF Application	On the Portal
Execute any action in the application	The `processAction()` method of JSF Portlet is called which calls the `execute()` method of JSF Lifecycle. Then the `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and returns content using `PortletRequestDispatcher.include()`.
Executing the action results in a error	The `processAction()` method of JSF Portlet is called which calls the `execute()` method of JSF Lifecycle. Then `render()` method of JSF Portlet is called which calls the `render()` method of JSF Lifecycle and returns the error message using `PortletRequestDispatcher.include()`.
The scope of the JSF Component or backing beans is request	When a JSF application is running in a servlet environment, the JSF request begins and ends within the scope of a servlet request (a user request). However, when a JSF application is running in a portlet environment, the JSF request lifecycle is split in two portlet requests. All JSF lifecycle phases but render happen during the portlet processAction request, with the JSF lifecycle render phase happening during the portlet render request.

Table 9–2 Portal to JSF Mapping


On a Portal	The JSF Application
Click on a JSF portlet Edit button	Edit page is displayed if portlet init parameter `com.sun.faces.portlet.INIT_EDIT` is set to the edit page; otherwise, a message indicating what needs to be done is displayed.
Click on a JSF portlet Help button	Help page is displayed if portlet init parameter `com.sun.faces.portlet.INIT_HELP` is set to the help page; otherwise, a message indicating what needs to be done is displayed.
Click on a JSF portlet Maximize button	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. Therefore, the maximize window displays the same context which were shown on portlet window before clicking maximize button.
Click on a JSF portlet Minimize button	Request is handled at the portlet level and the JSF application remains unaware of it. The desktop displays the minimized window as it displays for any other JSR 168 portlet.
Click on a Normalize button of the minimized JSF portlet	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. Therefore, the normalized window displays the same content which was shown on portlet window before clicking the minimize button.
Click on a JSF portlet Detach button	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. Portal server uses this content to display in a new window. Therefore, the detached window displays the same content which was shown on portlet window before clicking the detach button.
After detaching, click on a JSF portlet Attach button	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. Portal server uses this content to display in the portlet window. The content shown is same as was shown in the detached window before clicking the attach button.
Remove the JSF portlet from a page and then add it again	On removal, the request is handled at the portal/portlet level and on adding it again, the `render()` method is called. The jsf-portlet window displays the same content which was shown on portlet window before removing this portlet (that is, the state is maintained). The remove and add have to occur in the same login session while the same `DesktopContext` object exists. For example, if the desktop session reap interval setting is set low enough (say 30 second), and you remove a JSF portlet, then wait 2 minutes and then add it again, the state will be lost.
Click reload of the portal page	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. The jsf-portlet window displays the same content which was shown on portlet window before clicking the reload button.
Click on another tab and then click back on the tab that contains the JSF portlet	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. The jsf-portlet window displays the same content which was shown on portlet window before clicking on other tab.
Click on the Finish button of the edit page of some other channel, thereby causing a refresh of the portal page containing the JSF portlet	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. Therefore, the jsf-portlet window displays the same content which was shown on portlet window before clicking the edit button.
Execute any action on some other channel, thereby causing the portal page containing JSF portlet to be refreshed	The `render()` method of JSF Portlet is called which calls the render method of JSF Lifecycle and it returns content using `PortletRequestDispatcher.include()`. The jsf-portlet window displays the same content which was shown on portlet window before executing any action on some other channel.

Converting JSF-based Applications to JSF Aware Portlets in Portal Server

To Convert JSF-based Applications to Portlets

Steps

Copy jsf-portlet.jar from PortalServer7–base/lib directory to WEB-INF/lib directory of the application.

Add a new deployment descriptor for the portlet by creating a portlet.xml file.

The portlet.xml file must placed in the WEB-INF directory of the application.

In the portlet.xml file, set the portlet parameter com.sun.faces.portlet.INIT_VIEW to point to the first page of your portlet.

Modify the JSP pages as follows:
1. Remove the <html>, <head>, and <body> tags.
2. Modify use of forward and redirect as the new page will replace the existing portal pages.
3. Remove all the HTML tags and Javascript calls which are not allowed (as per JSR168 specification).

(Optional) Set the portlet parameter com.sun.faces.portlet.INIT_EDIT to point to the edit page of your portlet in the portlet.xml file to provide EDIT functionality for the JSF portlet.

(Optional) Set the portlet parameter com.sun.faces.portlet.INIT_HELP to point to the help page of your portlet in the portlet.xml file to provide HTLP functionality for the JSF portlet.

Deploy the WAR file using the psadmin deploy-portlet command. For example, type psadmin deploy-portlet -u amadmin -f passwordfile -v -d dn -p portalID -i instanceID warfile.

Create a new portlet channel and add it to the desired container.

上一页: 8. Deploying Struts Application as a Portlet in Portal Server