Using Flex with Spring

UPDATE (1/27/2008): The approach described in this article is now obsolete. Adobe and SpringSource are now collaborating on an open source project called: Spring BlazeDS integration. You can read more about the project and download the bits here: http://www.springsource.org/spring-flex. I also wrote a Test Drive providing out-of-the-box examples using this project. The test drive is available here.

UPDATE (1/12/2007): I put together a Tomcat-based Test Drive Server that includes the samples described below running out-of-the box. Read this post for more info.

What is Spring?

Spring is one of the most popular Java frameworks. The foundation of the Spring framework is a lightweight component container that implements the Inversion of Control (IoC) pattern.

Using an IoC container, components don’t instantiate or even look up their dependencies (the objects they work with). The container is responsible for injecting those dependencies when it creates the components (hence the term “Dependency Injection” also used to describe this pattern).

The result is looser coupling between components. The Spring IoC container has proven to be a solid foundation for building robust enterprise applications. The components managed by the Spring IoC container are called Spring beans.

The Spring framework includes several other modules in addition to its core IoC container. These modules are not covered in this document even though we will be using the Spring JDBC abstraction framework in examples 2 and 3 below. More information on the Spring framework can be found at http://www.springframework.org.

What is Flex?

Flex provides a complete solution for building Rich Internet Applications. The Flex programming model is made of:

• ActionScript, an ECMAScript compliant, object-oriented programming model. With some syntactical differences, ActionScript looks and feels similar to Java, and supports the same object-oriented constructs: packages, classes, inheritance, interfaces, strong (but also dynamic) typing etc.
• MXML: an XML-based language that provides an abstraction on top of ActionScript, and allows parts of an application (typically the View) to be built declaratively.
• An extensive set of class libraries. The online API documentation is available here in a Javadoc-like format.

The Flex source code (.mxml and .as files) is compiled into Flash bytecode (.swf) that is executed at the client-side by the Flash virtual machine using a Just-In-Time compiler.

A complete discussion of Flex is beyond the scope of this document. You can find more information at http://www.adobe.com/products/flex.

How does Flex access back-end systems?

When writing Flex applications, you can access back-end systems using four different strategies:

1. You can use the HTTPService component to send HTTP requests to a server, and consume the response. Although the HTTPService is typically used to consume XML, it can be used to consume other types of responses. The Flex HTTPService is similar to the XMLHttpRequest component available in Ajax.
2. You can use the WebService component to invoke SOAP-based web services.
3. You can use the RemoteObject component to directly invoke methods of Java objects deployed in your application server, and consume the return value. The return value can be a value of a primitive data type, an object, a collection of objects, an object graph, etc. In distributed computing terminology, this approach is generally referred to as “remoting”. This is also the terminology used in Spring to describe how different clients can access Spring beans remotely.
4. In addition to the RPC-type services described above, the Flex Data Management Services provide an innovative and virtually code-free approach to synchronize data between the client application and the middle-tier.

In this document, we focus on the Remoting (3) and Data Management Services (4) approaches described above because they enable the tightest integration with Spring. There is no need to transform data, or to expose services in a certain way: the Flex application works directly with the beans registered in the Spring IoC container.

How does Flex access Spring beans?

So, if Flex clients can remotely access Java objects, and if Spring beans are Java objects, aren’t we all set and ready to start accessing Spring beans from Flex clients? Almost… There is one simple element to configure.

The whole idea behind Spring IoC is to let the container instantiate components (and inject their dependencies). By default, however, components accessed remotely by a Flex client are instantiated by Flex destinations at the server-side. The key to the Flex/Spring integration is therefore to configure the Flex destinations to let the Spring container take care of instantiating Spring beans. The Flex Data Services support the concept of factory to enable this type of custom component instantiation. The role of a factory is simply to provide ready-to-use instances of components to a Flex destination (instead of letting the Flex destination instantiate these components itself).

The supporting files available with this document include a factory class (SpringFactory) that provides Flex destinations with fully initialized (dependency-injected) instances of Spring beans. Note: The SpringFactory was developed by Jeff Vroom (Flex Data Services architect) and is also available on Adobe Exchange.

The remaining of this article describes how to configure your web application to use Flex and Spring, how to configure the Spring Factory, and how to put the pieces together and start invoking Spring beans from Flex applications.

Setting Up your Web Application to Use Flex and Spring

Step 1: Install the supporting files

1. Download flex-spring.zip here
2. Expand flex-spring.zip

flex-spring.zip includes the Spring factory as well as the supporting files for the examples below.

Step 2: Install Flex Data Services

To use the Remoting and Data Management Services data access strategies described above, you need to install the Flex Data Services. If you haven’t already done so, you can download the Flex Data Services here, and follow the installation instructions.

The installation process will install three web applications (flex, samples, and flex-admin). You can use either the flex or samples web application to run the examples below.

You can read more information on the installation process here: http://www.adobe.com/support/documentation/en/flex/2/install.html#installingfds2

Step 3: Install Spring

