Configuring JSF 1.2 to run on the Google App Engine

This tutorial will guide users through the process of developing a JavaServer Faces application using Sun Microsystem's reference implementation of the 1.2 specification.

Software Requirements

Required Software
In order to build a JavaServer Faces 1.2 application and have it run on the Google App Engine platform, you will need to have the following software downloaded and installed locally.
* If you will be using the Google Plugin for Eclipse, you do not need to download and install the AppEngine SDK from Google's web site as it is included in the download for the plugin.

Optional Software

The following software packages are optional and were used in the course of composing this tutorial.

Pre-Configuration Steps

  1. Download and install Eclipse SDK 3.5.
  2. Follow the instructions outlined on the "Quick Start" page to install the Google Plugin for Eclipse.
  3. Download the Facelets 1.1.14 (, Sun Java ServerFaces 1.2 Update 13 framework (, and Unified Expression Language (API & Implementation).  Uncompress the archives on your local hard disk drive.

Creating a New Project

  1. From the 'New' sub-menu on the 'File' menu, select the "Google Web Application Project".

  2. Give your project a name in the 'Project Name' field.  For the purposes of this tutorial, we will use "Google AppEngine JSF 1.2 Examples".
  3. Remove the check mark from the 'Use Google Web Toolkit' box in the "Google SDKs" portion of the dialog.
  4. Ensure the "Use Google App Engine" option has a check mark beside it.
  5. Left-click on the 'Finish' button.

Importing the JavaServer Faces and Facelets Libraries

Facelets 1.1.14

  1. In the "Project Explorer" tab, located on the left side of your IDE, expand your project and navigate to and left-click on the WEB-INF/lib directory.

  2. Left-click on the 'File' menu and select the 'Import...' menu item.
  3. When presented with the "Import" dialog, left-click on the 'File System' item under the "General" option.

  4. Left-click on the 'Next' button.
  5. Left-click on the 'Browse...' button and select the folder on your local hard disk drive into which you unpacked the contents of the archive downloaded in step 3.  When you have selected the directory, left-click on the 'Open' button.

  6. Left-click on the jsf-facelets.jar file (as shown in the figure above) and then left-click on the 'Finish' button.

JavaServer Faces 1.2 Reference Implementation

  1. Repeat steps 10 - 14 above for the el-api-1.1.jar and el-impl-1.1.jar Java archive files which comprise the 1.1 release of the Unified Expression Language which you downloaded as part of step 3.
  2. Repeat steps 10 - 14 above for the jsf-api.jar and jsf-impl.jar files from the <JSF_1.2-13>/lib directory from the archive of update 13 of Sun's reference implementation of the JavaServer Faces 1.2 specification (which you also downloaded as part of step 3).
  3. At this point, the WEB-INF/lib directory of your project should look similar to what is depicted in the "Package Explorer" screenshot shown below.

  4. The next step in our project configuration will be to edit the appengine-web.xml file found in the WEB-INF directory of the project to allow the web application to store data in the session created for clients visiting our site.  Add the <sessions-enabled>true</sessions-enabled> line as shown below.

    <?xml version="1.0" encoding="utf-8"?>
    <appengine-web-app xmlns="">
    <!-- Configure java.util.logging -->
    <property name="java.util.logging.config.file" value="WEB-INF/"/>

    1. Do not forget to modify the contents of the <application> tag to reflect the name of your App Engine project.
    2. Save the changes to the appengine-web.xml file and close it. 
    3. Left double-click on the web.xml file found in the WEB-INF directory of the project.  Replace the contents of the file with what is shown below.

      <?xml version="1.0" encoding="utf-8"?>

      <web-app xmlns:xsi=""





         <!-- Use Documents Saved as *.xhtml -->





            <!-- Special Debug Output for Development -->





         <!-- Optional JSF-RI Parameters to Help Debug -->









         <!-- GAE Bug 1506 JSP 2.1 API but 2.0 Implementation -->





         <!-- JSF RI Issue 1709 Mojarra deployment fails in Google App Engine -->





         <!-- Faces Servlet -->


            <servlet-name>Faces Servlet</servlet-name>




         <!-- Faces Servlet Mapping -->


            <servlet-name>Faces Servlet</servlet-name>







    4. Save changes to the web.xml file and close it.
    5. In the "Package Explorer" window, left-click on the WEB-INF directory.  Then left-click on the 'File' menu, select the 'New' sub-menu and left-click on the 'File' menu item.

    6. When presented with the "New File" dialog, type in faces-config.xml in the 'File name:' filed and then left-click on the 'Finish' button.

    7. Add the following content to the newly created faces-config.xml file that was opened for editing.


    8. Save your changes to the faces-config.xml file.
    9. Locate and right-click on the index.html file in the war directory shown in the "Package Explorer" window.
    10. When the context-sensitive menu is displayed, left-click on the 'Rename...' menu item found on the 'Refactor' sub-menu.

    11. When presented with the "Rename Resource" dialog, ensure the 'New name:' field indicates the index.html file should be renamed to index.jsp.

    12. Left-click on the 'OK' button to complete the file rename operation.
    13. The next step in the process will be to modify the index.jsp file which is defined in the web.xml (step 21) as the initial page that will be loaded by the Google App Engine when someone visits your site.  As  described in the "Avoid Redirects" section of Yahoo!'s "Best Practices for Speeding Up Your Web Site", we are going to modify the index.jsp to send a redirect to the browser rather than leverage an <meta http-equiv="Refresh" content="0,welcome.jsf"/> tag in the <head> of an HTML document.  Using the method prescribed below will ensure that the browser's "back" button will continue to function properly.
    14. Replace the contents of the index.jsp file with the following:

            <title>Initial Redirect Page</title>
            <% response.sendRedirect("welcome.jsf"); %>

      NOTE: If you decide to use a page other than welcome.xhtml as your initial landing page, please make the appropriate change to the welcome.jsf shown above.
    15. Save your changes to the index.jsp and close the file.
    16. In the "Package Explorer" window, left-click on the war directory.  Then left-click on the 'File' menu, select the 'New' sub-menu and left-click on the 'File' menu item.
    17. When presented with the "New File" dialog, type in welcome.xhml in the 'File name:' filed and then left-click on the 'Finish' button.
    18. Left double-click on the newly created welcome.xhml file and add the following content:

      <!DOCTYPE html 

           PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"


      <html xmlns="" xml:lang="en" lang="en"




         <h:head id="head">

            <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

            <title>Welcome to JSF 1.2 on the Google App Engine!</title>


         <h:body id="body">

            <f:view contentType="text/html">

               <p><h:outputText value="You are now up and running with JavaServer Faces 1.2 on the Google App Engine."/></p>




      NOTE: The first three lines of the file above instruct web browsers to interpret this document as a well-formed XHTML document.  As described in the "The !DOCTYPE  'Switch'" section of the MSDN article entitled "CSS Enhancements in Internet Explorer 6", this text instructs versions of Internet Explorer 6 and greater to switch on standards compliance mode.


    Copyright © 2001-2012, Wildstar Technologies, LLC.