GraniteDS Documentation

You need at least the following four free development tools:

You may also read and follow the recommendations in this in order to customize your development environment.

Installing and testing GraniteDS sample application is a quick process, provided that you have downloaded , and .

Let's say you have installed a vanilla JBoss 4.2.3.GA and fresh Flex SDK at the root of your main drive (C:\jboss-4.2.3.GA and C:\flex_sdk_3 on Windows).

Follow these few steps:

You may now look at the code of each example and understand how each sample works.

This section 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 example project if you don't want to copy-paste the code in the following sections below.

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

Creation of the project in Eclipse:

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:

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:

Now let create the 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 Flah Builder or a simple text editor depending on your Eclipse installation, type in the following code:

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

Now we have to create the two main GraniteDS configuration files services-config.xml and web.xml at the root of the project. You should now see:

Copy and paste the following code into these files:

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

        

<?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), define 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:

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

The last thing to do is to build and deploy the application.

First we have to add the granite.jar library and create a build file, here using Ant.

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 the properties FLEX_HOME and TOMCAT_HOME to reflect your environment:

<?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 webapps directory.

Finally start Tomcat and test 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 Web browser to .

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

This tutorial shows an evolution of the basic "Hello, world" example application with some Hibernate persistence operations (JPA). When finished and deployed it should look like this picture:

In this picture, you see a small data grid that displays the history of all previous say hello operations. This history is persisted in the database by means of a JPA entity bean and those objects are serialized back to the Flex client each time you enter a new name.

This example also shows basic usage of the Granite Eclipse Builder and externalization configuration.

If you don't want to follow this tutorial step by step you may download it as a zip archive .

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

Creation of the project in Eclipse:

Start Eclipse and create a new Java project named helloworld2. You may just type in helloworld2 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.

Create a new directory named lib at the root of this project and put granite.jar, granite-hibernate.jar and granite-essentials.swc into it. Also add these two JBoss jars: ejb3-persistence.jar and jboss-ejb3x.jar, which you will find in the /jboss-4.2.3.GA/server/default/lib directory. Right-click on those JBoss jars and select Build Path / Add to Build Path.

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

Right-click on the java source folder, select New / Class and fill the New Java Class dialog as follows:

Copy and paste the following code in the Java editor:

package org.test;


import java.io.Serializable;


import javax.persistence.Basic;

import javax.persistence.Entity;

import javax.persistence.GeneratedValue;

import javax.persistence.Id;


@Entity

public class Welcome implements Serializable {


    private static final long serialVersionUID = 1L;


    @Id @GeneratedValue

    private Integer id;


    @Basic

    private String name;


    public Welcome() {

    }


    public Welcome(String name) {

        this.name = name;

    }

    

    public Integer getId() {

        return id;

    }


    public String getName() {

        return name;

    }

    public void setName(String name) {

        this.name = name;

    }

}

        

This basic JPA entity bean declares a read-only id field, auto incremented primary key in the database, and a name field, the name of the person that was entered in the Flex application when saying hello.

We are now going to create an EJB 3 session bean that will handle the say hello and persistence operations.

Create a new Java interface named HelloWorldService by right-clicking on the org.test package and choosing New / Interface. Then copy and paste the following code:

package org.test;


import java.util.List;


public interface HelloWorldService {


    public String sayHello(String name);

    public List<Welcome> findWelcomeHistory();

}

        

Create a new Java class named HelloWorldServiceBean that implements the HelloWorldService interface by right-clicking on the org.test package and choosing New / Class. Then copy and paste the following code:

package org.test;


import java.util.List;


import javax.ejb.Local;

import javax.ejb.Stateless;

import javax.persistence.EntityManager;

import javax.persistence.PersistenceContext;

import javax.persistence.Query;


@Stateless

@Local(HelloWorldService.class)

public class HelloWorldServiceBean implements HelloWorldService {


    @PersistenceContext

    protected EntityManager manager;


    @Override

    public String sayHello(String name) {

        manager.persist(new Welcome(name));

        return "Hello " + name + "!";

    }


    @SuppressWarnings("unchecked")

    @Override

    public List<Welcome> findWelcomeHistory() {

        Query query = manager.createQuery("from " + Welcome.class.getName());

        return query.getResultList();

    }

}

        

We now have a complete EJB 3 stateless session bean that will persist each name passed to the sayHello() method and return the list of all previous welcome operations with the findWelcomeHistory() method.

Your Java project should look like that after this step:

Now let create the Flex client code. Create a new folder named flex by right-clicking on the helloworld2 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 Flah Builder or a simple text editor depending on your Eclipse installation, type in the following code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
    xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundGradientColors="[#0e2e7d, #6479ab]"
    layout="vertical"
    verticalAlign="middle"
    creationComplete="srv.findWelcomeHistory()">

    <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" width="200" />
        <mx:Button label="Say Hello"
           click="srv.sayHello(nameInput.text);srv.findWelcomeHistory()"/>
        
        <mx:Label text="History:"/>
        <mx:DataGrid dataProvider="{srv.findWelcomeHistory.lastResult}"
          width="200" height="200"/>
    </mx:Panel>
        
    <mx:Label styleName="Result" text="{srv.sayHello.lastResult}"/>
    
</mx:Application>
        

Some explanations:

