Web App Solution Blog

Introduction

I’ve been playing around with a stack of Flex/ActionScript and Java frameworks and finally came up with one that I’m really pleased with — since I’m reusing these terms throughout the series, please review the acronyms after each, as that’s how I’ll be referring to them in the tutorial:

• Flex
• Cairngorm (”CG”)
  
• Spring ActionScript (”SAS”), formerly Prana
• Tomcat (”TC”)
  
• WebORB (”WORB”) / BlazeDS (”BDS”)
  
• Spring, Server-side Java version
• Hibernate (”HB”)
  
• MySQL

To that, I’m planing on writing a series of tutorials where each one builds on the previous one. The final tutorial will cover: Flex + Cairngorm + Spring ActionScript + Tomcat + WebORB/BlazeDS + Spring Java + Spring Security + Hibernate + MySQL

• Part 1: Basic Flex + CG Application
• Part 2: Flex + CG + SAS
• Part 3: Flex + CG + SAS + Injecting Services into Business Delegates
• Part 4: Integrated Flex Project + Java Project with Tomcat

Part 2 in our series will focus on the introduction of  the Spring ActionScript framework (”SAS”) to our existing Flex + Cairngorm (”CG”) application from Part 1.

Tutorial Goal: Flex + Cairngorm + Spring ActionScript

Build upon the existing, foundational Flex + CG application by adding SAS and injecting the desired CG Business Delegate (”BD”) at runtime; we’ll continue working with the mock-object EmployeeASDelegate, but also add a XML based BD called EmployeeXMLDelegate so we can choose our data provider at runtime. After this tutorial you should know why and how to use SAS with CG.

Assets:

• Project Demo
• Project View Source
• Project Source Files

Prerequisites & Assumptions

• Ability to create Flex and ActionScript classes with Flex Builder (”FB”). NOTE: I’m actually using Eclipse WTP with the Flex Builder Plugin so I can develop in both Java/J2EE and Flex projects in one IDE.
• Used or understand Cairngorm’s basic flow and how it all fits together. If you haven’t, I recommend looking at Part 1 of this tutorial and the Cairngorm Diagram for some reference.
• Understanding of OOP and basic Design Patterns.
• NOTE: Most of the code snippets are truncated to be concise and only highlight the lines of code that truly deserve the readers attention, so it’s highly recommended that readers download the accompanying project source files in order to follow along.

What This Tutorial is Not

There’s actually a set of extensions for SAS for both CG and PureMVC (”PMVC”), but since CG is more widely used and I want to keep things simple, this tutorial will focus on SAS + CG…so leave the frameworks debate and why I chose CG for this example for another time, or at least until another post where I actually want to argue the architectural issues that both frameworks possess. I’m also not going to focus on CG best-practices and extensions that WASI currently uses in this first post…let’s just get a SAS + CG app up and running and then come back to that in a later, cleanup/best-practices post.

So without any further delay, why Spring ActionScript (”SAS”)?

Ever create an app that relies on data from a DB that isn’t created or populated yet or try to work with services that don’t return any data? Sure you have, and so we all have our own frameworks and tricks for setting up mock objects in Business Delegates (”BD”) or simply consume XML until the real data is available. And that works great for awhile. You sit down with the server-side guys and flesh out your service API, the inputs and outputs, and hardcode your data in this temporary fashion until you hit the phase of your project called “integration.” What a lovely word. I’ve spent months of fun playing in the “integration phase” where you actually hook up your app to live data services, and you spend a good deal of time just ripping out scaffolding code, those hard-coded data calls, and…bleh…what a mess. So what if there was a way to simply interchange the BDs with their hard-coded mock objects, your stubbed service calls, or your XML through a simple config file? This my friends is the beauty of SAS and is why you’ll be hooked the moment you light up your first app with it.

