Running JavaServer Faces Technology-Based Portlets on Sun Java System Portal Server 6 2005Q1

Print-friendly Version

By extending the framework based on JavaServer Faces technology, you can run within a portal application a Web application based on that technology, commonly called a portlet, that complies with Java Specification Request (JSR) 168: Portlet Specification. You can also display the portlet within a channel on your desktop portal.

In support of this capability, Sun Java System Application Server 8.1 (henceforth, Application Server) contains enhancements to the reference implementation of the JavaServer Faces 1.1 release for an improved integration with Sun Java System Portal Server.

In this article, we describe the setup procedures for running a JSR 168-compliant portlet developed with JavaServer Faces technology on Sun Java Portal Server 6 2005Q1 (henceforth, Portal Server), along with troubleshooting tips. At the end of this article are five appendixes: a pointer to a sample application, sample code, and bug descriptions.

This article assumes that you have installed Portal Server and deployed an application there.

Note: Technical support for deployment of portlets based on JavaServer Faces technology will be available for an upcoming release of Portal Server. At this time, that deployment capability is in an early-access phase and is recommended for evaluation and exploratory development only.

First, revise your application so that it complies with JSR 168. Follow these steps:

1. Create a portlet.xml source file.
   
   Your portlet's Web archive (WAR) file must include the contents of a portlet.xml file with the proper entries. For an example, see Appendix C. Be sure to set the first page of your portlet as the value for the <name> tag of the portlet's init parameter com.sun.faces.portlet.INIT_VIEW.
   
   
2. Download the jsf-portlet.jar file, which is part of javaserverfaces_portlet.class, and place the file in the application directory.
   
   jsf-portlet.jar is the portlet integration library that must reside with your application in the WEB-INF/lib subdirectory. That way, your application can run as a portlet.
   
   Alternatively, you can append the location of jsf-portlet.jar to the container's class path. However, the portlet then depends on the deployment setting in the container and may not be entirely self-contained.
   
   Appendix B describes the known bugs in jsf-portlet.jar.
   
   

You're now ready to deploy the portlets, packaged as a WAR file. Here is an example of the command line (all on one line):

% pdeploy deploy -u "uid=amAdmin,ou=People,dc=sun,dc=com" -w amAdminPasswd -p webserverAdminPasswd -v -d "dc=india,dc=sun,dc=com" WAR_file_directory

Verify that the deployment is successful: Check the Sun Java System Access Manager (henceforth, Access Manager) console (amconsole) or the deployment location to ensure that the portlets are ready for display on new channels.

Follow this procedure to create a channel for your portlet:

1. Log in to Access Manager as amAdmin.
   
   
2. Click the Identity Management tab.
   
   
3. Choose Services from the View drop-down menu at the top of the left pane.
   
   Access Manager displays a Services list below.
   
   
4. From the list, select Portal Desktop under PortalServer configuration. On the right pane, click the link Manage Channels and Containers.
   
   
5. Under Channels, click New Portlet Channel.
   
   
6. Type a channel name and choose your portlet from the drop-down list.
   
   If the list does not show the name of your portlet, that means the deployment process as described in the preceding section failed.
   
   
7. Add the new channel to one of the containers. To do so, first click MyFrontPageTabPanelContainer for a list of the channels. Select the new channel and click Add.
   
   Access Manager adds the channel under Available and Visible.
   
   
8. Click Save.
   
   

Now, verify that the new channel runs as a portlet on your desktop portal. Go to your portal at http://hostname:portnumber/portal/dt and log in with your user ID and password.

The portlet should be running in the appropriate container along with the other portlets. If you followed the preceding procedure and added the portlet to MyFrontPageTabPanelContainer, it runs under the MyFrontPage tab.

For convenience, you may wish to redirect the log messages from your application to your Web server log. Do the following:

1. Go to the Web server console at http://localhost:8888/ and log in with the administrator's ID and password.
   
   
2. Select your server, click Manage, and then click the Java tab.
   
   
3. Select JVM Options. In the text field, type the following (all on one line as one string, no spaces):
   
   Dorg.apache.commons.logging.Log=org.apache.commons.logging. impl.Jdk14Logger
   
   
4. Click Add.

By default, the log level is set to info. To change the default, edit the server.xml file in the config directory of the server instance and change the value of the loglevel attribute, for example, to finest.

Note that with the log level set at finest, the server may take a while to start. In normal circumstances, leave the default level of info as is.

If your portlet does not show up on the desktop portal, verify the following:

• The jsf-portlet.jar file is in the application directory or in the class path for Application Server and Web server.
  
  
• The configurations for the web.xml file are correct.
  
  
• The WAR file includes the content of the portlet.xml file and the configurations for WAR are correct.

