This tutorial will guide users through the process of developing and deploying a JavaServer Faces 2.0 application on the 1.6.6 version of Google's App Engine for Java using the 2.0.9 version of Oracle's implementation of the specification. The application built out in the course of writing this tutorial is available from http://jsf2template.wildstartech.com/. The source code is available from the jsf2template Google Code project.

Importing the Unified Expression Language Files

The following steps will guide you through the process of importing the files which provide support for the new Unified Expression Language.

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.

Left-click on the 'File' menu and select the 'Import...' menu item.

When presented with the "Import" dialog, left-click on the 'File System' item under the "General" option.

Left-click on the 'Next' button.

Left-click on the 'Browse...' button and select the folder on your local hard disk drive into which you downloaded the el-api-2.2.1-b04.jar and el-impl-2.2.1-b05.jar files from the Unified Expression Language java.net Maven 2 repository. When you have selected the directory, left-click on the 'Open' button. Select the two library files as depicted in the screenshot below and then left-click on the 'Finish' button.

Importing the JavaServer Faces Libraries

The following steps will guide you through the process of importing the files which provide support for the second release candidate of Oracle's implementation of the JSF 2.0 specification.

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.

Left-click on the 'File' menu and select the 'Import...' menu item.

When presented with the "Import" dialog, left-click on the 'File System' item under the "General" option.

Left-click on the 'Next' button.

Left-click on the 'Browse...' button and select the folder on your local hard disk drive into which you unpacked the mojarra-2.0.6-FCS-binary.zip archive.

Locate the lib folder and left-click on the 'Open' button. Place check marks beside the jsf-api.jar and jsf-impl.jar files and left-click on the 'Finish' button.

Configuration File Changes

appengine-web.xml

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. Add the <threadsafe>true</threadsafe> setting to instruct the App Engine runtime environment to allow a single Instance to service multiple requests concurrently.

Do not forget to modify the contents of the <application></application> tag to reflect the name of your App Engine project. Save the changes to the appengine-web.xml file and close it.

web.xml

Left double-click on the contents of the web.xml file found in the WEB-INF directory and replace the contents with what is shown below.

<?xmlversion="1.0"encoding="utf-8"?>

<web-appxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://java.sun.com/xml/ns/javaee"

xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"version="2.5">

<display-name>

Wildstar Technologies, LLC. Google AppEngine JSF 2.0 Template

</display-name>

<description>

Template JSF 2.0 application configured to run on the Google

AppEngine for Java.

</description>

<!-- ***** Designate server-side state saving. ***** -->

<context-param>

<param-name>javax.faces.STATE_SAVING_METHOD</param-name>

<param-value>server</param-value>

</context-param>

<context-param>

<param-name>javax.faces.DEFAULT_SUFFIX</param-name>

<param-value>.xhtml</param-value>

</context-param>

<context-param>

<param-name>com.sun.faces.expressionFactory</param-name>

<param-value>com.sun.el.ExpressionFactoryImpl</param-value>

</context-param>

<!-- Disable use of threading for single-threaded environments such as

the Google AppEngine. -->

<context-param>

<param-name>com.sun.faces.enableThreading</param-name>

<param-value>false</param-value>

<description>

When enabled, the runtime initialization and default ResourceHandler

implementation will use threads to perform their functions. Set this

value to false if threads aren't desired (as in the case of running

within the Google Application Engine).

Note that when this option is disabled, the ResourceHandler will not

pick up new versions of resources when ProjectStage is development.

</description>

</context-param>

<!-- ***** Load the JavaServer 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>

<servlet-mapping>

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