The idea is to decouple configuration from implementation in patterns known as Inversion of Control (”IoC”) and Dependency Injection (”DI”) which are essentially the heart of Spring. Rather than go into too much detail about either of these patterns, please read Eric Feminellas great post on the topic. Furthermore, this is being very narrow minded and I’m leaving out a ton of other great things that Spring does, but this is the meat and potatoes of it and is what we’ll focus on in our first SAS tutorial.

A huge thanks to Christophe Herreman for porting this beauteous code-base over from Java to AS! SAS, formerly Prana, is now being considered as part of the original Java SpringSource Community’s code repository. Now that we have an idea of how SAS can help us, let’s see it in practice.

Create a Flex Builder Project

If you don’t already have the project from Part 1 of this series, please download it and import it into Flex Builder. Once in FB, copy and paste it into the same workspace as “EmployeeManagementConsole2″.

Add Libraries and Dependencies

Next we’ll need to add the necessary libraries and dependencies to the project as SWCs and AS files; mainly, we’ll need:

Spring ActionScript — Download the ZIP, extract it, and import the spring-actionscript.swc into the libs folder of your Flex Builder project.

Spring ActionScript Cairngorm Extensions — I couldn’t find the SWC for this, so I just downloaded the AS source by using Subversion (I’m currently using Subclipse, the Eclipse plug-in for SVN) and going here — https://src.springframework.org/svn/se-springactionscript-as/. Checkout the project “spring-actionscript-cairngorm” as a Flex Library Project. Once the project has completely checked out, disconnect it from SVN — if you are using Subclipse, just right-click on the project -> Team -> Disconnect (and delete all the SVN contents as well.) Finally, dig into the Flex Library Project you just created and locate the following directory: trunk/core/src/main/actionscript/org. Copy the root folder for the Cairngorm Exts sourcem org and all of it’s child directories and paste it into the src folder of your original EmployeeManagementConsole2 project.

Create Simple XML Data Source File

First we need to go ahead and create our XML data source, so let’s create a new XML file called “employee_list.xml” and save it in our project in a root folder called /assets/xml. We’ll model the XML directly after the EmployeeModel.as Model object (also like the AS mock-object we created in the AS BD), except that we’ll make the ID property an attribute in each employee node. We’ll also add “XML” as a suffix to each first name node value just so we can differentiate the data source later on when we start switching between the AS mock-object BD and our new XML BD. The finished XML should look something like this: employee_list.xml

<?xml version="1.0"?>
<employee id="0">
		<firstName>BrianXML</firstName>
		<lastName>Riley</lastName>
	</employee>

	<employee id="1">
		<firstName>TimXML</firstName>
		<lastName>McGee</lastName>
	</employee>

	<employee id="2">
		<firstName>JoeXML</firstName>
		<lastName>Seiter</lastName>
	</employee>

</employeeList>

Create New XML Business Delegate

Since we already have the application running with the AS mock-object BD and we want the app to work with XML as well, we need to go ahead and create a new XML BD, EmployeeXMLDelegate.as. The key differences between this BD and the AS BD are the following:

• Has its own HTTPService object to make requests for the XML Employee List data.
• Calls the HTTPService in the getList() method.
• Deserializes the XML result into an ArrayCollection (”AC”) of EmployeeModel objects.

These changes all exist in the constructor, getList(), and result() methods.

EmployeeXMLDelegate.as

/**
 * Constructor.
 */
public function EmployeeXMLDelegate(responder:IResponder=null)
{
	trace("EmployeeXMLDelegate Constructor");

	this.responder = responder;

	// the serives are usually created in the ServiceLocator ("SL") in
	// Cairngorm but since we're going to do away with the SL when we
	// introduce Spring AS, we'll just hardcode the service here for now.
	this.httpService = new HTTPService();
	this.httpService.url = "../assets/xml/employee_list.xml";
	this.httpService.resultFormat = "e4x";
}

/**
 * Get the list of employees.
 */