We are now going to configure the Granite Eclipse Builder that will generate the Welcome entity bean ActionScript3 equivalent. First the builder and install it; just drop the jar in your Eclipse plugin directory and restart. In your package explorer, right-click on the helloworld2 project and select Add GraniteDS Nature:

In the configuration wizard, click on the Add Folder button and select the java source folder:

Select the Excluded subnode and click on the Edit button. In the following dialog, change the Output Directory to flex, instead of the default as3, and add the **/*Service*.java exclusion pattern, as we don't want code generation for services, just for entities:

After those short configuration steps, you may accept all other default options and click directly on the Finish button in the wizard. The generation process starts and produces two files as shown in the following picture:

There is no need to modify those files for our short example but, if you want to add specific methods to your ActionScript 3 bean, you must put it in the Welcome.as class and not in the WelcomeBase.as class that may be overwritten by subsequent generation processes. If you look at the WelcomeBase.as class, you will see that the generated code reproduces the Welcome.java fields and accesses (read-only id and read-write name). It also implements the code required for externalization mechanisms with lazy loading support. See Externalizers documentation for details.

The rest is only a matter of configuration files. First, create a new file named granite-config.xml at the root of the helloworld2 project directory with this content:

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

<!DOCTYPE granite-config PUBLIC "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/2.3.0/granite-config.dtd">



<granite-config>



    <class-getter type="org.granite.hibernate.HibernateClassGetter"/>



    <externalizers>

        <externalizer type="org.granite.hibernate.HibernateExternalizer">

            <include annotated-with="javax.persistence.Entity"/>

        </externalizer>

    </externalizers>



</granite-config>

        

This configuration instructs GDS to externalize all Java classes annotated with the @Entity annotation (such as our Welcome.java entity bean).

Next we need a Flex services-config.xml as follows. Create it in at root of the project, as for granite-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>

                    <factory>ejbFactory</factory>

                </properties>

            </destination>

        </service>

    </services>

    

    <factories>

        <factory id="ejbFactory" class="org.granite.messaging.service.EjbServiceFactory">

            <properties>

                <lookup>helloworld/{capitalized.destination.id}Bean/local</lookup>

            </properties>

        </factory>

    </factories>



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

        

This is where the destination id HelloWorldService is bound to our stateless EJB 3 session bean service. When the RemoteObject in HelloWorld.mxml is called, the destination id is used in the EjbServiceFactory to lookup the EJB; helloworld/{capitalized.destination.id}Bean/local is resolved to helloworld/HelloWorldServiceBean/local, that is the JNDI name used in JBoss to access the EJB.

We then need three additional configuration files: application.xml, persistence.xml and web.xml. All are standard J2EE configuration files and you will find detailed documentation on them on the Internet. Here is their contents. Again, create them at the root of the project:

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



<application>

    <display-name>GraniteDS HelloWorld</display-name>

    <module>

        <web>

            <web-uri>helloworld.war</web-uri>

            <context-root>/helloworld</context-root>

        </web>

    </module>

    <module>

        <ejb>helloworld.jar</ejb>

    </module>

</application>

        

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



<persistence>

    <persistence-unit name="ejb3">

        <jta-data-source>java:/DefaultDS</jta-data-source>

        <properties>

            <property name="hibernate.hbm2ddl.auto" value="update"/>

        </properties>

    </persistence-unit>

</persistence>

        

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

        

You should now see something like this in your package explorer:

The last thing to do is to build and deploy the application.

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 the properties FLEX_HOME and TOMCAT_HOME to reflect your environment:

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



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



    <!-- Modify FLEX_HOME/JBOSS_HOME properties to reflect your environment -->

    <property name="FLEX_HOME" value="/flex_sdk_3"/>

    <property name="JBOSS_HOME" value="/jboss-4.2.3.GA"/>

    

    <!-- 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">

            

            <source-path path-element="flex" />



            <!-- Make sure that the Welcome.as class is compiled into

                 our HelloWorld.swf (otherwise mxmlc doesn't include it

                 because there are no explicit reference to this class

                 in HelloWorld.mxml -->

            <includes symbol="org.test.Welcome" />

            

            <!-- Make sure that all "essentials" GDS classes are included into

                 our HelloWorld.swf (otherwise mxmlc doesn't include them

                 because there is no explicit reference to these classes

                 in HelloWorld.mxml and Welcome.as -->

            <compiler.include-libraries dir="lib" append="true">

                <include name="granite-essentials.swc" />

            </compiler.include-libraries>

        </mxmlc>

    </target>



    <!-- Build an ear suitable for JBoss -->

    <target name="ear" depends="mxmlc">

        <mkdir dir="build"/>

        <jar destfile="build/helloworld.jar">

            <fileset dir="bin" includes="**/*.class"/>

            <zipfileset file="persistence.xml" prefix="META-INF" />

        </jar>

        <war destfile="build/helloworld.war" webxml="web.xml">

            <zipfileset file="services-config.xml" prefix="WEB-INF/flex" />

            <zipfileset file="granite-config.xml" prefix="WEB-INF/granite" />

            <fileset dir="build" includes="*.swf"/>

        </war>

        <ear destfile="build/helloworld.ear" appxml="application.xml">

            <fileset dir="build" includes="*.jar,*.war"/>

            <zipfileset dir="lib" includes="granite*.jar" prefix="lib" />

        </ear>

    </target>



    <!-- Deploy the ear in JBoss -->

    <target name="deploy" depends="ear">

        <copy todir="${JBOSS_HOME}/server/default/deploy" file="build/helloworld.ear"/>

    </target>



