Page History

Camel on Google App Engine Tutorial

Overview

Goal of this tutorial is to get a non-trivial Camel application running on Google App Engine that can send weather reports to user-defined email accounts. The user enters (GAE). For developing that application the Camel Components for Google App Engine will be used. The application allows the user to enter the name of a city and the email address of the report receiver into a form and submits it to the tutorial application. Retrieving weather data for that city and sending the weather report is done in the background.

Image Removed

Download

The packaged tutorial application can be downloaded from here. It is an Eclipse project that requires the Google Eclipse Plugin and the App Engine Java SDK 1.2.6 for running. A Maven-based version of the project should be available soon. The following sections describe how to build that application from scratch.

Create a GAE application

For setting up the Camel-independent parts of a GAE application refer to the Java Getting Started Guide in the GAE documentation. This tutorial uses the Google Plugin for Eclipse and the App Engine Java SDK 1.2.6. After installing the SDK and the plugin, create a new GAE project via File->New->Web Application Project.

Image Removed

After pressing Finish the new GAE project appears in the package explorer.

Image Removed

Add required libraries

The created project is not a Maven project so all required dependencies must be added manually to the war/WEB_INF/lib directory. These are

• camel-core-2.1-SNAPSHOT.jar
• camel-spring-2.1-SNAPSHOT.jar
• camel-http-2.1-SNAPSHOT.jar
• camel-servlet-2.1-SNAPSHOT.jar
• camel-gae-2.1-SNAPSHOT.jar
• commons-logging-1.1.1.jar
• commons-management-1.0.jar
• commons-httpclient-3.1.jar
• commons-codec-1.4.jar
• spring-aop-2.5.6
• spring-beans-2.5.6
• spring-context-2.5.6
• spring-core-2.5.6

Then right-click on the Tutorial project and add these libraries to the classpath via Properties->Java Build Path->Libraries->Add JARs.... After adding they should now appear in the Referenced Libraries container.

Image Removed

Setup deployment descriptors

The deployment descriptors web.xml and appengine-web.xml are located in the war/WEB-INF directory.

web.xml

...