public function getList():void
{
	trace("EmployeeXMLDelegate getList");

	var responder:mx.rpc.Responder;
 	var token:AsyncToken;

 	responder = new mx.rpc.Responder(result, fault);
	token = this.httpService.send();
	token.addResponder(responder);
}

/**
 * Handles the successful service request.
 *
 * @param response Object The success event coming back from the asynchronous
 * service call containing the data payload.
 */
public function result(resultEvent:ResultEvent):void
{
	trace("EmployeeXMLDelegate result");

	var response:ArrayCollection;
	var employee:EmployeeModel;

	response = new ArrayCollection();

	for each(var employeeXML:XML in resultEvent.result.employee)
	{
		employee = new EmployeeModel();
		employee.id = employeeXML.@id;
		employee.firstName = employeeXML.firstName;
		employee.lastName = employeeXML.lastName;
		response.addItem(employee);
	}

	// pass the command the response object to do whatever it wants with it
	this.responder.result(response);
}

Now that we have our XML BD, let’s make some quick changes in the CMD to test it out. We’ll need to modify the reference to the BD in 2 places in the CMD:

1. The delegate class property
2. The instantiation of that delegate in the constructor

GetEmployeeListCommand.as

public class GetEmployeeListCommand implements ICommand, IResponder
{
	private var delegate:EmployeeXMLDelegate;

	public function GetEmployeeListCommand()
	{
		trace("GetEmployeeListCommand Constructor");
		this.delegate = new EmployeeXMLDelegate(this);
	}
       ...
}

When you test your application you should see something like:

Add Spring ActionScript

Now we have 2 possible delegates to choose from, but we have to change the AS in the CMD, recompile, and then test to see the results…this sounds tedious and leaves us with the very problem we’re trying to avoid…time for SAS.

In order to see the changes occur at run-time we’ll need to create the Spring Application Context XML configuration file that defines which BD to inject at run-time and then modify the CMD in such a way that the exact type of BD is unknown at compile time…well not exactly an unknown type, but rather the underlying implementation. To achieve this feat we’ll leverage the almighty Interface in our CMDs. We’ll come back to the Application Context config file in a bit…

Create an Employee Delegate Interface

If you look at the AS and XML BDs, you’ll notice that they both have the same method signature for getList():

public function getList():void

We’ll use this as the point of commonality to create our interface, as they both need to actually get the list of employees for our application.

IEmployeeDelegate.as

/**
 * Web App Solution Confidential Information
 * Copyright 2009, Web App Solution, Inc.
 *
 * @author Brian Riley
 * @date May, 4, 2009
 */
package com.wasi.employeeconsole.business.delegates
{
	public interface IEmployeeDelegate
	{
		function getList():void
	}
}

Next we’ll make each of our BDs implement the interface.

public class EmployeeASDelegate implements IEmployeeDelegate
public class EmployeeXMLDelegate implements IEmployeeDelegate

Spring ActionScript Application Context

The SAS Application Context (”SASAC”) is the XML configuration file that’s loaded at run-time by the Spring framework that defines all the concrete implementation objects you wish to use in your application — it essentially maps interface properties in classes (like our delegate:IEmployeeDelegate property in our GetEmployeeListCommand) to fully qualified, concrete objects. Let’s actually create our ApplicationContext and see how we can either inject our AS mock-object BD or our XML BD at run-time.

Create a new XML file called “ApplicationContext.xml” and save it in our project in a root folder called /assets/springactionscript/. Add the following code, which we’ll discuss in a moment:

ApplicationContext.xml