<url-pattern>/faces/*</url-pattern>

<url-pattern>*.jsf</url-pattern>

</servlet-mapping>

<!-- ***** Specify session timeout of thirty (30) minutes. ***** -->

<session-config>

<session-timeout>30</session-timeout>

</session-config>

<welcome-file-list>

<welcome-file>index.jsp</welcome-file>

<welcome-file>index.xhtml</welcome-file>

<welcome-file>index.html</welcome-file>

</welcome-file-list>

</web-app>

The com.sun.faces.enableThreading context parameter is set in the event you use the "Development" value for the javax.faces.PROJECT_STAGE context parameter. As indicated in the comments, setting com.sun.faces.enableThreading equal to false instructs the Mojarra implementation of the JSF 2 API to NOT attempt to use threads which is not allowed by the Google App Engine platform (as described in the "Sandbox" section of the "Java Servlet Environment" article on the Google App Engine documentation site.

Modifying the Web Application's Default Page

If your web project does not already contain an index.html file in the war directory, then skip to the "Creating index.jsp" sub-section. If there is already an index.html, continue with the "Renaming index.html to index.jsp and Modifying Its Contents" section which follows.

Renaming index.html to index.jsp and Modifying Its Contents

A Google AppEngine web project will create an index.html file as the default file for your web application. In the section above, we specified a change to the <welcome-file-list> configuration parameter which instructs the AppEngine's runtime environment to look for the following default pages in the specified order:

index.jsp

index.xhtml

index.html

As such, we we will rename the AppEngine's default index.html file to index.jsp. We will ensure that the browser's "back" button will continue to function properly by following the guidelines prescribed in the "Avoid Redirects" section of Yahoo!'s "Best Practices for Speeding Up Your Web Site" document. The index.jsp file will be configured to send a redirect to the browser rather than leverage an <metahttp-equiv="Refresh"content="0,welcome.jsf"/> tag in the <head> of an HTML document.

Locate and right-click on the index.html file in the war directory shown in the "Project Explorer" window.

When the context-sensitive menu is displayed, left-click on the 'Rename...' menu item found on the 'Refactor' sub-menu.

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

Left-click on the 'OK' button to complete the file rename operation.

Left double-click on the newly renamed index.jsp file to open the file in the editor. Replace the file contents with the following:

<html> <head> <title>Initial Redirect Page</title> </head> <body><% response.sendRedirect("welcome.jsf"); %> <body></html>NOTE: If you decide to use a page other than welcome.xhtml as your initial landing page, please make the appropriate change to the index.jsp shown above.

Save your changes to the index.jsp and close the file.

In the "Package Explorer" window, right-click on the war directory. Left-click on the "New" menu and then left-click on the "File" menu item.

When presented with the "New File" dialog, type in welcome.xhml in the 'File name:' field and then left-click on the 'Finish' button.

The newly created welcome.xhtml file will be presented in the editor. Use the following as the contents of the file.

<!DOCTYPEhtmlPUBLIC"-//W3C//DTD XHTML 1.0 Strict//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><htmlxmlns="http://www.w3.org/1999/xhtml"xml:lang="en"lang="en"xmlns:f="http://java.sun.com/jsf/core"xmlns:h="http://java.sun.com/jsf/html"xmlns:ui="http://java.sun.com/jsf/facelets"><h:headid="head"><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>Welcome to JSF 2.0 on the Google AppEngine!</title></h:head><h:bodyid="body"><f:viewcontentType="text/html"><p><h:outputTextvalue="You are now up and running with JavaServer Faces 2.0 on the Google App Engine."/></p></f:view>

</h:body>

</html>

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.

Creating index.jsp

The default welcome page for our web application will be a JSP page entitled index.jsp and we will ensure that the browser's "back" button will continue to function properly by following the guidelines prescribed in the "Avoid Redirects" section of Yahoo!'s "Best Practices for Speeding Up Your Web Site" document. The index.jsp file will be configured to send a redirect to the browser rather than leverage an <metahttp-equiv="Refresh"content="0,welcome.jsf"/> tag in the <head> of an HTML document.

Locate and right-click on the war directory shown in the "Project Explorer" window.

Left-click on the "New" menu and then left-click on the "File" menu item.

When presented with the "New File" dialog, enter "index.jsp" as the value for the "File name:" field and left-click on the "Finish" button.

The newly created index.jsp file will be presented in the editor. Use the following as the contents of the file.

<html> <head> <title>Initial Redirect Page</title> </head> <body><% response.sendRedirect("welcome.jsf"); %> <body></html>NOTE: If you decide to use a page other than welcome.xhtml as your initial landing page, please make the appropriate change to the index.jsp shown above.

Return to the "Project Explorer" window and right click on the war directory.

Left-click on the "New" menu and then left-click on the "File" menu item.

When presented with the "New File" dialog, enter "welcome.xhtml" as the value for the "File name:" field and left-click on the "Finish" button.

The newly created welcome.xhtml file will be presented in the editor. Use the following as the contents of the file.

<!DOCTYPEhtmlPUBLIC"-//W3C//DTD XHTML 1.0 Strict//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><htmlxmlns="http://www.w3.org/1999/xhtml"xml:lang="en"lang="en"xmlns:f="http://java.sun.com/jsf/core"xmlns:h="http://java.sun.com/jsf/html"xmlns:ui="http://java.sun.com/jsf/facelets"><h:headid="head"><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>Welcome to JSF 2.0 on the Google AppEngine!</title></h:head><h:bodyid="body"><f:viewcontentType="text/html"><p><h:outputTextvalue="You are now up and running with JavaServer Faces 2.0 on the Google App Engine."/></p></f:view>

</h:body>

</html>

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.

Starting Your Google App Engine JSF Application

Now that you have completed the requisite configuration steps, you are ready to launch your first JSF application running on the App Engine platform.