parent/src/site/apt/myfaces2-googleappengine-idea-tutorial.apt

 ------
 Tutorial : Configuring MyFaces 2 to run on Google App Engine with IntelliJ IDEA
 ------
 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 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 {{{./googleappenginesupport.html}here}}. Additionally, there is a tutorial for Eclipse {{{./myfaces2-googleappengine-eclipse-tutorial.html}here}}. 

  {{{http://sites.google.com/a/aliok.com.tr/upload/uploads/tutorial-gae-myfaces2-idea.zip?attredirects=0&d=1}Here}} 
  is the complete source code and the IDEA 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 at: 
  {{{http://myfaces2-tutorial-idea.latest.aliok-com-tr-test.appspot.com/guess.jsf}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 
  {{{http://upload.aliok.com.tr/uploads/myfaces2-gae-idea-tut-all-images.zip?attredirects=0&d=1}this link}}. 

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


*{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 {{{http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Java}App Engine SDK}} and extract it to somewhere.
  
  [[2]]  Download {{{http://myfaces.apache.org/download.html}MyFaces Core 2.0.0 Beta 3}} (or a later version) and extract it.
  
  [[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}} jars.
  
  [[4]]  We need IntelliJ IDEA {{{Ultimate Edition}http://www.jetbrains.com/idea/download/}}. Community edition doesn't have JavaEE support, 
         thus {{{http://plugins.intellij.net/plugin/?&id=4254}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.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-01-welcome.jpg] 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. 

[images/gaetutorial-idea/myfaces2-gae-idea-tut-02-plugins.jpg] IDEA Plugins Screen

  [[6]]  Next, we will define our App Engine Devl Server.
  
    [[a]] To do this, navigate to IDE settings.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-03-settings-menu.jpg] IDEA Settings Menu

    [[b]] Select "Application Servers" and click "Add" button. Select "Google App Engine Dev Server".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-04-ide-settings.jpg] IDE Settings

    [[c]] Select the path of the App Engine SDK.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-05-sdk-path.jpg] SDK Path Config

    [[d]] You will see some JARS under the "Classes" node.
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-06-sdk-verification.jpg] SDK Verification






*{Creating and Configuring the Project}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  [[1]] First, we will create a new project:
    
    [[a]] Press "File - > New Project"
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-07-new-project.jpg] New Project

    [[b]] We will create the project from scratch. So, select it and press next.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-08-create-scratch.jpg] New Project from Scratch

    [[c]] Type the project name, and select "Java Module".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-09-project-naming.jpg] New Project Name
    
    [[d]] Let IDEA crete a source directory for us.
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-10-scr-dir.jpg] New Project src Dir

    [[e]] 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.
          
[images/gaetutorial-idea/myfaces2-gae-idea-tut-11-tech-selection.jpg] 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.

    [[a]] Right-click on the project and select "Module Settings".
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-12-module-settings.jpg] Module Settings

    [[b]] You will see a screen like the one below.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-13-project-libs.jpg] Project Libs

    [[c]] Press the "+" button, type "MyFaces 2 Beta 3" and press "OK".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-14-lib-name.jpg] Lib Name

    [[d]] IDEA will ask which modules to add the library. Select the project you've created and press "OK".
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-15-lib-module-selecting.jpg] Project Library Module Selection

    [[e]] 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.
          
[images/gaetutorial-idea/myfaces2-gae-idea-tut-16-attach-classes.jpg] Attach Classes

    [[f]] You should have a screen like below. Press "OK".
    
[images/gaetutorial-idea/myfaces2-gae-idea-tut-17-lib-verification.jpg] Library Verification

    [[g]] Here is the external libraries so far:

[images/gaetutorial-idea/myfaces2-gae-idea-tut-18-ext-lib-verification.jpg] External Library Verification

  [[3]] Put necessary jars into "WEB-INF/lib":
  
    [[a]] 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".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-19-lib-dir-create.jpg] lib Directory Creation
          
    [[b]] Type "lib" and press OK.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-20-lib-naming.jpg] lib Directory Naming
          
    [[c]] 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".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-21-paste-jars.jpg] Paste MyFaces Jars

    [[d]] Here is the "WEB-INF/lib" jars so far:

[images/gaetutorial-idea/myfaces2-gae-idea-tut-22-jar-verification.jpg] MyFaces Jar Verification

    [[e]] 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".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-23-paste-el-jars.jpg] Paste EL Jars

  [[4]] XML configuration:

    [[a]] Put the lines below into your web.xml file:
    
+---------------------------------------------------------------------------------------------------------+
<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>
+---------------------------------------------------------------------------------------------------------+

[images/gaetutorial-idea/myfaces2-gae-idea-tut-24-web-xml-conf.jpg] web.xml Configuration

    [[b]] 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>
+---------------------------------------------------------------------------------------------------------+

[images/gaetutorial-idea/myfaces2-gae-idea-tut-25-faces-config-conf.jpg] faces-config.xml Configuration

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

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

[images/gaetutorial-idea/myfaces2-gae-idea-tut-26-appengine-web-conf.jpg] 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.

         {{{http://sites.google.com/a/aliok.com.tr/upload/uploads/tutorial-gae-myfaces2-idea.zip}Here}} is the complete 
         source code and the IDEA 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.




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

  [[1]] We need to define a run configuration.
  
	[[a]] Select "Run - > Edit Configurations"

[images/gaetutorial-idea/myfaces2-gae-idea-tut-27-edit-run-conf.jpg] Edit Run Configuration
	
	[[b]] Press "+" button to add a new configuration.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-28-add-new-run-conf.jpg] Adding New Run Configuration
	
    [[c]] Select "Google AppEngine Dev Server".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-29-add-gae-run-conf.jpg] Add GAE Run Configuration
	
	[[d]] Type the configuration name, and make sure your screen seems like this:

[images/gaetutorial-idea/myfaces2-gae-idea-tut-30-gae-run-conf-settings.jpg] GAE Run Configuration Settings
	
	[[e]] Select "Build Artifacts" and click "..." button. We will configure, what to export.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-31-run-conf-build.jpg] Run Configuration Build Settings
	
	[[f]] Select "Test-GoogleAppEngine:war exploded".
	
[images/gaetutorial-idea/myfaces2-gae-idea-tut-32-run-conf-artifacts.jpg] Run Configuration Build Artifacts
	

  [[2]] Now, you can see the configuration you've defined next to "Run" button.

    [[a]] Select your run configuration and press "Run".

[images/gaetutorial-idea/myfaces2-gae-idea-tut-33-run-conf-select.jpg] Run Configuration Selection
	
	[[b]]  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.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-34-myfaces-logs.jpg] MyFaces Logs
	
	[[c]] 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.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-35-local-page.jpg] Local Devl Server Page
	
	[[d]] You can stop the GAE Devl Server by pressing stop button.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-36-stop-local-server.jpg] Stopping Local Server





*{Running Facelets Tutorial Example}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  I've configured a project to run on Google App Engine, which you can find the sources 
  {{{http://sites.google.com/a/aliok.com.tr/upload/uploads/tutorial-gae-myfaces2-idea.zip}here}}.
  You can simply copy the files guess.xhtml, response.xhtml, template.xhtml and NumberBean.java to appropriate locations.

[images/gaetutorial-idea/myfaces2-gae-idea-tut-37-add-stuff.jpg] Add Stuff

  You can see the application running below.
  
[images/gaetutorial-idea/myfaces2-gae-idea-tut-38-guess-appl-local-page.jpg] 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.	

[images/gaetutorial-idea/myfaces2-gae-idea-tut-39-app-engine-appl-version-conf.jpg] App Engine Application and Version Configuration

  [[2]] You can upload the application by selecting "Tools - > Upload App Engine Application".
  
[images/gaetutorial-idea/myfaces2-gae-idea-tut-40-upload.jpg] Uploading

  [[3]] IDEA will ask about building. Build the project by clicking "Yes".
  
[images/gaetutorial-idea/myfaces2-gae-idea-tut-41-upload-build.jpg] 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.
  
[images/gaetutorial-idea/myfaces2-gae-idea-tut-42-upload-console.jpg] 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.com
  
[images/gaetutorial-idea/myfaces2-gae-idea-tut-43-gae-page.jpg] GAE Page