<?xml version="1.0"?>
<objects xmlns              = "http://www.pranaframework.org/objects"
         xmlns:xsi          = "http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation = "http://www.pranaframework.org/objects http://www.pranaframework.org/schema/objects/prana-objects-0.5.xsd">

	<!-- =================================================================== -->
	<!-- This application context defines multiple test configurations, it
		 can be expanded to include a deployment configuration as well,
		 please see comments below.

		 1. Testing: ActionScript Mock Delegates
		 2. Testing: XML Mock Delegates (Will add in next revision)
		 3. Deployment: Remote Object Delegates (Will add in next tutorial)

		 To use a configuration, uncomment it and comment the one you don't
		 want to use. By default, the Mock Delegates configuration is used.
	-->
	<!-- =================================================================== -->

	<!-- =================================================================== -->
	<!-- 1. Testing: ActionScript Mock Delegates & Services -->
	<!-- =================================================================== -->

	<object
		id="delegateLocator"
		class="com.wasi.employeeconsole.business.delegates.DelegateLocator"
		factory-method="getInstance">

		<property name="employeeDelegate">
			<object class="com.wasi.employeeconsole.business.delegates.EmployeeASDelegate" />
		</property>

	</object>

</objects>

Walking through the SASAC XML document from the top, you’ll notice the first-child node called <object>; each object tag defines a concrete object that we’ll inject into the application at run-time, as well as any properties (ie more concrete implementaitons) that we might inject into the object itself. The first object tag defines a new object that we haven’t discussed yet called the Delegate Locator (”DL”) (see Allen Manning’s Post on SAS + CGM for additional info on the DL in SAS), which is similar to the standard Service Locator (”SL”) object in CGM. However, instead of containing a registry of services like the SL, it contains a registry of BDs.

Taking a deeper look at DL object, you can see the fully qualified path to the DL object in it’s class attribute (we’ll create the AS class for the DL in the next section), and an attribute called factory-method=getInstance, indicating that it’s a Singleton. Next we’ll examine the <property> node, which is really the crux of the entire framework — here we’re setting the class property on the DL called employeeDelegate to a value of the fully qualified name of out AS mock-object delegate called EmployeeASDelegate, signifying that we’d like to inject the AS BD into the DL at run-time. Later we will setup the SASAC to inject the XML BD, but for now let’s test out this version by loading the file at run-time and making sure that it does in fact inject our AS BD.

Create the DelegateLocator

Since our DL is really just a registry of the BDs we want to use at run-time, we need to create a getter and setter method for each BD we want to inject into it with the same property name as the one we used in the SASAC — employeeDelegate. Create a new AS class called DelegateLocator and make it a singleton. Next, create a private var representing the employeDelegate with corresponding getters and setters and make sure they use our Employee Delegate interface, IEmployeeDelegate as the type:

/**
 * Reference to the employee delegate. Provides an interface
 * to get the injected delegate at run-time.
 */
private var _employeeDelegate:IEmployeeDelegate;
public function get employeeDelegate():IEmployeeDelegate
{
	return this._employeeDelegate;
}
public function set employeeDelegate(delegate:IEmployeeDelegate):void
{
	this._employeeDelegate = delegate;
}

Modify the GetEmployeeCommand to Use the DelegateLocator

If you recall, we recently modified the GetEmployeeCommand to reference the EmployeeXMLDelegate…we’ll need to go back into the CMD and modify it again to use the DL and Interface to acquire the injected BD:

private var delegate:IEmployeeDelegate;

public function GetEmployeeListCommand()
{
	trace("GetEmployeeListCommand Constructor");
	this.delegate = DelegateLocator.getInstance().employeeDelegate;
	this.delegate.responder = this;
}

Now we’re acquiring the BD from the DL with the injected, concrete implementation set up in the ApplicationContext file, but we need to make a couple small change to our BDs and Interfaces…we need a reference to the CMD as the responder. In our previous implmentation of the CMD, we passed in a reference of itself into the constructor of the BD, but now we’re going to set it as a property on the BD. Instead of making this change in ever BD, let’s make an abstract BD that each of our concrete BDs will subclass:

AbstractDelegate

package com.wasi.employeeconsole.business.delegates
{
	import mx.rpc.IResponder;

	public class AbstractDelegate
	{
		/**
		 * Constructor.
		 */
		public function AbstractDelegate()
		{
			trace("AbstractDelegate Constructor");
		}

		/**
		 * RPC Responder, used as a reference back to the command that made the request.
		 */
		private var _responder:IResponder;
		public function get responder():IResponder
		{
			return this._responder;
		}
		public function set responder(value:IResponder):void
		{
			this._responder = value;
		}

	}
}