</project>

        

Basically, this Ant build compiles our Flex code in a swf and package everything in an ear suitable for JBoss deployment.

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 an ear (Enterprise ARchive) and copy it into your JBoss deploy directory.

Finally start JBoss and test the application. To start JBoss, go to the directory bin just under your JBoss installation directory, /jboss-4.2.3.GA/bin for example, and double-click on run.bat, or run.sh for Unix/Mac users. After a short while, you should see in the console that JBoss has started. You may now point your Web browser to .

On the client there are two main choices :

The Tide remoting API is only a part of the Tide client framework (that supports dependency injection, conversation management, ...) so you can also choose between using the complete Tide framework or only Tide remoting mixed with any other Flex framework such as Cairngorm, PureMVC or Parsley. Obviously we recommend using only the Tide framework as it will greatly simplify the overall architecture of your application, but you will still able to use Tide even if higher powers force you using another particular framework.

Finally it's also possible to use the Tide client framework independently of the GraniteDS AMF provider. We really cannot recommend doing this if your server is Java-based but you can use Tide with AMFPHP, RubyAMF or any other server technology. The Tide framework is comparable in features to Swiz or Parsley but brings its own unique features and concepts (conversation contexts, centralized exception handling, data management...).

On the server there are mostly two options :

This section describes some classic technology stacks used with Flex applications and GraniteDS.

Spring/Hibernate on Tomcat 6+ or Jetty 6+

This is one of the most common use cases and is similar to what can be done with the Spring-BlazeDS integration project. You can furthermore benefit from the extensive support for serialization of Java objects and JPA detached objects, and of NIO/APR asynchronous support of Tomcat 6.0.18+ or Jetty 6 continuations.

EJB3/Hibernate on JBoss 4/5

This is another common use case and it provides roughly the same features than Spring/JPA. The main difference is that it requires a full EE container supporting EJB 3.

Tide/Spring/Hibernate on Tomcat 6+ or Jetty 6+

This is an extension of the first case, with the additional use of the Tide remoting API on the client. This will enable the most advanced features such as data paging, transparent lazy-loading of collections, real-time data synchronization... Tide also provides advanced client-side support for Spring Security authorization that for example allow to easily hide/disable buttons for unauthorized actions. This is currently the most popular technology stack.

Tide/EJB3/Hibernate on JBoss 4/5 or Tide/EJB3/EclipseLink on GlassFish v3

It's also similar to the previous case, but using EJB 3 instead of Spring.

Tide/Seam 2.2/Hibernate on JBoss 4/5

This is the most natural option if you want to connect your Flex application to a Seam 2 backend. Compared to Tide/Spring, it provides an even deeper integration with Seam including support for Seam events, Query, Seam application framework... If you are not sure of what stack you should use, we advise that you consider this stack as this is currently the most powerful and easy to use.

Tide/CDI/JPA2/Java EE 6 on JBoss 6/7 or GlassFish 3

Well this is not really a "common" stack but at least it is the latest Java EE 6 standard. If you are on a Java EE 6 compliant application server, it is definitely the best option.

The GraniteDS jars are available from the build folder of the distribution. You will always need granite.jar. Additionally you will have to include the jar corresponding to your server framework (granite-spring.jar for Spring for example), the jar for your JPA provider (granite-hibernate.jar for Hibernate) and the granite-beanvalidation.jar if you want to benefit from the integration with the Bean Validation API on the server.