<?xml version="1.0" encoding="utf-8"?>
<web-app 
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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">
    
    <servlet>
        <servlet-name>CamelServlet</servlet-name>
        <servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>context.xml</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>CamelServlet</servlet-name>
        <url-pattern>/camel/*</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
        <servlet-name>CamelServlet</servlet-name>
        <url-pattern>/worker/*</url-pattern>
    </servlet-mapping>
    
    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>
</web-app>

an email adsress in an HTML form. The form data are submitted by the user to a Camel application, running on GAE, which retrieves weather data for the given city. It then sends a weather report to the user-defined email address. The following figure gives an overview.

Image Added

POSTed form data are dispatched to the Camel application via the ghttp component. Then the application queues the message with the gtask component for further background processing. This includes retrieval of weather data from the Google Weather Service, transforming the data to generate a report and sending that report by email via the gmail component.

Prerequisites

• Sign up for a Google App Engine account if you don't have already.
• Create a new application via the admin console or reuse an existing one for uploading the example.
• Install the Google App Engine SDK for Java. This tutorial has been tested with version 1.2.6.

Deployment

To deploy the example application, first checkout the sources with

svn co http://svn.apache.org/repos/asf/camel/trunk/examples/camel-example-gae camel-example-gae

Open the camel-example-gae/src/main/webapp/WEB-INF/application-web.xml file in an editor and replace the template application name replaceme with the name of the application that you created in the previous section

appengine-web.xml

The <application> element in appengine-web.xml requires a GAE application name. In the following example, replace the value replaceme with a valid GAE application name.

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <!-- use your own application name here -->
    <application>replaceme</application> 
    <version>1</version>
	
    <!-- Configure java.util.logging -->
    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
	
</appengine-web-app>

Setup the form

Users provide input data to the application by submitting form data. The following form definition should be stored in war/WEB-INF/index.html.

Open camel-example-gae/src/main/resources/context.xml file and change the sender property value to the email address of your Google App Engine account.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
    
    ...

    <bean id="tutorialRouteBuilder"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Weather Report</title>
</head>

<body>
<h1>Weather Report</h1>
<form action="camel/weather" method="post">
<table>
    <tr>
        <td>City:</td>
        <td><input type="text" name="city"></td>
    </tr>
    <tr>
        <td>Mailto:</td>
        <td><input typeclass="text" name="mailto"></td>org.apache.camel.example.gae.TutorialRouteBuilder">
    </tr>
    <tr>
        <td></td><!-- use your own GAE admin email address here -->
        <td<property alignname="rightsender"><input type="submit" value="Submitreplaceme@gmail.com" /></td>>
    </tr>bean>
    
</table>
</form>
</body>
</html>
beans>

Then go to the camel-example-gae directory and enter

mvn install

This will create the application war file in the target directory. Finally use the appcfg command-line tool of the App Engine SDK to deploy the application.

appcfg update target/camel-example-gae-<version>

where version needs to be replaced with the version of Camel you're using. You will be prompted for the email address and password of your Google App Engine account. After deployment the example application is ready to use.

Usage

Go When the user presses the Submit button the form data are POSTed to http://<appname>replaceme.appspot.com/camel/weather. The input field values will be available as in message headers city and mailto.

Setup the routes

Add the following TutorialRouteBuilder class to the org.apache.camel.example.gae package. The previously generated TutorialServlet in that package can be deleted.

^{Image Added} where replaceme must be replaced with the application name you entered in appengine-web.xml. The following form should now appear.

Image Added

Enter the name of a city and your email address, for example:

Image Added

Then press Submit. The immediate response is

Weather report will be sent to you@yourprovider.com

In the background, the current weather conditions for the user-defined city will be obtained from the Google weather service and a formatted weather report will be send by email. Submitting the form the first time initializes the application on Google App Engine which can take several seconds. Subsequent submissions are served much faster. Check your emails and you should now see a new email with subject Wheather report and content similar to this one:

Weather report for:  London, England
Current condition:   Klar
Current temperature: 12 (Celsius) 

The report is partly internationalized, depending on the language settings of your browser.

Route builder walkthrough

package org.apache.camel.example.gae;

import org.apache.camel.Exchange;
import org.apache.camel.builder.RouteBuilder;
import org.apache.camel.component.gae.mail.GMailBinding;

public class TutorialRouteBuilder extends RouteBuilder {

    private String sender;
    
    public void setSender(String sender) {
        this.sender = sender;
    }
    
    @Override
    public void configure() throws Exception {
        from("ghttp:///weather")
            .to("gtask://default")
            .setHeader(Exchange.CONTENT_TYPE, constant("text/plain"))
            .transform(constant("Weather report will be sent to ").append(header("mailto")));
      
        from("gtask://default")
            .setHeader(Exchange.HTTP_QUERY, constant("weather=").append(header("city")))
            .to("ghttp://www.google.com/ig/api")
            .process(new WeatherProcessor())        
            .setHeader(GMailBinding.GMAIL_SUBJECT, constant("Weather report"))
            .setHeader(GMailBinding.GMAIL_TO, header("mailto"))
            .to("gmail://<replaceme>@gmail.com"" + sender);
    }

}

Form data are received via the ghttp component. After receiving the request it is added to the default queue for background processing. Queueing messages on GAE is done with the gtask component. After queueing the request a response is generated for being displayed in the browser. The value of the mailto header is the email address the user entered in the form.

...

This processor extracts data from the XML result with XPath expressions and creates a simple text-based report for being sent by email. Add this class to the org.apache. camel.example.gae package. For sending the email the gmail component is used. The sender is given by the endpoint URI where <replaceme> must be replaced with the username of the admin account of the GAE application (usually the account to deploy the GAE application). The recipient is derived from the user-defined mailto header .

Setup the application context

Add the following application context XML file to the project's src directory (needs to be on the classpath).

...

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
    
    <bean id="camelContext" 
        class="org.apache.camel.component.gae.context.GaeSpringCamelContext">
        <property name="routeBuilder" ref="tutorialRouteBuilder" />
    </bean>
    
    <bean id="tutorialRouteBuilder"
        class="org.apache.camel.example.gae.TutorialRouteBuilder">
    </bean>
    
</beans>

Deploy the application

To deploy the application right-click on the Tutorial project and select Google->Deploy to App Engine. In the dialog enter the project name, your email address and password for logging into App Engine and press Deploy.

Use the application

Go to http://<appname>.appspot.com where <appname> must be replaced with a valid GAE application name. The following form should now appear.

Image Removed

Enter the name of a city and your email address, for example:

Image Removed

Then press Submit. Submitting the form the first time will initialize the application on Google App Engine which can take more than 10 seconds. Subsequent submissions are served much faster. Check your emails and you should now see a new email with subject Wheather report and content similar to this one:

Weather report for:  London, England
Current condition:   Klar
Current temperature: 12 (Celsius) 

The report is partly internationalized, depending on the language settings of your browservalue.