Note: A complete discussion of the Spring installation process is beyond the scope of this article. Refer to http://www.springframework.org for more information. The steps below describe a basic configuration that is sufficient for the purpose of this article.

1. Download the Spring framework (version 2.0) at http://www.springframework.org/download (the version without dependencies is sufficient to complete the examples in this article).
   
   Note: The examples below have been developed and tested using Spring 2.0. However the integration approach described in this document (and the SpringFactory class) should work fine using Spring 1.2.8 (some of the examples might not work because they use Spring 2.0 features).
2. Expand the downloaded file
3. Locate spring.jar in the dist directory and copy it in the {context-root}\WEB-INF\lib directory of your web application
4. Modify the web.xml file of your web application. Add the context-param and listener definitions as follows:

   [/xml]
   <context-param>
       <param-name>contextConfigLocation</param-name>
       <param-value>/WEB-INF/applicationContext.xml</param-value>
   </context-param>
   
   <listener>
       <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
   </listener>
   </pre>
   </li>
   </ol>
   <h3>Step 4: Register the Spring Factory</h3>
   <ol>
     <li>Copy SpringFactory.class and SpringFactory$SpringFactoryInstance.class  from flex-spring-sdk\bin\flex\samples\factories to {context-root}\WEB-INF\classes\flex\samples\factories</li>
     <li>Register the Spring factory in {context-root}\WEB-INF\flex\services-config.xml:
   [xml]

   
   
   

Example 1: Mortgage Calculator Using Flex Remoting

This first application is intentionally simplistic in its functionality to provide an uncluttered example of wiring Spring beans together and invoking them from a Flex application.

Step 1: Copy the application files

1. Copy RateFinder.class, SimpleRateFinder.class, and Mortgage.class from flex-spring-sdk\bin\flex\samples\spring\mortgage to {context-root}\WEB-INF\classes\flex\samples\spring\mortgage
2. Copy mortgage.mxml from flex-spring-sdk\flex\mortgage to {context-root}\mortgage

Step 2: Register Spring Beans

1. Before registering the Spring beans for this application, open RateFinder.java, SimpleRateFinder.java and Mortgage.java in flex-spring-sdk\src\flex\samples\spring\mortgage to familiarize yourself with the source code. Notice that Mortgage has a dependency to a RateFinder object. Mortgage doesn’t instantiate a RateFinder object itself, doesn’t lookup up for a RateFinder object, and doesn’t even know the exact type of the object it will be dealing with (RateFinder is an inteface). An instance of a class implementing the RateFinder interface will be injected by the container (using the setRateFinder method) when it instantiates the component.
2. If it doesn’t already exist, create a file named applicationContext.xml in {context-root}\WEB-INF.
3. Register the rateFinderBean and mortgageBean beans in applicationContext.xml as follows: 

   [/xml]
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
   
   <beans>
   
       <bean id="rateFinderBean" class="flex.samples.spring.mortgage.SimpleRateFinder"/>
   
       <bean id="mortgageBean" class="flex.samples.spring.mortgage.Mortgage">
             <property name="rateFinder" ref="rateFinderBean"/>
       </bean>
   
   </beans>
   </pre>
   Notice that in the mortgageBean  definition, we tell the container how to inject the rateFinder dependency: the  rateFinder property is mapped to rateFinderBean which defines an instance of  the SimpleRateFinder class.
   </li></ol>
   
   <h3>Step 3: Configure the Flex Remoting Destination</h3>
   <ol>
     <li>Open remoting-config.xml in  {context-root}\WEB-INF\flex.</li>
     <li>Add a mortgageService destination as follows: &nbsp;&nbsp;
   [xml]

   spring
   mortgageBean

   Notice that we use the spring factory defined above (see “Register the Spring Factory”), and we provide the name of the Spring bean as defined in applicationContext.xml as the source.

Step 4: Run the Client Application

1. Open {context-root}\mortgage\MortgageCalc.mxml in a code editor to familiarize yourself with the application. Notice that the RemoteObject destination is the mortgageService destination defined above.
2. Open a browser, access http://host:port/context-root/mortgage/MortgageCalc.mxml, and test the application: Enter a loan amount and click “Calculate” to get the monthly payment for a 30 year mortgage.

Note: that there is a delay the first time you access an application in this manner. This is because we are using the web compiler which compiles your application into bytecode the first time it is accessed (similar to the JSP compilation model). Subsequent requests to the same application will be much faster since the application is already compiled. In a production environment, you would typically deploy applications that have already been compiled using the Flex compiler available as a command-line utility or fully integrated in FlexBuilder (the Eclipse-based development environment for Flex).
Depending on your configuration, you may need to increase the heap size of your application server's JVM to use the web compiler. This would not be required in a production environment since you typically don't use the web compiler. If you get a java.lang.OutOfMemoryError exception while trying to access a sample for the first time, you must increase your heap size. Alternatively, you can compile the application using FlexBuilder or the command line compiler.

Example 2: Store/Inventory Management using Flex Remoting