Now go into each BD and subclass our new AbstractDelegate:

public class EmployeeASDelegate extends AbstractDelegate implements IEmployeeDelegate
public class EmployeeXMLDelegate extends AbstractDelegate implements IEmployeeDelegate

And finally go into our IEmployeeDelegate and extend a SAS CGM extention called IResponderAware that will allow/force each of our BDs to have a set repsonder(value:IResponder) method (open up the source of IResponderAware to see what it’s doing):

public interface IEmployeeDelegate extends IResponderAware

I know, I know…this is getting long, so on with it already…

Load the Spring ApplicationContext Config

Finally, open your Application file so we can load the SASAC and instantiate the DL:

1. Create a class property representing the application context.
2. Listen for the Creation Complete event of the Application and handle it with an init() method.
3. Create loadSpringAppContext() method and call it in the init().
4. In the loadSpringAppContext() method, create a new FlexXMLApplicationContext (the application context class property we defined in step 1) and pass in the URL to the SASAC file.
5. Create listeners for the success and failed requests for the SASAC.
6. Load the File.
7. Upon successful retrieval of the SASAC, instantiate the DL.
8. Test…you’ll get an error, but this is exected and requires some explanation.

/**
 * Defines the application specific context by which objects and
 * their dependencies are loaded.
 */
private var applicationContext:FlexXMLApplicationContext;

/**
 * Called when the Application component has been created.
 */
private function init():void
{
	trace("Application init");
	this.loadSpringAppContext();
}

/**
 * Initializes the applicationContext instance and adds
 * listeners for the context file loading events.
 */
private function loadSpringAppContext():void
{
	trace("Application loadSpringAppContext");

	var applicationContextURL:String;

	applicationContextURL = "../assets/springactionscript/applicationContext.xml";

	// Initializes the applicationContext instance and adds listeners for the context file loading events.
	this.applicationContext = new FlexXMLApplicationContext(applicationContextURL);
	this.applicationContext.addEventListener(Event.COMPLETE, applicationContextLoadResult);
	this.applicationContext.addEventListener(IOErrorEvent.IO_ERROR, applicationContextLoadFault);
	this.applicationContext.load();
}

/**
 * IApplicationContextLoader.applicationContextLoadResult
 * implementation which handles successful loading of the context
 * document.
 */
public function applicationContextLoadResult(event:Event):void
{
	trace("Application applicationContextLoadResult");
	this.applicationContext.getObject("delegateLocator");
}

/**
 * IApplicationContextLoader.applicationContextLoadFault
 * implementation which handles an exception when loading the context
 * document.
 */
public function applicationContextLoadFault(iOErrorEvent:IOErrorEvent):void
{
	trace("Application applicationContextLoadFault " + iOErrorEvent.text);

	// we'll go with a simple stoopid apprach for this right now and just throw an alert
	Alert.show("Spring Application Context Failed to Load", "Error");
}

An error!?! WTF mate?

Why Did We Get An Error?

[SWF] Users:brianmriley:projects:spring-hibernate:workspaces:flex3:EmployeeManagementConsole2:bin-debug:EmployeeManagementConsole2.swf - 1,235,684 bytes after decompression
CairngormFrontController Constructor
CairngormFrontController addCommands
Application init
Application loadSpringAppContext
5/8/2009 14:40:02.804 [INFO] SpringActionScript.FlexXMLApplicationContext Loading XML object definitions from [../assets/springactionscript/applicationContext.xml]
Error: A class with the name
        'com.wasi.employeeconsole.business.delegates.EmployeeASDelegate'
        could not be found.
	at as3reflect::ClassUtils$/forName()[C:\Users\Christophe\workspace\as3reflect\src\as3reflect\ClassUtils.as:89]
	at org.springextensions.actionscript.ioc.factory.support::DefaultListableObjectFactory/getObjectNamesForType()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\ioc\factory\support\DefaultListableObjectFactory.as:87]
	at org.springextensions.actionscript.context.support::XMLApplicationContext/registerObjectPostProcessors()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\context\support\XMLApplicationContext.as:196]
	at org.springextensions.actionscript.context.support::XMLApplicationContext/afterParse()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\context\support\XMLApplicationContext.as:158]
	at org.springextensions.actionscript.ioc.factory.xml::XMLObjectFactory/_doParse()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\ioc\factory\xml\XMLObjectFactory.as:341]
	at org.springextensions.actionscript.ioc.factory.xml::XMLObjectFactory/_loadNextProperties()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\ioc\factory\xml\XMLObjectFactory.as:315]
	at org.springextensions.actionscript.ioc.factory.xml::XMLObjectFactory/_loadNextConfigLocation()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\ioc\factory\xml\XMLObjectFactory.as:291]
	at org.springextensions.actionscript.ioc.factory.xml::XMLObjectFactory/_onLoaderComplete()[C:\Users\Christophe\Documents\Adobe Gumbo MAX Preview\spring-actionscript\core\src\main\actionscript\org\springextensions\actionscript\ioc\factory\xml\XMLObjectFactory.as:241]
	at flash.events::EventDispatcher/dispatchEventFunction()
	at flash.events::EventDispatcher/dispatchEvent()
	at flash.net::URLLoader/onComplete()

Since we’re injecting our concrete types of BDs into the application at run-time, we never explicitly told the Flex compiler to add our EmployeeASDelegate class into the SWF; thus, when we try to instantiate it the Flash Player throws an error saying the class doesn’t exist…one way to get around this is to just create a reference to it somewhere in your application, but we’re going to take a slightly different approach and add it to a property file for better organization.

ClassReferences.properties

Create a new properties file and put it directly into the src folder of your project (again, we’ll come back to cleaning this up in later posts) and create a reference to both the EmployeeASDelegate and the EmployeeXMLDelegate, since we’ll be switching back and forth between the 2 shortly.

EmployeeASDelegate  = ClassReference("com.wasi.employeeconsole.business.delegates.EmployeeASDelegate")
EmployeeXMLDelegate = ClassReference("com.wasi.employeeconsole.business.delegates.EmployeeXMLDelegate")

Now create a reference to your ClassProperties.properties file in your main Application:

[ResourceBundle("ClassReferences")]
private var springClassRefs:ResourceBundle;

Success & Last Touches

Run your application and click the “Refresh List” button and you should see the following:

Open up the SASAC file and change the reference of the Employee Delegate from the AS impl to the XML impl:

<?xml version="1.0"?>
<objects xmlns              = "http://www.pranaframework.org/objects"
         xmlns:xsi          = "http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation = "http://www.pranaframework.org/objects http://www.pranaframework.org/schema/objects/prana-objects-0.5.xsd">

	<object
		id="delegateLocator"
		class="com.wasi.employeeconsole.business.delegates.DelegateLocator"
		factory-method="getInstance">

		<property name="employeeDelegate">
			<object class="com.wasi.employeeconsole.business.delegates.EmployeeXMLDelegate" />
		</property>

	</object>

</objects>

Save it, run it, and you should see the following:

Voila! You’ve just successfully set up your first Flex + SAS + CGM application and learned how to inject 2 different types of BDs at runtime. Say tuned for episode 3 to learn how to inject the XML HTTPService in the EmployeeXMLDelegate also via SAS.

References:

• Dependency Injection in Flex Applications - Part 1 - Spring ActionScript and Cairngorm - Allen Manning
• IoC and the Dependency Injection Pattern in Flex - Eric Feminella
• Christophe Herreman’s Blog - Christophe Herreman

Tweet This Post