 ------
 Tutorial : Configuring MyFaces 2 to run on Google App Engine with Eclipse
 ------
 Ali Ok
 ------
 2010-04-08
 -------
 
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
 

Tutorial : Configuring MyFaces 2 to run on Google App Engine with Eclipse
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  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. I assume that you have basic Eclipse, JSF and Facelets knowledge.

  You can find IDE-independent instructions {{{./googleappenginesupport.html}here}}. Additionally, there is a tutorial for IntelliJ IDEA {{{./myfaces2-googleappengine-idea-tutorial.html}here}}.

  {{{http://sites.google.com/a/aliok.com.tr/upload/uploads/tutorial-gae-myfaces2.zip?attredirects=0&d=1}Here}} 
  is the complete source code and the Eclipse project of the example application (which I took from 
  {{{https://facelets.dev.java.net/nonav/docs/dev/docbook.html}Facelets Tutorial}}) that I configured to run on 
  Google App Engine. 
  
  I deployed the application explained in this tutorial to: 
  {{{http://myfaces2-tutorial.latest.aliok-com-tr-test.appspot.com/guess.jsf}http://myfaces2-tutorial.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.2.

*Table of Content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  
%{toc|section=2|fromDepth=1|toDepth=1}


*{Setting up the environment}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  [[1]]  Download Eclipse {{{http://www.eclipse.org/downloads/}here}}, preferably IDE for JEE Developers.
  
  [[2]]  Install Google Eclipse Plugin with {{{http://code.google.com/eclipse/docs/download.html}this}} guide.


*{Creating the Project and Placing the Jars}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  [[1]] Create a Web Application Project (uncheck "Use Google Web Toolkit" if you won't use GWT)
  
[images/gaetutorial-eclipse/01.jpg] Creating the Project
  
[images/gaetutorial-eclipse/02.jpg] Creating the Project
  
  [[2]] Download Myfaces Core {{{http://myfaces.apache.org/download.html}here}}. We need "MyFaces Core 2.0.0-beta-3" or a 
        later version. Extract files below and put them into war/WEB-INF/lib.
    
      * lib/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-collections-3.x.jar
      
      * lib/commons-digester-x.x.jar (I tested with version 1.8)
      
      * lib/commons-discovery-0.x.jar

      Here is the war/WEB-INF/lib so far:
      
[images/gaetutorial-eclipse/03.jpg] war/WEB-INF/lib
         
      Please note that some jars (i.e. jdo2-api-2.3-eb.jar) are put by Google App Engine Eclipse plugin when the project is created.
        

  [[3]]  Download {{{http://download.java.net/maven/glassfish/javax/el/el-api/1.1/el-api-1.1.jar}el-api}}  
         and {{{http://download.java.net/maven/glassfish/org/glassfish/web/el-impl/1.1/el-impl-1.1.jar}el-impl}} 
         and put them into war/WEB-INF/lib. You can see the war/WEB-INF/lib so far below.

[images/gaetutorial-eclipse/04.jpg] war/WEB-INF/lib

  [[4]]  Add lines below into war/WEB-INF/web.xml.

+------------------------------------------------------------------------+
     <web-app ...
             ...
            <!--
                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>
+------------------------------------------------------------------------+

  
  [[5]] Make sure that you use the JSF 2 header in your faces-config.

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


  [[6]] Add the following line into war/WEB-INF/appengine-web.xml:

+------------------------------------------------------------------------+
      <sessions-enabled>true</sessions-enabled>
+------------------------------------------------------------------------+


  [[7]]  Now you can add your stuff (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.
         

*{Deploying to App Engine Development Server (Your Local Server)}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Right click on the project and select "Run As -> Web Application". This will start 
  Google App Engine development server. You can see the port information on the console (default is 8888).
  
[images/gaetutorial-eclipse/05.jpg] Deployment to Local Development Server
  

*{Deploying to Google App Engine}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  [[1]]  Right-click on the project and select "Properties".
  
  [[2]]  Select "Google"->"App Engine".
  
  [[3]]  Select "Use Google App Engine" if not selected, and type your "Application ID". Press OK and close the dialog.
  
[images/gaetutorial-eclipse/06.jpg] Configuring the Google App Engine Project
  
  [[4]]  Right click on the project and select "Google" -> "Deploy to App Engine"
    
  [[5]]  Enter your account information, and the application will be deployed on your-app-id.appspot.com.

[images/gaetutorial-eclipse/07.jpg] Deployment to Google App Engine

  [[6]]  The URL for the application I deployed is : 
         {{{http://myfaces2-tutorial.latest.aliok-com-tr-test.appspot.com/guess.jsf}http://myfaces2-tutorial.latest.aliok-com-tr-test.appspot.com/guess.jsf}}