3. "Hello, world" (POJO)

Documentation Summary

Page Summary

Overview

This page will guide you through the setting up of a very basic GraniteDS project deployed in Tomcat. Expected result is a typical "Hello, world" application as shown below:

When you type a name in the text field and click Say Hello, a request is sent to a POJO service that replies with a string made by this concatenation:

"Hello " + <typed name> + "!"

The result is then displayed in white under the "Hello World Sample" panel.

You may download this sample project here if you don't want to copy-paste the code in the following sections below.

Requirements

In order to create, build, and deploy this sample application you need these free tools:

Java 5+ (6+ working): Download Sun JDK and install it.
Eclipse 3.3+: Download Eclipse and unzip it somewhere.
Flex 3 SDK: Download Flex 3 SDK and unzip it somewhere. For example, /flex_3_sdk (for Windows users: C:\flex_3_sdk).
Tomcat 6+: Download Tomcat and unzip it somewhere. For example, /apache-tomcat-6.0.18 (for Windows users: C:\apache-tomcat-6.0.18).
granite.jar: You may take it from any of the GraniteDS sample applications or from GraniteDS source distribution in the build folder. Download it here.

Eclipse Project Creation

Java Service:

Start Eclipse and create a new Java project named helloworld. You may just type in helloworld for Project name and accept all other default settings. Because we are going to have two types of sources, Java and Flex MXML, it is better to rename the default Java source folder src to java. You can do this by right-clicking on the src source folder and selecting Refactor / Rename.

We are now going to create a new POJO service named HelloWorldService. Right-click on the java source folder and select New / Class, enter org.test for Package and HelloWorldService for Name in the following dialog, and then click on the Finish button. In the Java source file editor, modify the code so it is just as follows:

HelloWorldService.java

package org.test;

public class HelloWorldService {

    public String sayHello(String name) {
        return "Hello " + name + "!";
    }
}

You should now see something like the following picture under Eclipse:

Flex Client Code:

Create a new folder named flex by right-clicking on the helloworld project and selecting New / Folder. Create a new file directly in this new folder and name it HelloWorld.mxml by right-clicking on the flex folder and selecting New / File. In the file editor, which may be FlexBuilder or a simple text editor depending on your Eclipse installation, type in the following code:

HelloWorld.mxml

<?xml version="1.0" encoding="utf-8"?>

<mx:Application
    xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundGradientColors="[#0e2e7d, #6479ab]"
    layout="vertical"
    verticalAlign="middle">

    <mx:Style>
        .Panel {
            padding-left: 8px; padding-top: 8px;
            padding-right: 8px; padding-bottom: 8px;
        }
        .Result { font-size: 26px; color: white; }
    </mx:Style>

    <mx:RemoteObject id="srv" destination="helloWorldService" />

    <mx:Panel styleName="Panel" title="Hello World Sample">
        <mx:Label text="Enter your name:"/>
        <mx:TextInput id="nameInput" />
        <mx:Button label="Say Hello" click="srv.sayHello(nameInput.text)"/>
    </mx:Panel>
        
    <mx:Label styleName="Result" text="{srv.sayHello.lastResult}"/>

</mx:Application>

You should now see something like the following picture under Eclipse:

Configuration Files:

Create two files named services-config.xml and web.xml at the root of your project. You should now see:

Copy and paste the following code for each file:

services-config.xml

<?xml version="1.0" encoding="UTF-8"?>

<services-config>

    <services>
        <service
            id="granite-service"
            class="flex.messaging.services.RemotingService"
            messageTypes="flex.messaging.messages.RemotingMessage">
            <destination id="helloWorldService">
                <channels>
                    <channel ref="my-graniteamf"/>
                </channels>
                <properties>
                    <scope>application</scope>
                    <source>org.test.HelloWorldService</source>
                </properties>
            </destination>
        </service>
    </services>

    <channels>
        <channel-definition id="my-graniteamf" class="mx.messaging.channels.AMFChannel">
            <endpoint
                uri="http://{server.name}:{server.port}/{context.root}/graniteamf/amf"
                class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
    </channels>

</services-config>