To obtain a sample application and a sample portlet based on the JavaServer Faces interface, do the following:

1. Download javaserverfaces_portlet.class from the javaserverfaces Project Document and Files site at java.net.
   
   
2. Type this command line to extract the jsf-portlet.zip file:
   
   % java -cp . javaserverfaces_portlet
   
   
3. Type this command line to unzip the jsf-portlet.zip file:
   
   % unzip jsf-portlet.zip

Under the samples directory is the portlet-guessNumber.war file, which you can then deploy and run in Portal Server. To customize your application, follow the sample application's template and simply copy over the portlet.xml and web.xml files.

Note these two bugs in the portlet integration library (jsf-portlet.jar):

• A duplicate component ID exists in View mode.
  
  
• You cannot implement portlet modes and display of the JavaServer Faces framework-based JavaServer Pages (JSP) pages with the portlet library.
  
  Typically, you would implement a portlet's Edit, View, and Help modes by overriding the doEdit(), doView(), and doHelp() methods of the javax.portlet.GenericPortlet class. However, a portlet based on the JavaServer Faces interface does not support this process; hence, only the View mode works in that portlet.

Below are the contents of a sample portlet.xml file of a JavaServer Faces interface-based portlet.

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

        <portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class>

        <init-param>
          <description>Portlet init 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>

Below are the contents of a sample web.xml file of a JavaServer Faces interface-based portlet.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//
EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
    <display-name>JavaServer Faces Guess Number Sample Application</displayname>
    <description>
        JavaServer Faces Guess Number Sample Application
    </description>

    <context-param>

        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</param-value>
    </context-param>
	
    <context-param>
        <param-name>javax.faces.application.CONFIG_FILES</param-name>

        <param-value>/WEB-INF/faces-config.xml</param-value>
    </context-param>
	
    <context-param>
        <param-name>com.sun.faces.validateXml</param-name>
        <param-value>true</param-value>

    </context-param>
	
    <!-- Faces Servlet -->
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>

        <load-on-startup> 1 </load-on-startup>
    </servlet>

    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>

        <url-pattern>/guess/*</url-pattern>
    </servlet-mapping>
	
<security-constraint>
    <!-- This security constraint illustrates how JSP pages
            with JavaServer Faces components can be protected from
            being accessed without going through the Faces Servlet.
            The security constraint ensures that the Faces Servlet will
            be used or the pages will not be processed. -->
    <display-name>Restrict access to JSP pages</display-name>

    <web-resource-collection>
            <web-resource-name>
        Restrict access to JSP pages
            </web-resource-name>
        <url-pattern>/greeting.jsp</url-pattern>
        <url-pattern>/response.jsp</url-pattern>

    </web-resource-collection>
    <auth-constraint>
        <description>
        With no roles defined, no access granted
        </description>
    </auth-constraint>
    </security-constraint>

	
</web-app>

Following is a list of the classes that have been added as part of the jsf-portlet.jar file in the JavaServer Faces 1.1 framework. Recall that this file is the portlet integration library that runs on top of JavaServer Faces 1.1 interface. With these classes, the JavaServer Faces application runs as a portlet within the portlet container.

FacesContextFactoryImpl  PortletRequestMap
FacesPortlet             PortletRequestHeaderMap
FacesPortletState        PortletRequestParameterMap
LifeCycleFactoryImpl     PortletSessionMap
PortletApplicationMap    ViewHandlerImpl

The classes in jsf-portlet.jar, which are documented in the specification for JavaServer Faces technology, play the same role in the portlet environment as they do in the servlet environment. In the portlet environment, the RenderResponsePhase phase of the JavaServer Faces life cycle is executed when you call the portlet's render() method. The rest of the phases--RestoreViewPhase, ApplyRequestValuesPhase, ProcessValidationsPhase, and UpdateModelValuesPhase--are executed when you call the action() method.

To learn how to develop a JavaServer Faces framework, see the J2EE 1.4 Tutorial.

• JavaServer Faces technology
  
  
• Java Specification Request (JSR) 168: Portlet Specification
  
  
• Sun Java System Portal Server
  • Main page
  • Developer home
    
    
• Sun Java System Application Server
  • Main page
  • Developer home
    
    
• Sun Java System Access Manager
  • Main page
  • Developer home

Vishwas Soman, a staff engineer at Sun's India Engineering Center (IEC) in Bangalore, has been a member of the Sun Java System Portal Server development team since April 2004. Currently, he's focusing on the integration of JavaServer Faces and Struts technologies with Portal Server and on interportlet communications.

Jayashri Visvanathan, a member of technical staff at Sun, currently leads the reference-implementation effort for JavaServer Faces technology. She has also contributed to the development of various client-side and server-side Web technologies, including Mozilla, WebTop Registry Server, and HotJava Browser.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena.