UI-Component Sets
Project Documentation

Tutorial : Configuring MyFaces 2 to run on Google App Engine with IntelliJ IDEA

Google App Engine support for MyFaces 2 made trunk and it is released with MyFaces Core 2.0.0-beta-3. In this tutorial, I will explain how to use it with IntelliJ IDEA. I assume that you have basic IDEA, JSF and Facelets knowledge.

You can find IDE-independent instructions here. Additionally, there is a tutorial for Eclipse here.

Here is the complete source code and the IDEA project of the example application (which I took from Facelets Tutorial) that I configured to run on Google App Engine.

I deployed the application explained in this tutorial at: http://myfaces2-tutorial-idea.latest.aliok-com-tr-test.appspot.com/guess.jsf

In order to run Myfaces on Google App Engine, you need to complete the steps below. Configuration explained in this document is tested with Google App Engine 1.3.0.

If you're having trouble with the figures in this page, you can download all images from this link.

Requirements

  • IntelliJ IDEA Ultimate Edition
  • Google App Engine SDK
  • MyFaces Core 2.0.0 Beta 3
  • EL API and Impl
  • Basic JSF and Facelets knowledge
  • Google App Engine Account :)

Downloading and Configuration

  1. Download App Engine SDK and extract it to somewhere.
  2. Download MyFaces Core 2.0.0 Beta 3 (or a later version) and extract it.
  3. Download EL API and EL Impl jars.
  4. We need IntelliJ IDEA http://www.jetbrains.com/idea/download/. Community edition doesn't have JavaEE support, thus Google App Engine Plugin doesn't work on it. I downloaded and installed IDEA version 9.0.1, and I don't know this plugin works for older versions of the IDE.IDEA Welcome
  5. After installing the IDE and running for the first time, the IDE asked me which plugins that I want. I selected "Google App Engine Integration" and its dependencies. If you have an existing installation, make sure you have "Google App Engine Integration" plugin installed and enabled. IDEA Plugins Screen
  6. Next, we will define our App Engine Devl Server.
    1. To do this, navigate to IDE settings.IDEA Settings Menu
    2. Select "Application Servers" and click "Add" button. Select "Google App Engine Dev Server".IDE Settings
    3. Select the path of the App Engine SDK.SDK Path Config
    4. You will see some JARS under the "Classes" node.SDK Verification

Creating and Configuring the Project

  1. First, we will create a new project:
    1. Press "File - > New Project"New Project
    2. We will create the project from scratch. So, select it and press next.New Project from Scratch
    3. Type the project name, and select "Java Module".New Project Name
    4. Let IDEA crete a source directory for us.New Project src Dir
    5. On this screen, select "Web Application" and "Google App Engine" nodes. Altough we will create a JSF project, don't select the "JavaServer Faces" node since IDEA doesn't support MyFaces 2 yet. After making sure the AppEngine SDK path is correct, press "Finish" and IDEA will create the project.Technology Selection
  2. Now, we will add the MyFaces jars as an "External Library". I did this step to solve compilation problems in my managed beans. Without explicitly adding an External Library, "javax.faces" namespace is not visible in my managed beans �which we will create in the next steps- even if the jars exist in "WEB-INF/lib". I am sure an experienced IDEA user can solve this problem in a better way.
    1. Right-click on the project and select "Module Settings".Module Settings
    2. You will see a screen like the one below.Project Libs
    3. Press the "+" button, type "MyFaces 2 Beta 3" and press "OK".Lib Name
    4. IDEA will ask which modules to add the library. Select the project you've created and press "OK".Project Library Module Selection
    5. Now we will "attach" MyFaces2 jars. While the newly created library "MyFaces 2 Beta 3" is selected, press "Attach Classes" button and select the MyFaces (and dependencies) jars.Attach Classes
    6. You should have a screen like below. Press "OK".Library Verification
    7. Here is the external libraries so far:External Library Verification
  3. Put necessary jars into "WEB-INF/lib":
    1. By default, IDEA does not create a "lib" folder under "WEB-INF". So we need to create one. Right-click on "WEB-INF" folder and select "New - > Directory".lib Directory Creation
    2. Type "lib" and press OK.lib Directory Naming
    3. Copy the jars from the MyFaces release (myfaces-api-2.x.x.jar, lib/myfaces-impl-2.x.x.jar, lib/commons-logging-1.x.x.jar, lib/commons-beanutils-1.x.x.jar, lib/commons-codec-1.x.jar, commons-collections-3.x.jar, lib/commons-digester-x.x.jar, lib/commons-discovery-0.x.jar) and paste them into "WEB-INF/lib".Paste MyFaces Jars
    4. Here is the "WEB-INF/lib" jars so far:MyFaces Jar Verification
    5. Put el-api-x.x.jar and el-impl-1.1.jar �which you've downloaded at step 3 of "Downloading and Configuration" section- into "WEB-INF/lib".Paste EL Jars
  4. XML configuration:
    1. Put the lines below into your web.xml file:
      <web-app ...
         ...
         <!--
            We need to set annotation lifecycle provider manually as org.apache.myfaces.config.annotation.NoInjectionAnnotationLifecycleProvider.
            Other providers use some classes that are restricted on Google App Engine.    
         --> 
         <context-param>
            <param-name>
               org.apache.myfaces.config.annotation.LifecycleProvider
            </param-name>
            <param-value>
               org.apache.myfaces.config.annotation.NoInjectionAnnotationLifecycleProvider
            </param-value>
         </context-param>
      
         <!--
            Need to set a secret to avoid javax.crypto.BadPaddingException.
            "param-value" must be Base64 encoded.
            More details: http://wiki.apache.org/myfaces/Secure_Your_Application
         -->
         <context-param>
            <param-name>org.apache.myfaces.SECRET</param-name>
            <param-value>NzY1NDMyMTA=</param-value>
         </context-param>       
      
         <!--
            Facelets configuration fragment
         -->
         <context-param>
            <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
            <param-value>.xhtml</param-value>
         </context-param>
             
         <servlet>
            <servlet-name>Faces Servlet</servlet-name>
            <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
         </servlet>
             
         <servlet-mapping>
            <servlet-name>Faces Servlet</servlet-name>
            <url-pattern>*.jsf</url-pattern>
         </servlet-mapping>
         ...     
      </web-app>
      web.xml Configuration
    2. Create a "faces-config.xml" file under your "WEB-INF" folder, and make sure that you use the JSF 2 header in it.
      <?xml version="1.0"  encoding="UTF-8"?>
      
      <faces-config
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
         version="2.0">
         ...
      </faces-config>
      faces-config.xml Configuration
    3. Add the following line into war/WEB-INF/appengine-web.xml:
         <sessions-enabled>true</sessions-enabled>
      appengine-web.xml Configuration
  5. Now you can add your pages, beans etc. You cannot use JSP as view technology on Google App Engine. You must use Facelets, which is the default view technology in JSF 2.

    Here is the complete source code and the IDEA project of the example application (which I took from Facelets Tutorial) that I configured to run on Google App Engine.

Deploying to App Engine Development Server (Your Local Server)

  1. We need to define a run configuration.
    1. Select "Run - > Edit Configurations"Edit Run Configuration
    2. Press "+" button to add a new configuration.Adding New Run Configuration
    1. Select "Google AppEngine Dev Server".Add GAE Run Configuration
      1. Type the configuration name, and make sure your screen seems like this:GAE Run Configuration Settings
      2. Select "Build Artifacts" and click "..." button. We will configure, what to export.Run Configuration Build Settings
      3. Select "Test-GoogleAppEngine:war exploded".Run Configuration Build Artifacts
  2. Now, you can see the configuration you've defined next to "Run" button.
    1. Select your run configuration and press "Run".Run Configuration Selection
      1. You will see MyFaces logs on the console. You shouldn't see any exception at this step. If you saw one, make sure you've completed all steps above.MyFaces Logs
      2. You can see your application at "localhost:8080". IDEA created a dummy index.jsp before, so it is normal to see "Place your content here" text.Local Devl Server Page
      3. You can stop the GAE Devl Server by pressing stop button.Stopping Local Server

Running Facelets Tutorial Example

I've configured a project to run on Google App Engine, which you can find the sources here. You can simply copy the files guess.xhtml, response.xhtml, template.xhtml and NumberBean.java to appropriate locations.

Add Stuff

You can see the application running below.

Guess Application Local Page

Deploying to App Engine

  1. You need to set application name and version in appengine-web.xml file. You can see my config below. "application" is your application id at Google App Engine (AppSpot Id), and version is anything you like. App Engine Application and Version Configuration
  2. You can upload the application by selecting "Tools - > Upload App Engine Application".Uploading
  3. IDEA will ask about building. Build the project by clicking "Yes".Upload : Build
  4. Now, IDEA will use AppEngine SDK's batch jobs to upload application. You will be asked your email and password. You can see the output of my upload below.Upload Console
  5. Your application is hosted at Google App Engine now. You can see this version of the application at "Versions" page of Google App Engine administration screen. Your application is hosted at version-I-specified.latest.application-ID.appspot.comGAE Page