At the most basic level, GraniteDS is implemented as a servlet (in fact a servlet and a filter) and thus has to be configured in web.xml. Here is a typical code snippet that maps the GraniteDS AMF servlet to /graniteamf/*. Of course it's possible to define a different URL mapping if required. It is also highly recommended to also add the configuration listener that will release resources on application undeployment.

<listener>

    <listener-class>org.granite.config.GraniteConfigListener</listener-class>

</listener>



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



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

        

The configuration of the various GraniteDS parts is done in the file WEB-INF/granite/granite-config.xml. There are many options that can be defined here, you can refer to the configuration reference.

As a starting point, you can create an empty file :

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

<!DOCTYPE granite-config PUBLIC "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/2.3.0/granite-config.dtd">



<granite-config/>

        

Or much easier a configuration that will use class scanning to determine the default setup.

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

<!DOCTYPE granite-config PUBLIC "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/2.3.0/granite-config.dtd">



<granite-config scan="true"/>

        

The last thing to define on the server is the application configuration in WEB-INF/flex/services-config.xml. This is for example the place where you will define which elements of your application you will expose to Flex remoting, or the topic for messaging. You can refer to the configuration reference for more details.

For example a simple configuration for an EJB 3 service would look like :

<services-config>

    <services>

        <service id="granite-service"

            class="flex.messaging.services.RemotingService"

            messageTypes="flex.messaging.messages.RemotingMessage">



            <destination id="example">

                <channels>

                    <channel ref="graniteamf"/>

                </channels>

                <properties>

                    <factory>ejbFactory</factory>

                </properties>

            </destination>

        </service>

    </services>



    <factories>

        <factory id="ejbFactory" class="org.granite.messaging.service.EjbServiceFactory">

            <properties>

                <lookup>myapp/{capitalized.destination.id}ServiceBean/local</lookup>

            </properties>

        </factory>

    </factories>



    <channels>

        <channel-definition id="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>

        

This configuration file declares 3 differents things, let's list them in the reverse order :

Depending on the kind of framework integration that is used, the services-config.xml file may not be necessary and can be omitted. With Spring and Seam for example, everything can be defined in the respective framework configuration files instead of services-config.xml.

GraniteDS comes with two client swc libraries that must be linked with your Flex application. The main library granite.swc should be linked with the standard mode (linked into code), but the core internal library granite-essentials.swc must be linked with the compiler option -include-libraries. When using the Tide client framework, you will also have to specify to the Flex compiler some annotations that should be kept in the swf for runtime usage. The following sections describe in more details the various options for different development environments.

When using a services-config.xml file, it's necessary to use the compiler option -services path/to/services-config.xml so the Flex SDK itself can handle the creation of the channel and other remoting objects. If you don't use this option, you will have to specify manually a channel and endpoint for each destination in ActionScript 3 :

private function init():void {
        srv = new RemoteObject("myService");
        srv.source = "myService";
        srv.channelSet = new ChannelSet();
        srv.channelSet.addChannel(new AMFChannel("graniteamf", 
            "http://{server.name}:{server.port}/myapp/graniteamf/amf"));
        srv.showBusyCursor = true;
}
        

Ant is a very popular and powerful build tool. The Flex SDK comes with a set of ant tasks that can perform various development tasks, notably the compilation of the Flex application to a swf file. The following XML code defines a typical target to build a Flex/GraniteDS application (the variable FLEX_HOME should point to your Flex SDK installation directory) :

<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar"/>



<target name="compile.flex" description="Build swf from Flex sources">

    <mxmlc

        file="flex/src/${flex.application}.mxml"

        output="bin-debug/${flex.application}.swf"

        services="path/to/services-config.xml"

        context-root="/myapp"

        use-network="false"

        debug="true"

        incremental="true">



        <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>



        <source-path path-element="${FLEX_HOME}/frameworks"/>

        <source-path path-element="bin-debug"/>

        

        <!-- Definition of runtime annotations, not required when not using Tide -->

        <keep-as3-metadata name="Bindable"/>

        <keep-as3-metadata name="Managed"/>

        <keep-as3-metadata name="ChangeEvent"/>

        <keep-as3-metadata name="NonCommittingChangeEvent"/>

        <keep-as3-metadata name="Transient"/>

        <keep-as3-metadata name="Id"/>

        <keep-as3-metadata name="Version"/>

        <keep-as3-metadata name="Lazy"/>

        <keep-as3-metadata name="Name"/>

        <keep-as3-metadata name="In"/>

        <keep-as3-metadata name="Inject"/>

        <keep-as3-metadata name="Out"/>

        <keep-as3-metadata name="Produces"/>

        <keep-as3-metadata name="Observer"/>

        <keep-as3-metadata name="ManagedEvent"/>

        <keep-as3-metadata name="PostConstruct"/>

        <keep-as3-metadata name="Destroy"/>



        <!-- All granite-essentials.swc classes must be included in the output swf -->

        <compiler.include-libraries dir="${gds.build}" append="true">

            <include name="granite-essentials.swc" />

        </compiler.include-libraries>



        <!-- Actually used only granite.swc classes are included in the output swf -->

        <compiler.library-path dir="${gds.build}" append="true">

            <include name="granite.swc"/>

        </compiler.library-path>

     </mxmlc>

 </target>

        

Maven is another popular build tool. Though GraniteDS is not itself built with Maven, its artifacts are available in the Maven central repository and can thus be easily added as dependencies to any Maven project.

The Java dependencies are in the group org.graniteds.

<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-core</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-hibernate</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



...

        

The Flex application can be built using the plugin. Here is a simple project descriptor for a Flex module :

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

<project xmlns="http://maven.apache.org/POM/4.0.0" 

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    

    <modelVersion>4.0.0</modelVersion>

  

    <groupId>com.myapp</groupId>

    <artifactId>myapp-flex</artifactId>

    <packaging>swf</packaging>

    <version>1.0-SNAPSHOT</version>

    <name>My Flex Module</name>



    <dependencies>

        <dependency>

            <groupId>com.adobe.flex.framework</groupId>

            <artifactId>flex-framework</artifactId>

            <version>${flex.framework.version}</version>

            <type>pom</type>

        </dependency>

        

        <dependency>

          <groupId>com.adobe.flexunit</groupId>

          <artifactId>flexunit</artifactId>

          <version>4.0-rc-1</version>

          <type>swc</type>

          <scope>test</scope>

        </dependency>    

        

        <dependency>

            <scope>internal</scope>

            <groupId>org.graniteds</groupId>

            <artifactId>granite-essentials-swc</artifactId>

            <version>${graniteds.version}</version>

            <type>swc</type>

        </dependency>

    

        <dependency>

            <groupId>org.graniteds</groupId>

            <artifactId>granite-swc</artifactId>

            <version>${graniteds.version}</version>

            <type>swc</type>

        </dependency>

    </dependencies>

  

    <build>

        <finalName>myapp</finalName>

        <sourceDirectory>src/main/flex</sourceDirectory>

        <testSourceDirectory>src/test/flex</testSourceDirectory>

    

        <pluginManagement>

            <plugins>

                <plugin>

                    <groupId>org.sonatype.flexmojos</groupId>

                    <artifactId>flexmojos-maven-plugin</artifactId>

                    <version>${flexmojos.version}</version>

                </plugin>

            </plugins>

        </pluginManagement>

        

        <plugins>

            <plugin>

                <groupId>org.sonatype.flexmojos</groupId>

                <artifactId>flexmojos-maven-plugin</artifactId>

                <version>${flexmojos.version}</version>

                <extensions>true</extensions>

                <dependencies>

                    <dependency>

                        <groupId>com.adobe.flex</groupId>

                        <artifactId>compiler</artifactId>

                        <version>${flex.framework.version}</version>

                        <type>pom</type>

                    </dependency>

                </dependencies>

                <configuration>

                    <contextRoot>/myapp</contextRoot>

                    <sourceFile>Main.mxml</sourceFile>

                    <incremental>true</incremental>

                    <keepAs3Metadatas>

                        <keepAs3Metadata>Bindable</keepAs3Metadata>

                        <keepAs3Metadata>Managed</keepAs3Metadata>

                        <keepAs3Metadata>ChangeEvent</keepAs3Metadata>

                        <keepAs3Metadata>NonCommittingChangeEvent</keepAs3Metadata>

                        <keepAs3Metadata>Transient</keepAs3Metadata>

                        <keepAs3Metadata>Id</keepAs3Metadata>

                        <keepAs3Metadata>Version</keepAs3Metadata>

                        <keepAs3Metadata>Lazy</keepAs3Metadata>

                        <keepAs3Metadata>Name</keepAs3Metadata>

                        <keepAs3Metadata>In</keepAs3Metadata>

                        <keepAs3Metadata>Out</keepAs3Metadata>

                        <keepAs3Metadata>Inject</keepAs3Metadata>

                        <keepAs3Metadata>Produces</keepAs3Metadata>

                        <keepAs3Metadata>PostConstruct</keepAs3Metadata>

                        <keepAs3Metadata>Destroy</keepAs3Metadata>

                        <keepAs3Metadata>Observer</keepAs3Metadata>

                        <keepAs3Metadata>ManagedEvent</keepAs3Metadata>

                    </keepAs3Metadatas>

                </configuration>

            </plugin>

        </plugins>

    </build>

</project>

        

Building a full Flex / Java EE Web application with Maven is rather complex and requires to create a multi-module parent project with 3 modules : a Java module, a Flex module and a Web application module, each having its own pom.xml, dependencies and plugin configurations. It is thus recommended that you start from one of the existing GraniteDS/Maven archetypes :

Note than using Maven 3 is highly recommended but Maven 2.2 should also work. A project can then be created using the following command :

mvn archetype:generate
	-DarchetypeGroupId=org.graniteds.archetypes
	-DarchetypeArtifactId=graniteds-tide-spring-jpa-hibernate
	-DarchetypeVersion=1.1.0.GA
	-DgroupId=com.myapp
	-DartifactId=springflexapp
	-Dversion=1.0-SNAPSHOT
        

To build the application, just run :

cd springflexapp
mvn install
        

The Spring and Seam archetypes define a Jetty run configuration so you can simply test your application with :

cd webapp
mvn jetty:run-war
		

The CDI archetype defines an embedded GlassFish run configuration so you can test your application with :

cd webapp
mvn embedded-glassfish:run
        

To deploy your application to another application server (for example Tomcat), you may have to change the Gravity servlet in web.xml. Then you can build a war file with :

cd webapp
mvn war:war
		

There are different options for working with Flash Builder. The easiest is to use a single combined Flex/Java project that will contain the source files for both the server and client parts of the application.

You should install the GraniteDS Eclipse Builder plugin (see here) so you can benefit from the automatic Java -> AS3 code generation. In can be installed in a standalone Flex/Flash Builder or in an Eclipse installation with the Flash Builder plugin.

The first step is to create a new Java EE Web project. You can use the Eclipse WTP wizard (File / New / Web / Dynamic Web Project) :

Change the name of the source folder to java instead of src to avoir conflicts with the Flex source folder we will add later.

Then copy the necessary GraniteDS libs in the folder WebContent/WEB-INF/lib. That should be fine for the Java side.

Next add the Flex nature to the project by right-clicking on the project and selecting Add/Change Project Type / Add Flex Project Type.... Then follow the steps on the wizard.

You may want to change the target build folder of Flex to WebContent so the target swf will be directly compiled in the exploded war folder.

You should change the source folder to flex in the project properties in Flex Build Path and set the target url so the Flex debugger will connect to the application deployed on the server :

Next copy the GraniteDS client libraries granite.swc and granite-essentials.swc to the libs folder, and configure the compiler options in the project properties in Flex Compiler :

Finally we add the GraniteDS nature to the project with right-click / Add GraniteDS Nature. Remember to change the target folder to flex. The GraniteDS properties should like this :

If you have configured a target server (Tomcat for example), you now have a complete environment to run your application. All changes to the Flex application will be automatically deployed to Tomcat thanks to the Eclipse WTP publishing of the WebContent folder.

RemoteObject is the standard remoting API of the Flex SDK. It can be use either declaratively in MXML or programmatically in ActionScript. A RemoteObject is attached to a server-side destination, generally defined in the services-config.xml (see the configuration reference). You can also refer to the about RemoteObject to get some useful information.

public class HelloService {


    public String hello(String name) {

        return "Hello " + name; 

    }

}

            

<services>

    <service

        id="granite-service"

        class="flex.messaging.services.RemotingService"

        messageTypes="flex.messaging.messages.RemotingMessage">

        <destination id="hello">

            <channels>

                <channel ref="graniteamf"/>

            </channels>

            <properties>

                <scope>request</scope>

                <source>com.myapp.HelloService</source>

            </properties>

        </destination>

    </service>

</services>



<channels>

    <channel-definition id="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>

            

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">



    <mx:Script>

        import mx.rpc.events.ResultEvent;

        import mx.rpc.events.FaultEvent;

        import mx.controls.Alert;

        

        public function resultHandler(event:ResultEvent):void {

            // Display received message

            outputMessage.text = event.result as String;

        }                       

        

        public function faultHandler(event:FaultEvent):void {

            // Show error alert

            Alert.show(event.fault.faultString);               

        }

    </mx:Script>

    

    <!-- Connect to a service destination.--> 

    <mx:RemoteObject id="helloService" 

        destination="hello"

        result="handleResult(event);"

        fault="handleFault(event);"/>

    

    <!-- Provide input data for calling the service. --> 

    <mx:TextInput id="inputName"/>

    

    <!-- Call the web service, use the text in a TextInput control as input data.--> 

    <mx:Button click="helloService.hello(inputName.text)"/>

    

    <!-- Display results data in the user interface. --> 

    <mx:Label id="outputMessage"/>

</mx:Application>

            

<mx:RemoteObject id="helloService" 

        destination="hello">

    <mx:operation name="hello" 

        result="handleResult(event);"

        fault="handleFault(event);"/>

    <mx:operation name="..."

        result="..."

        fault="..."/>

</mx:RemoteObject>

            

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">



    <!-- Connect to a service destination.--> 

    <mx:RemoteObject id="helloService" destination="hello"/>

    

    <!-- Provide input data for calling the service. --> 

    <mx:TextInput id="inputName"/>

    

    <!-- Call the web service, use the text in a TextInput control as input data.--> 

    <mx:Button click="helloService.hello(inputName.text)"/>

    

    <!-- Display results data in the user interface using binding on the lastResult property of AsyncToken. --> 

    <mx:Label id="outputMessage" text="{helloService.hello.lastResult}"/>

</mx:Application>

            

package com.myapp.model;


public class Person {


    private String name;


    public String getName() { 

        return name; 

    }

    public void setName(String name) { 

        this.name = name;

    }

}

            

package com.myapp.model {
		
	[RemoteClass(alias="com.myapp.model.Person")]
	public class Person {
		public var name:String;
	}
}
	        

public class PeopleService {


    public List<Person> findAll(Person examplePerson) {

        ...

        return list;    

    }

}

            

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">



    <!-- Connect to a service destination.--> 

    <mx:RemoteObject id="peopleService" 

        destination="people"

        result="handleResult(event);"

        fault="handleFault(event);"/>

    

    <!-- Provide input data for calling the service. --> 

    <mx:TextInput id="inputName"/>

    

    <!-- Call the web service, use the text in a TextInput control as input data.--> 

    <mx:Button click="peopleService.findAll(inputName.text)"/>

    

    <!-- Display results data in the user interface. --> 

    <mx:DataGrid id="outputGrid" dataProvider="{peopleService.lastResult}"/>

</mx:Application>

            

package com.myapp.controllers {

 	import mx.rpc.events.ResultEvent;
 	import mx.rpc.events.FaultEvent;
 	import mx.rpc.remoting.mxml.RemoteObject;
 	import mx.controls.Alert;

	public class HelloController {

		private var helloService:RemoteObject;

		public function HelloController():void {
            // Initialize a remote destination
            helloService = new RemoteObject("pojo");
            helloService.addEventListener(ResultEvent.RESULT, resultHandler, false, 0, true);
            helloService.addEventListener(FaultEvent.FAULT, faultHandler, false, 0, true);
        }
        
        private function resultHandler(event:ResultEvent):void {
            // Handler result
        }                       
        
        private function faultHandler(event:FaultEvent):void {
            // Handle fault
        }
    }
}
    		

package com.myapp.controllers {

 	import mx.rpc.events.ResultEvent;
 	import mx.rpc.events.FaultEvent;
 	import mx.rpc.remoting.mxml.RemoteObject;
 	import mx.controls.Alert;

	public class HelloController {

		private var helloService:RemoteObject;

 		public function HelloController():void {
			// Initialize a remote destination
			helloService = new RemoteObject("hello");
			helloService.source = "com.myapp.HelloService";
			// Setup the channel set and endpoint for the RemoteObject 
			helloService.channelSet = new ChannelSet();
			helloService.channelSet.addChannel(new AMFChannel("graniteamf", 
			     "http://{server.name}:{server.port}/myapp/graniteamf/amf"));
			helloService.addEventListener(ResultEvent.RESULT, resultHandler, false, 0, true);
			helloService.addEventListener(FaultEvent.FAULT, faultHandler, false, 0, true);
		}
        
		private function resultHandler(event:ResultEvent):void {
			// Handle result
		}                       
        
		private function faultHandler(event:FaultEvent):void {
			// Handle fault
		}
    }
}
		  

<services>

    ...

</services>



<channels>

    <channel-definition id="graniteamf" class="mx.messaging.channels.SecureAMFChannel">

        <endpoint

            uri="https://{server.name}:{server.port}/{context.root}/graniteamf/amf"

            class="flex.messaging.endpoints.AMFEndpoint"/>

    </channel-definition>

</channels>

            

<security-constraint>

    <display-name>AMF access</display-name>

    <web-resource-collection>

        <web-resource-name>Secure AMF remoting</web-resource-name>

        <description>Secure AMF Remoting</description>

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

    </web-resource-collection>

    <auth-constraint>

        <role-name>role1</role-name>

        ...

    </auth-constraint>

    <user-data-constraint>

        <transport-guarantee>CONFIDENTIAL</transport-guarantee>

    </user-data-constraint>

</security-constraint>

            

The Tide remoting API is an alternative to the standard RemoteObject. It can be used only programmatically in ActionScript and simplifies the handling of asynchronicity by hiding AsyncToken and other internal objects. Note that Tide provides much more than just a different API, it will be detailed in the next chapters.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>

        import org.granite.tide.Tide;

        import org.granite.tide.Context;

        import org.granite.tide.events.TideResultEvent;

        import org.granite.tide.events.TideFaultEvent;

        

        private var tideContext:Context = Tide.getInstance().getContext();

        

        private function hello(name:String):void {

            // tideContext.helloService implicitly creates a proxy for the remote destination named helloService

            tideContext.helloService.hello(name, resultHandler, faultHandler);

        }

        

        private function resultHandler(event:TideResultEvent):void {

            outputMessage.text = event.result as String;

        }                       

        

        private function faultHandler(event:TideFaultEvent):void {

            // Handle fault

        }

    </mx:Script>

    

    <!-- Provide input data for calling the service. --> 

    <mx:TextInput id="inputName"/>

    

    <!-- Call the web service, use the text in a TextInput control as input data.--> 

    <mx:Button click="hello(inputName.text)"/>

    

    <!-- Result message. --> 

    <mx:Label id="outputMessage"/>

</mx:Application>

            

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"

    creationComplete="Tide.getInstance().initApplication()">

    <mx:Script>

        import org.granite.tide.Tide;

        import org.granite.tide.events.TideResultEvent;

        import org.granite.tide.events.TideFaultEvent;

        

        [In]

        public var helloService:Component;

        

        private function hello(name:String):void {

            helloService.hello(name, resultHandler, faultHandler);

        }

        

        private function resultHandler(event:TideResultEvent):void {

            outputMessage.text = event.result as String;

        }                       

        

        private function faultHandler(event:TideFaultEvent):void {

            // Handle fault

        }

    </mx:Script>

    

    <!-- Provide input data for calling the service. --> 

    <mx:TextInput id="inputName"/>

    

    <!-- Call the web service, use the text in a TextInput control as input data.--> 

    <mx:Button click="hello(inputName.text)"/>

    

    <!-- Result message. --> 

    <mx:Label id="outputMessage"/>

</mx:Application>

            

public function call():void {
    var responder1:TideResponder = new TideResponder(helloResult, helloFault, "firstCall");
    var responder2:TideResponder = new TideResponder(helloResult, helloFault, "secondCall");
    tideContext.helloWorld.sayHello("Jimi", responder1);
    tideContext.helloWorld.sayHello("Jimi", responder2);
}

private function helloResult(event:TideResultEvent, token:Object):void {
    if (token == "firstCall")
        Alert.show(event.result);
}
	        

private var products:ArrayCollection = new ArrayCollection();

public function call():void {
    tideContext.productService.findAllProducts(
        new TideResponder(resultHandler, null, null, products)
    );
}

private function resultHandler(event:TideResultEvent):void {
   trace("Assert result was merged: " + (event.result === products));
}
	        

<mx:DataGrid dataProvider="{products}">

   ...

</mx:DataGrid>

            

Tide.getInstance().addComponentWithFactory("serviceInitializer", DefaultServiceInitializer, 
    { contextRoot: "/context-root" }
);
	        

public class MyMessageInterceptor implements IMessageInterceptor {
    public function before(msg:IMessage):void {
        showWaitScreen();
        msg.headers['customHeader'] = 'test';
    }

    public function after(msg:IMessage):void {
        var customHeader:String = msg.headers['customHeader'] as String;
        hideWaitScreen();
    }
}
	        

public class EntityNotFoundExceptionConverter implements ExceptionConverter {


    public static final String ENTITY_NOT_FOUND = "Persistence.EntityNotFound";

    

    public boolean accepts(Throwable t, Throwable finalException) {

        return t.getClass().equals(javax.persistence.EntityNotFoundException.class);

    }


    public ServiceException convert(

        Throwable t, String detail, Map<String, Object> extendedData) {


        ServiceException se = new ServiceException(

            ENTITY_NOT_FOUND, t.getMessage(), detail, t

        );

        se.getExtendedData().putAll(extendedData);

        return se;

    }

}

            

public class EntityNotFoundExceptionHandler implements IExceptionHandler {

    public function accepts(emsg:ErrorMessage):Boolean {
        return emsg.faultCode == "Persistence.EntityNotFound";
    }

    public function handle(context:BaseContext, emsg:ErrorMessage):void {
        Alert.show("Entity not found: " + emsg.message);
    }
}
            

<mx:Application>

    <mx:Script>

        Tide.getInstance().addExceptionHandler(EntityNotFoundExceptionHandler);

    </mx:Script>

</mx:Application>

            

When using typed objects, it's necessary to create an ActionScript 3 class for each Java class that will be marshalled between Flex and Java. However due to the differences of data types in the ActionScript 3 and Java languages, data conversions are done during serialization/deserialization. GraniteDS follows the standard conversions specified in the Adobe Flex SDK documentation , with an important exception : GDS will neither convert AS3 String to Java numeric types or boolean, nor AS3 numeric types or boolean to String. You must use AS3 numeric types for Java numeric types and AS3 boolean type for Java boolean types; either primitive or boxed boolean.

Starting with GraniteDS 2.2, long, Long, BigInteger and BigDecimal values may by converted to their respective ActionScript 3 equivalent (see Big Number Implementations for details).

In some cases it can be necessary to serialize private fields of a Java class (for example the @Version field of a JPA entity). Due to the limited capabilities of the ActionScript 3 reflection API than cannot access private fields, it is necessary to create an externalizable AS3 class (implementing flash.utils.IExternalizable and its corresponding externalizable Java class. In both classes you have to implement two methods readExternal and writeExternal that read and write data to the network stream in the exact same order. This is extremely tedious and unmaintainable, so GraniteDS provides a specific mechanism to handle this almost transparently :

By means of these two combined mechanisms, it's possible to serialize any kind of object with minimal effort.

package com.myapp.entity;

import java.io.Serializable;

import javax.persistence.Basic;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Version;

@Entity
public class Person implements Serializable {

    private static final long serialVersionUID = 1L;

    @Id @GeneratedValue
    private Integer id;

    @Version
    private Integer version;

    @Basic
    private String firstName;

    @Basic
    private String lastName;

    public Integer getId() {
        return id;
    }

    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}
			

/**
 * Generated by Gas3 v2.2.0 (Granite Data Services).
 *
 * WARNING: DO NOT CHANGE THIS FILE. IT MAY BE OVERWRITTEN EACH TIME YOU USE
 * THE GENERATOR. INSTEAD, EDIT THE INHERITED CLASS (Person.as).
 */