This second example is more sophisticated and includes database connectivity. To keep the application simple and avoid dependencies on other products or frameworks, the Spring JDBC abstraction framework is used to access the database. You could use the Spring support for ORM data access (using Hibernate, JDO, Oracle TopLink, iBATIS, or JPA) as an alternative: the specific Spring data access strategy you choose has no impact on the Flex/Spring integration. We use an embedded HSQLDB database: the only installation requirement is to copy the HSQLDB driver in your web application classpath (see below). The application has two modules: a database maintenance module, and a customer-facing product catalog with filtering capabilities.

Step 1: Copy the application files

1. Copy hsqldb.jar to {context-root}\WEB-INF\lib. You can download the hsqldb driver at http://www.hsqldb.org/.
2. Copy ProductDAO.class, SimpleProductDAO.class, SimpleProductDAO$1.class, and Product.class from flex-spring-sdk\bin\flex\samples\spring\store to {context-root}\WEB-INF\classes\flex\samples\spring\store
3. Copy admin.mxml, ProductForm.mxml, store.mxml, Thumb.mxml, AnimatedTileList.as, Product.as, logo.jpg, store.css and the pic directory from flex-spring-sdk\flex\store to {context-root}\store

Step 2: Register Spring Beans

1. Before registering the Spring beans for this application, open ProductDAO.java, SimpleProductDAO.java and Product.java in flex-spring-sdk\src\flex\samples\spring\store to familiarize yourself with the source code. Notice that SimpleProductDAO extends org.springframework.jdbc.core.support.JdbcDaoSupport. JdbcDaoSupport has a dependency to a javax.sql.DataSource object (javax.sql.DataSource is an interface).
2. Register the dataSource and productDAOBean beans in applicationContext.xml as follows: 

   [/xml]
   <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
       <property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
       <property name="url" value="jdbc:hsqldb:/flex-spring-sdk/db/store"/>
       <property name="username" value="sa"/>
       <property name="password" value=""/>
   </bean>
   
   <bean id="productDAOBean" class="flex.samples.spring.store.SimpleProductDAO">
       <property name="dataSource" ref="dataSource"/>
   </bean>
   </pre>
   Note: If you didn't unzip flex-spring-sdk in your root directory, adjust the JDBC url accordingly.
   </li>
   </ol>
   <h3>Step 3: Configure the Flex Remoting Destination</h3>
   <ol>
     <li>Open remoting-config.xml in  {context-root}\WEB-INF\flex.</li>
     <li>Add the productService destination as follows:&nbsp;&nbsp;
   [xml]

   spring
   productDAOBean

Step 4: Run the Client Application

Test the database maintenance module:

1. Open {context-root}\store\admin.mxml in a code editor and familiarize yourself with the application.
2. Open a browser, access http://host:port/context-root/store/admin.mxml, and test the application.

Test the store module:

1. Open {context-root}\store\store.mxml in a code editor and familiarize yourself with the application.
2. Open a browser, access http://host:port/context-root/store/store.mxml, and test the application.

Example 3: Data Management Services

In addition to the RPC services used in examples 1 and 2 above, the Flex Data Management Services provide an innovative and very productive approach to synchronize data between the client and the middle-tier. The Flex Data Management Services consist of a client-side API and server-side services:

• At the client-side, "managed objects" keep track of changes made to the data, and notify the back-end of these changes. You don't have to keep track of changes made to the data, nor do you have to invoke remote services to notify the back-end of the changes (create, update, delete) made at the client side.
• At the server-side, the Data Service receives the list of changes and passes it to your server-side persistence components. The Data Service also pushes the changes to other clients.

This application provides an example of using the Flex Data Management Services with the Spring IoC container.

Note: The Flex Data Management Services leverage the Java Transaction API (JTA). If you are using Tomcat, or another servlet container that doesn't provide a full implementation of the J2EE stack, you have to install a JTA implementation such as JOTM to run this example. Click here for more information.

Step 1: Copy the application files

1. Copy ProductAssembler.class from flex-spring-sdk\bin\flex\samples\spring\store to {context-root}\WEB-INF\classes\flex\samples\spring\store
2. Copy dms.mxml and Product.as from flex-spring-sdk\flex\dms to {context-root}\dms

Step 2: Register Spring Beans

1. Open ProductAssembler.java in a code editor. Notice that ProductAssembler has a dependency to a ProductDAO object.
2. Register the productAssemblerBean in applicationContext.xml as follows:

   [/xml]
   <bean id="productAssemblerBean" class="flex.samples.spring.store.ProductAssembler">
       <property name="productDAO" ref="productDAOBean"/>
   </bean>
   </pre>
   </li>
   </ol>
   <h3>Step 3: Configure the Flex Data Management Services Destination</h3>
   <ol>
     <li>Open data-management-config.xml in  {context-root}\WEB-INF\flex.</li>
     <li>Add the product destination as follows:
   [xml]

   
   

   productAssemblerBean
   spring
   
   
   

Step 4: Run the Client Application

1. Open {context-root}\dms\dms.mxml in a code editor and familiarize yourself with the application.
2. Open a browser, access http://host:port/context-root/dms/dms.mxml, and test the application.