web.xml

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <!-- general information about this web application -->
    <display-name>Hello World</display-name>
    <description>Hello World Sample Application</description>

    <!-- read services-config.xml file at web application startup -->
    <listener>
        <listener-class>org.granite.config.GraniteConfigListener</listener-class>
    </listener>

    <!-- handle AMF requests ([de]serialization) -->
    <filter>
        <filter-name>AMFMessageFilter</filter-name>
        <filter-class>org.granite.messaging.webapp.AMFMessageFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>AMFMessageFilter</filter-name>
        <url-pattern>/graniteamf/*</url-pattern>
    </filter-mapping>

    <!-- handle AMF requests (execution) -->
    <servlet>
        <servlet-name>AMFMessageServlet</servlet-name>
        <servlet-class>org.granite.messaging.webapp.AMFMessageServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>AMFMessageServlet</servlet-name>
        <url-pattern>/graniteamf/*</url-pattern>
    </servlet-mapping>

    <!-- default content for helloworld application -->
    <welcome-file-list>
        <welcome-file>HelloWorld.swf</welcome-file>
    </welcome-file-list>

</web-app>

Put together, those four files (HelloWorldService.java, HelloWorld.mxml, services-config.xml, and web.xml), specify an entire Flex/GraniteDS application. Here are some highlights (partial/pseudo code):

public String HelloWorldService.sayHello(String name)

<mx:RemoteObject id="srv" destination="helloWorldService" />
<mx:Button label="Say Hello" click="srv.sayHello(nameInput.text)"/>
<mx:Label ... text="{srv.sayHello.lastResult}"/>

<destination id="helloWorldService">
    <channel ref="my-graniteamf"/>
    <scope>application</scope>
    <source>org.test.HelloWorldService</source>
</destination>
<channel-definition id="my-graniteamf" ...>
    <endpoint uri="http://{server.name}:{server.port}/{context.root}/graniteamf/amf" .../>
</channel-definition>

<url-pattern>/graniteamf/*</url-pattern>

From top to bottom:

The HelloWorldService Java class declares a method sayHello() that takes a String parameter and returns another String.
The HelloWorld.mxml Flex application declares a RemoteObject named srv and maps it to a destination named helloWorldService.
When you click on the Say Hello mx:Button, the RemoteObject triggers a server request that will call a sayHello() method with a String parameter (the text typed in the mx:TextInput named nameInput): srv.sayHello(nameInput.text).
The result of this call will be displayed, when available, in an mx:Label: srv.sayHello.lastResult.
The helloWorldService destination is declared in services-config.xml and uses a channel named my-graniteamf. The Java class (source) used as a service for this destination call is org.test.HelloWorldService and its scope is application. The Java class will be created when the service is first accessed, and this same and unique instance will be used for all subsequent calls; other possible values are request and session.
The channel named my-graniteamf, used by the helloWorldService destination, declares an endpoint whose URL will be resolved to http://localhost:8080/helloworld/graniteamf/amf for a local call; it could also be resolved, for example, to http://www.helloworld.com:80/helloworld/graniteamf/amf for remote calls.
AMFMessageFilter and AMFMessageServlet are both bound in web.xml to the same URL-pattern /graniteamf/*. Inside the helloworld web application, all requests that match this pattern will be go through this filter and this servlet such as http://localhost:8080/helloworld/graniteamf/amf.

Here is basic flow chart that summarizes the expected communication between the Flex client application and the Java server:

Building & Deploying the Sample Application

Add granite.jar Library and Create a Build File:

Create a new folder named lib at the root of the project and put granite.jar into this new folder. Create a new file named build.xml at the root of the project. Copy and paste the following content into it; you may have to modify FLEX_HOME/TOMCAT_HOME properties to reflect your environment:

build.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="hello-world" default="deploy">

    <!-- Modify FLEX_HOME/TOMCAT_HOME properties to reflect your environment -->
    <property name="FLEX_HOME" value="/flex_sdk_3"/>
    <property name="TOMCAT_HOME" value="/apache-tomcat-6.0.18"/>
    
    <!-- Declare Flex Ant tasks (such as mxmlc used below) -->
    <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" />

    <!-- Compile MXML source code to SWF -->
    <target name="mxmlc">
        <mxmlc
            file="flex/HelloWorld.mxml"
            output="build/HelloWorld.swf"
            services="services-config.xml"
            context-root="helloworld">
        </mxmlc>
    </target>

    <!-- Build a war suitable for Tomcat (and other) -->
    <target name="war" depends="mxmlc">
        <mkdir dir="build"/>
        <war destfile="build/helloworld.war" webxml="web.xml">
            <zipfileset file="services-config.xml" prefix="WEB-INF/flex" />
            <fileset dir="build" includes="*.swf"/>
            <lib dir="lib"/>
            <classes dir="bin"/>
        </war>
    </target>

    <!-- Deploy the war in Tomcat -->
    <target name="deploy" depends="war">
        <copy todir="${TOMCAT_HOME}/webapps" file="build/helloworld.war"/>
    </target>

</project>

You should see something like the following picture:

You may now right-click on the build.xml file and select Run As / Ant Build. This will launch the build process, compile the MXML code to an SWF, create a WAR (Web Archive), and copy it into your Tomcat deploy directory.

Start Tomcat & Play with the Application

To start Tomcat, go to the directory bin just under your Tomcat installation directory, /apache-tomcat-6.0.18/bin for example, and double-click on startup.bat, or startup.sh for Unix/Mac users. After a short while, you should see in the console that Tomcat has started. You may now point your Internet browser to http://localhost:8080/helloworld/.

The Flex sample application should appear and you may start playing with "Hello, world" ... a fascinating game .