package com.myapp.entity {

    import flash.utils.IDataInput;
    import flash.utils.IDataOutput;
    import flash.utils.IExternalizable;
    import org.granite.collections.IPersistentCollection;
    import org.granite.meta;

    use namespace meta;

    [Bindable]
    public class PersonBase implements IExternalizable {

        private var __initialized:Boolean = true;
        private var __detachedState:String = null;

        private var _firstName:String;
        private var _id:Number;
        private var _lastName:String;
        private var _version:Number;

        meta function isInitialized(name:String = null):Boolean {
            if (!name)
                return __initialized;

            var property:* = this[name];
            return (
                (!(property is Person) || (property as Person).meta::isInitialized()) &&
                (!(property is IPersistentCollection) ||
                  (property as IPersistentCollection).isInitialized())
            );
        }

        public function set firstName(value:String):void {
            _firstName = value;
        }
        public function get firstName():String {
            return _firstName;
        }

        public function get id():Number {
            return _id;
        }

        public function set lastName(value:String):void {
            _lastName = value;
        }
        public function get lastName():String {
            return _lastName;
        }

        public function readExternal(input:IDataInput):void {
            __initialized = input.readObject() as Boolean;
            __detachedState = input.readObject() as String;
            if (meta::isInitialized()) {
                _firstName = input.readObject() as String;
                _id = function(o:*):Number {
                    return (o is Number ? o as Number : Number.NaN) } (input.readObject());
                _lastName = input.readObject() as String;
                _version = function(o:*):Number {
                    return (o is Number ? o as Number : Number.NaN) } (input.readObject());
            }
            else {
                _id = function(o:*):Number {
                    return (o is Number ? o as Number : Number.NaN) } (input.readObject());
            }
        }

        public function writeExternal(output:IDataOutput):void {
            output.writeObject(__initialized);
            output.writeObject(__detachedState);
            if (meta::isInitialized()) {
                output.writeObject(_firstName);
                output.writeObject(_id);
                output.writeObject(_lastName);
                output.writeObject(_version);
            }
            else {
                output.writeObject(_id);
            }
        }
    }
}
	        

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



<!DOCTYPE granite-config PUBLIC

    "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/2.3.0/granite-config.dtd">



<granite-config>

    <class-getter type="org.granite.hibernate.HibernateClassGetter"/>



    <externalizers>

        <externalizer type="org.granite.hibernate.HibernateExternalizer">

            <include type="com.myapp.entity.Person"/>

        </externalizer>

    </externalizers>

</granite-config>

            

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



<!DOCTYPE granite-config PUBLIC

    "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/2.3.0/granite-config.dtd">



<granite-config>

    <class-getter type="org.granite.hibernate.HibernateClassGetter"/>



    <externalizers>

        <externalizer type="org.granite.hibernate.HibernateExternalizer">

            <include instance-of="com.myapp.entity.AbstractEntity"/>

        </externalizer>

    </externalizers>

</granite-config>