One of the main criticisms on Cairngorm you'll read on the internet is its heavy use of the singleton pattern. To obtain a reference to your model instance you need to call the static ApplicationModel.getInstance() method every time you need one. This tightly couples your code to a specific implementation of your model, which in a world of 'High Cohesion and Loose Coupling' is somewhat of a sin.

To circumvent this problem it's a good plan to first create an interface for your model and have your concrete model implement this interface. This way it'll be easy to inject your model across various object instances in your application. The injection bit we will come to later on. First let's create a very simple model interface:

public interface IApplicationModel extends IEventDispatcher {
        
    function get productItems():ArrayCollection;

    [Bindable(event="productItemsChanged")]
    function set productItems(value:ArrayCollection):void;

}

And have your actual ModelLocator implement this, like so:

public class ApplicationModel extends EventDispatcher implements IModelLocator, IApplicationModel {
            
    private static var _modelInstance : IApplicationModel;

    public static function getInstance():IApplicationModel {
        if (!_modelInstance) {
            _modelInstance = new ApplicationModel();
        }

        return _modelInstance;
    }

    public function ApplicationModel():void {
        super();
        if (_modelInstance) {
            throw new Error('Only one ApplicationModel instance should be instantiated');
        }
    }

    private var _productItems:ArrayCollection;
    
    public function get productItems():ArrayCollection {
        return _productItems;
    }

    [Bindable(event="productItemsChanged")]
    public function set productItems(value:ArrayCollection):void {
        if (value !== _productItems) {
            _productItems = value;
            dispatchEvent(new Event("productItemsChanged"));
        }
    }
}

That was easy enough right? Now let's add a bit of XML to our application configuration that will make sure a model instance is created:

<object id="appModelInstance" class="com.myclasses.cairngorm.ApplicationModel" factory-method="getInstance" scope="singleton"/>

When transferring responsibility for creating our model to the IoC container, it is not even necessary anymore to use the getInstance() factory method. Spring Actionscript will make sure only one instance of the model is created. (Notice the singleton="true" attribute). So in all fairness, we can just change our model class into this:

public class ApplicationModel extends EventDispatcher implements IModelLocator, IApplicationModel {

    public function ApplicationModel():void {
        super();
    }

    private var _productItems:ArrayCollection;
    
    public function get productItems():ArrayCollection {
        return _productItems;
    }
    
    [Bindable(event="productItemsChanged")]
    public function set productItems(value:ArrayCollection):void {
        if (value !== _productItems) {
            _productItems = value;
            dispatchEvent(new Event("productItemsChanged"));
        }
    }
}

And change our configuration by getting rid of the factory method call:

<object id="applicationModel" class="com.myclasses.cairngorm.ApplicationModel" scope="singleton"/>

That's it! Next up we are going to configure our FrontController and ServiceLocator.

When using Cairngorm without Spring Actionscript you are used to adding MXML instances of the FrontController and ServiceLocator to your application like this:

<mx:Application
    xmlns:control="com.cairngormclasses.control.*"
    xmlns:business="com.cairngormclasses.business.*"
    xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="absolute">
    <control:Controller id="frontController"/>
    <business:Services id="serviceLocator"/>
</mx:Application>

After that you hook up your events and commands in your FrontController in more or less this fashion:

public class Controller extends FrontController {
        
    public static const SOME_ACTION:String = "SomeActionEventID";
    
 //-----------------------------------------------------------
 
    public function Controller() {
        super();
        initializeCommands();
    }

 //-----------------------------------------------------------

    public function initializeCommands():void {
        addCommand( Controller.SOME_ACTION, SomeActionCommand );
    }
}

And your service locator implementation will probably look something like this (depending on which server technology is being used):

<cairngorm:ServiceLocator
 xmlns:cairngorm="com.adobe.cairngorm.business.*"
 xmlns:mx="http://www.adobe.com/2006/mxml">

 <mx:RemoteObject id="SomethingRemote"
  endpoint="/flex2gateway/"
  destination="ColdFusion"
  source="com.myremoteobjects.someservice"
  concurrency="multiple"
  makeObjectsBindable="true"
  showBusyCursor="true"/>

</cairngorm:ServiceLocator>

Now this is all fine and dandy, but of course we would really like to keep configuration outside of our compiled code. Otherwise every time we'd like to change an event/command combination we'd have to re-compile the application. So, this is where the CairngormFrontController The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. comes in. This class allows you to pass an object as a parameter to its constructor which holds a mapping of event id's and commands.

To configure the instantiation of the CairngormFrontController The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. in Spring Actionscript add this snippet of XML to your configuration:

<object id="frontController" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton">
<constructor-arg>
  <object>
    <!-- Add a new property for each event/command mapping: -->
    <property name="SomeActionEventID" value="SomeActionCommand"/>
  </object>
</constructor-arg>
<!-- The following argument is optional -->
<constructor-arg value="com.mycommands.command"/>
</object>

The first argument is the object that contains the mapping between the event names and the command classes. The second argument is optional and defines the package where the command classes reside. By specifying this argument, you don't need to define the fully qualified class names of the commands.

We can now leave out the FrontController class, but beware: we need to make sure that the command classes get compiled in the swf of our application. We can do this by referencing them in our application. We'll also reference the CairngormFrontController The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. class:

private var _cairngormFrontController:CairngormFrontController;
private var _commands:Array = [SomeActionCommand];

The MXML declarations of the FrontController and ServiceLocator have become obsolete by now, so let's get rid of them:

<mx:Application
 xmlns:control="com.cairngormclasses.control.*"
 xmlns:business="com.cairngormclasses.business.*"
 xmlns:mx="http://www.adobe.com/2006/mxml"
 layout="absolute">
  <!-- control:Controller id="frontController"/ -->
  <!-- business:Services id="serviceLocator"/ -->
</mx:Application>

<object id="frontController" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton">
<constructor-arg>
  <object>
    <!-- Add a new property for each event/command mapping: -->
    <property name="SomeActionEventID" value="SomeActionCommand"/>
    <property name="SomeActionEventID" value="AnotherActionCommand"/>
  </object>
</constructor-arg>
</object>

One big drawback and limiting factor of the regular FrontController is that it doesn't play nice in a multiple module scenario. Meaning, in the case where two FrontController instances are created for two different modules, yet both instances have associated a command with the same event id, this will actually trigger both commands when this specified event is dispatched. The reason for this is the dependency that the FrontController has on the CairngormEventDispatcher, which is a singleton. So both controllers will listen for the same event from one instance of the CairngormEventDispatcher.

An example of this behavior could be an event that retrieves module settings. (Not too uncommon). Imagine that this event has an id called "GetSettingEventId". Now the first module loads, its FrontController gets instantiated and then some time after this the GetSettings event is dispatched. So far so good, the FrontController detects the event being dispatched and executes its associated GetSettings command which in turn calls a delegate, etc. However, when a second module gets loaded which also needs to retrieve its settings both controllers will detect the GetSettings event and both of them will execute their command. Which will lead to all kinds of interesting results you might imagine.

Naturally it would be desirable to somehow associate a FrontController with a specific module and when events are dispatched within this module only the associated controller will be triggered.

Spring Actionscript's CairngormFrontController The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. offers support for multiple module scenario's. This functionality doesn't rely on a singleton event dispatcher but uses event bubbling instead. This does demand a certain way of setting things up though and this section will show you exactly how.

public function creationComplete_handler(event:FlexEvent):void {
 var frontController:CairngormFrontController = _applicationContext.getObject("moduleController") as CairngormFrontController;
 frontController.register(this);
}

public function click_handler(event:MouseEvent):void {
 CairngormEventDispatcher.getInstance().dispatchEvent(new MyCairngormEvent());
}

public function click_handler(event:MouseEvent):void {
 new MyCairngormEvent().dispatch();
}

public function click_handler(event:MouseEvent):void {
 this.dispatchEvent(new MyCairngormEvent());
}

var newEvent:MyCairngormEvent = new MyCairngormEvent("MyCairngormEventID",true);

public class ExampleMediator extends EventDispatcher implements IExampleMediator {

 public function ExampleMediator(target:IEventDispatcher=null) {
  super(target);
 }

 public function remoteOperation():void {
  dispatchEvent(new MyCairngormEvent());
 } 

}

public function creationComplete_handler(event:FlexEvent):void {
 var frontController:CairngormFrontController = _applicationContext.getObject("moduleController") as CairngormFrontController;
 frontController.register(this);

 var exampleMediator:ExampleMediator = _applicationContext.getObject("exampleMediator",this) as ExampleMediator;}
}

public class CairngormFrontControllerWireAgent implements IObjectFactoryAware {

 private var _moduleMap:Dictionary;
 private var _objectFactory:IObjectFactory;

 public function ModuleFrontControllerWireAgent(moduleMap:Dictionary){
  Assert.notNull(moduleMap,"moduleMap argument must not be null");
  _moduleMap = moduleMap;
 }

 public function evaluate(component:Object):void {
  Assert.notNull(_objectFactory,"_objectFactory must not be null");
  var module:Module = (component as Module);
  if (module != null) {
   var name:String = module.name;
   var frontControllerName:String = _moduleMap[name];
   if (frontControllerName != null) {
    var frontController:CairngormFrontController = _objectFactory.getObject(frontControllerName) as CairngormFrontController;
    if (frontController != null){
     frontController.register(module);
    }
   }
  }
 }

 public function set objectFactory(value:IObjectFactory):void {
  _objectFactory = value;
 }

}

<object id="frontcontrollerWireAgent" class="com.classes.CairngormFrontControllerWireAgent" scope="singleton">
 <constructor-arg>
  <dictionary>
   <entry key="mymodulename" value="frontcontrollerA"/>
  </dictionary>
 </constructor-arg>
</object>

<object id="frontcontrollerA" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton" lazy-init="true">
 <!-- configuration omitted for brevity -->
</object>

<objects
  xmlns="http://www.springactionscript.org/schema/objects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:si="http://www.springactionscript.org/schema/stageinterception"
  xsi:schemaLocation="http://www.springactionscript.org/schema/objects
  http://www.springactionscript.org/schema/objects/spring-actionscript-objects-1.0.xsd
  http://www.springactionscript.org/schema/objects/spring-actionscript-stageinterception-1.0.xsd">

 <object id="frontcontrollerWireAgent" class="com.classes.CairngormFrontControllerWireAgent" scope="singleton">
  <constructor-arg>
   <dictionary>
    <entry key="mymodulename" value="frontcontrollerA"/>
   </dictionary>
  </constructor-arg>
 </object>

 <object id="frontcontrollerA" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton" lazy-init="true">
  <!-- configuration omitted for brevity -->
 </object>
 
 <si:stageinterceptor target-object="frontcontrollerWireAgent" target-method="evaluate"
        object-selector="moduleSelector" id="stageInterceptor"/>
     
 <object id="moduleSelector" class="org.springextensions.actionscript.ioc.wire.TypeBasedObjectSelector">
  <constructor-arg>
   <array>
    <value type="class">mx.modules.Module</value>
   </array>
  </constructor-arg>
 </object>

</objects>

Now what about that ServiceLocator? Having all that remoting configuration right inside your source code is also not very convenient. What if the paths are different between staging and production servers? What if you'd like to change the remote path later on while already being in production? Right now all of those changes would require a re-compile of the application. A re-compile that is unnecessary when you use Spring Actionscript to configure your ServiceLocator.

To be able to configure the services at runtime Spring Actionscript offers a subclass of the normal ServiceLocator that allows just this. The class we're talking about is the CairngormServiceLocator Allows programmatic manipulation of the services inside Cairngorm's ServiceLocator.. To have the container create an instance of this class, add this bit of markup to your application configuration.

<object id="serviceLocator" class="org.springextensions.actionscript.cairngorm.business.CairngormServiceLocator" factory-method="getInstance">
  <!-- The CairngormServiceLocator is marked with the dynamic keyword, so new properties can be added at runtime: -->
  <property name="testService">
    <ref>testService</ref>
  </property>
</object>

As you'll notice by the <ref/> element used in the testService property, this ServiceLocator already has one service configured.

The testService (RemoteObject) instance is defined like this:

<object id="testService" class="mx.rpc.remoting.mxml.RemoteObject" scope="singleton">
  <property name="id" value="testService"/>
  <property name="endpoint" value="/flex2gateway/"/>
  <property name="destination="ColdFusion"/>
  <property name="source" value="com.myremoteobjects.someservice"/>
  <property name="showBusyCursor" value="true"/>
  <property name="makeObjectsBindable" value="true"/>
</object>

Of course, afterwards make sure the appropriate classes are referenced in your source code, otherwise you will experience run-time errors because the classes will not have been compiled into your swf:

private var _cairngormFrontController:CairngormFrontController;
private var _cairngormServiceLocator:CairngormServiceLocator;
private var _remoteObject:mx.rpc.remoting.mxml.RemoteObject;
private var _commands:Array = [SomeActionCommand];

<object id="amfChannel" class="mx.messaging.channels.AMFChannel" scope="singleton">
  <constructor-arg value="my-amf"/>
  <constructor-arg value="http://{server.name}:{server.port}/flex2gateway/"/>
  <property name="id" value="amfChannel"/>
  <property name="pollingEnabled" value="false"/>
</object>

<object id="channelset" class="mx.messaging.ChannelSet" scope="singleton">
  <method-invocation name="addChannel">
    <arg>
      <ref>amfChannel</ref>
    </arg>
  </method-invocation>
</object>

<object id="testService" class="mx.rpc.remoting.mxml.RemoteObject">
  <property name="id" value="testService"/>
  <property name="destination="ColdFusion"/>
  <property name="source" value="com.myremoteobjects.someservice"/>
  <property name="showBusyCursor" value="true"/>
  <property name="makeObjectsBindable" value="true"/>
  <property name="channelSet">
    <ref>channelset</ref>
  </property>
</object>

<template id="remoteObject">
  <object class="mx.rpc.remoting.mxml.RemoteObject" scope="singleton">
    <property name="destination" value="ColdFusion"/>
    <property name="source" value="com.myremoteobjects.${serviceClass}"/>
    <property name="channelSet">
      <ref>channelset</ref>
    </property>
  </object>
</template>

<object id="testService" template="remoteObject">
  <param name="serviceClass" value="someservice"/>
</object>

The FrontController usually takes care of instantiating the command classes that are mapped to your events. This starts to become inconvenient when a Command instance needs a reference to, for example, the model instance. (A situation which will occur quite regularly.) Normally you would just add a direct reference into your command class through a call to the applicationModel.getInstance() method. This is what we call 'tight coupling' and is undesirable since it leaves the command directly dependent on a specific implementation of the model class. For example, this will make unit testing the class a lot harder since your unit test will be dependent on that same model instance.

So what we'd like to be able to do is inject this model instance into the command after it has been created. Spring Actionscript offers the ICommandFactory Implemented by factory objects that are capable of creating <code>ICommand</code> instances. interface to solve this problem.

The interface is very simple and requires only to implement two methods:

public function canCreate(clazz:Class):Boolean;
public function createCommand(clazz:Class):ICommand;

The result of the canCreate() Returns true if the current <code>ICommandFactory</code> is able to create the specified <code>Class</code> method determines whether the specific command factory is able to create the requested command class. In this method you could check if a command implements a certain interface or look it up in a list of command classes that was injected at runtime.

If the canCreate() Returns true if the current <code>ICommandFactory</code> is able to create the specified <code>Class</code> method returns true it will be save to call the createCommand() Looks up the appropriate <code>ICommandFactory</code> instance to create the specified <code>Class</code>. method which returns the actual instance of the requested class.

The CairngormFrontcontroller The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. actually creates an implementation of this interface internally. This ICommandFactory Implemented by factory objects that are capable of creating <code>ICommand</code> instances. implementation checks whether the specified class implements the ICommand interface and creates the command or not accordingly.

Now, to solve your little model injection problem, let's say you define a small interface called IApplicationModelAware. The definition of which could simply be like this:

public interface IApplicationModelAware {
        
    function set applicationModel(value:IApplicationModel):void;
  
}

Where the IApplicationModel is the interface you have created to describe your model.

Now you can go ahead and create a base class for all your commands that require a reference to the model:

public class CommandBase extends AbstractResponderCommand implements IApplicationModelAware {
            
    public function CommandBase() {
        super();
    }

    private var _applicationModel:IApplicationModel;
    
    function get applicationModel():IApplicationModel {
        return _applicationModel;
    }
 
    function set applicationModel(value:IApplicationModel):void {
        _applicationModel = value;
    }

    override public function execute(event:CairngormEvent):void {
        super.execute(event);
    }

    override public function result(data:Object):void {
        throw new Error("Not implemented in base class");
    }

    override public function fault(info:Object):void {
        throw new Error("Not implemented in base class");
    }
    
}

To be able to create subclasses of this command and inject them with a model reference we can now construct an implementation of the ICommandFactory Implemented by factory objects that are capable of creating <code>ICommand</code> instances. interface:

public class ApplicationModelAwareCommandFactory implements ICommandFactory, IApplicationModelAware {

    public function CommandFactory() {
        super();
    }

    private var _applicationModel:IApplicationModel;
    
    function set applicationModel(value:IApplicationModel):void {
        _applicationModel = value;
    }

    public function canCreate(clazz:Class):Boolean {
        return (ClassUtils.isSubclassOf(clazz, CommandBase));
    }

    public function createCommand(clazz:Class):ICommand {
        var result:CommandBase = new clazz();
        result.applicationModel = _applicationModel;
        return result;
    }
}

As you see the ApplicationModelAwareCommandFactory implements the same IApplicationModelAware interface as well. Now, to be able to inject the model into our new factory and after that inject it into our controller we need to add some XML to our application configuration. First let's create the command factory:

<object id="appAwareCmdFactory" class="com.myclasses.cairngorm.factories.ApplicationModelAwareCommandFactory" scope="singleton">
 <property name="applicationModel" ref="appModelInstance"/>
</object>

Remember how we already added markup to instantiate our model? We now use the context id of that object to inject it into our command factory.

Now we can change the XML markup that configures our controller:

<object id="frontController" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton">
 <constructor-arg>
  <object>
   <property name="SomeActionEventID" value="SomeActionCommand"/>
  </object>
 </constructor-arg>
 <!-- The followoing argument is optional -->
 <constructor-arg value="com.mycommands.command"/>
 <!-- Add a custom command factory instance -->
 <method-invocation name="addCommandFactory">
  <arg><ref>appAwareCmdFactory</ref></arg>
 </method-invocation>
</object>

And there we are! From now on every command that is added to our FrontController (and subclasses the CommandBase class) will be automatically injected with the ApplicationModel instance after creation.

<object id="someActionCommandID" class="com.class.commands.MyCommand">
<!-- omitted configuration -->
</object>

<object id="frontController" class="org.springextensions.actionscript.cairngorm.control.CairngormFrontController" scope="singleton">
 <constructor-arg>
  <object>
   <property name="SomeActionEventID" value="someActionCommandID"/>
  </object>
 </constructor-arg>
</object>

Cairngorm commands need delegates, these delegates are responsible for retrieving and sending the data in the application. One way to do this is to create an instance of a specific delegate inside the command class. Let's create an example command class that handles the retrieval of products:

public class GetProductItemsCommand extends CommandBase {
    private var _delegate:GetProductItemsDelegate;
    
    public function GetProductItemsCommand() {
        super();
        //create the specific delegate class and pass ourselves as its responder
        _delegate = new GetProductItemsDelegate(this as IResponder);
    }

    override public function execute(event:CairngormEvent):void {
       super.execute(event);
       //execute the delegate logic
       _delegate.getProductItems();
    }

    override public function result(data:Object):void {
        // Business logic to handle the data retrieval
    }

    override public function fault(info:Object):void {
        // Logic to handle errors
    }
    
}

Again this tightly couples the command to a specific delegate. For example, what if we want to replace this delegate with a mock version that simply returns test data? What is needed, again, is an interface, one that describes the functionality of our delegate. Spring Actionscript already offers an interface that we can use as a base for this. Its called IBusinessDelegate Defines a business delegate..

The GetProductItemsDelegate declaration could look a little like this:

public interface IGetProductItemsDelegate extends IBusinessDelegate {
 
    function getProductItems():void;
    
}

An implementation of the interface can conveniently inherit from the already available AbstractBusinessDelegate class: AbstractBusinessDelegate acts as a base class for business delegates.

public class GetProductItemsDelegate extends AbstractBusinessDelegate {
    
    public function GetProductItemsDelegate(service:* = null, responder:IResponder = null) {
        super(service, responder);
    }
 
    public function getProductItems():void {
        var token:AsyncToken = service.getProductItems();
        token.addResponder(this.responder);
    }
}

Now its time to change the base command class. You can see we were already inheriting from the AbstractResponderCommand Base class for command classes that can act as a responder for their assigned business delegate. class provided by Spring Actionscript. This class already exposes a property called businessDelegate which expects an instance of IBusinessDelegate Defines a business delegate.. Since we made our IGetProductItemsDelegate inherit from this interface we can use this property in our command class. We can delete the creation of the delegate altogether and simply cast the value of the businessDelegate property to our own delegate interface.

We'll make sure an appropriate instance will be injected later on, first let's change our command into this:

public class GetProductItemsCommand extends CommandBase {
    public function GetProductItemsCommand() {
        super();
    }

    override public function execute(event:CairngormEvent):void {
        super.execute(event);
        //execute the delegate logic
        IGetProductItemsDelegate(this.businessDelegate).getProductItems();
    }

    override public function result(data:Object):void {
        // Business logic to handle the data retrieval
    }

    override public function fault(info:Object):void {
        // Logic to handle errors
    }
}

Nothing fancy there either, actually we just made our class smaller which always good, right?

Now we want to be able to create an instance of the GetProductItemsDelegate and inject it into our GetProductItemsCommand once its created by the command factory. Luckily Spring Actionscript already offers a class that performs exactly this task for you. The ResponderCommandFactory <code>ICommandFactory</code> implementation that is capable of creating commands that implements the <code>ICommand</code> interface. class to be precise. This class (an implementation of IResponderCommandFactory Implemented by objects that can create <code>ICommand</code> instances and configure them with the <code>IBusinessDelegateFactory</code> instances added with the <code>addBusinessDelegateFactory</code> method.) has a method called addBusinessDelegateFactory() Adds a <code>IBusinessDelegateFactory</code> that will be used to inject business delegates in the created <code>ICommand</code> instances. which expects an instance of IBusinessDelegateFactory Defines a business delegate factory. and an array of command classes.

Before we forget, first let's change the implementation of our command class so that it inherits from ResponderCommandFactory <code>ICommandFactory</code> implementation that is capable of creating commands that implements the <code>ICommand</code> interface.:

public class ApplicationModelAwareCommandFactory extends ResponderCommandFactory implements IApplicationModelAware {

    public function CommandFactory() {
        super();
    }

    private var _applicationModel:IApplicationModel;

    function set applicationModel(value:IApplicationModel):void {
        _modelInstance = value;
    }

    override public function canCreate(clazz:Class):Boolean {
        //First check if we can create the specified class, then ask our super class if he agrees with us:
        if (ClassUtils.isSubclassOf(clazz, CommandBase)) {
            return super.canCreate(clazz);
        }
        return false;
    }

    override public function createCommand(clazz:Class):ICommand {
        //First have our super class create and inject an instance, after that we perform our own injection and finaly return the result:
        var result:CommandBase = super.createCommand(clazz) as CommandBase;
        result.applicationModel = _applicationModel;
        return result;
    }
}

Well, then it is finally time to tie everything together and the place to do this of course is the Spring Actionscript configuration.

First of all, let's define our BusinessDelegate factory:

<object id="businessDelegateFactory"
   class="org.springextensions.actionscript.cairngorm.business.BusinessDelegateFactory" scope="singleton">
  <property name="service" ref="testService"/>
  <property name="delegateClass" type="class" value="com.myclasses.delegates.GetProductItemsDelegate"></property>
</object>

After that we can create the new command factory and add our business delegate factory to it, along with the name of our command classes. (well, in our case just one command class). To do this we change our existing definition we created earlier:

<object id="appAwareCmdFactory" class="com.myclasses.cairngorm.factories.ApplicationModelAwareCommandFactory" scope="singleton">
  <property name="applicationModel" ref="appModelInstance"/>
  <method-invocation name="addBusinessDelegateFactory">
    <arg>
      <ref>businessDelegateFactory</ref>
    </arg>
    <arg>
      <array>
        <value type="Class">com.myclasses.commands.GetProductItemsCommand</value>
      </array>
    <arg>
  </method-invocation>
</object>

By passing a reference to our businessDelegateFactory to the addBusinessDelegateFactory() Adds a <code>IBusinessDelegateFactory</code> that will be used to inject business delegates in the created <code>ICommand</code> instances. method along with the classname of our command, we tell the command factory that each time he creates an instance of our command he can use the business delegate factory to create a delegate for it. If more command classes use the same delegate, just add their class to the array of class names. If a different delegate is needed than add another definition to your application configuration. And if more complex injection needs to be performed, go right ahead and subclass the existing Spring Actionscript extensions for your convenience.

And there we are, our complete Cairngorm configuration is now loosely coupled and fully managed by the Spring Actionscript container!

Now go ahead and start coding!

When dealing with web services you will typically receive a response that consists of an XML string (but other formats such as JSON, CSV or anything else are possible too of course). This XML is not particularly useful within an application so naturally this XML will need to be converted into business or value objects. You can choose to perform this conversion either in your delegate or your command class after a response has been received. However, these classes aren't really meant to perform this task, and that's why Spring Actionscript offers the IDataTranslator Defines a generic data translator object interface.

The interface, as usual, is a very simple one:

public interface IDataTranslator {
  function translate(data:*):*;
}

This enables an IDataTranslator Defines a generic data translator object implementation to take a generic input and return a generic output.

Now what we'd like to be able to do is inject an IDataTranslator Defines a generic data translator object into a delegate instance when appropriate, since not all delegates will need one naturally. So, what we need is a delegate instance that implements the IDataTranslatorAware Implemented by objects that need a reference to an <code>IDataTranslator</code> instance. interface.

This particular interface will not make you scream in terror of its complexity either:

public interface IDataTranslatorAware {
  function set dataTranslator(value:IDataTranslator):void;
}

Spring Actionscript offers a base class for such a delegate called AbstractDataTranslatorAwareBusinessDelegate Abstract implementation of a business delegate that can be assigned an <code>IDataTranslator</code> instance to do some initial data conversion before the delegate's result is sent back to it's initial responder.. If you want to create a delegate that makes use of an IDataTranslator Defines a generic data translator object implementation then simply derive from this class. Here's a simple example of an AbstractDataTranslatorAwareBusinessDelegate Abstract implementation of a business delegate that can be assigned an <code>IDataTranslator</code> instance to do some initial data conversion before the delegate's result is sent back to it's initial responder. subclass:

public class GetProductsDelegate extends AbstractDataTranslatorAwareBusinessDelegate {

  public function GetProductsDelegate(service:*=null, responder:IResponder=null, dataTranslator:IDataTranslator=null) {
   super(service, responder, dataTranslator);
  }

  public function getProducts():void {
   var token:AsyncToken = service.getProducts();
   addResponderToToken(token);
  }
}

Notice the one line in bold, this is where we call a method in the base class that takes care of intercepting the service call, sending the input to the assigned IDataTranslator Defines a generic data translator object and afterwards sending its result back to the delegate's responder.

Now, a simplified implementation of an IDataTranslator Defines a generic data translator object that takes an XML response and turns it into an array of objects is shown below:

public class XMLToProductsDataTranslator implements IDataTranslator {

  public function XMLToProductsDataTranslator() {
  }

  public function translate(data:*):* {
   var productsArray:Array = [];
   var productsXML:XML = new XML(data);

   //Conversion logic omitted for clarity...

   return productsArray;
  }
}

To configure the delegate to use this particular IDataTranslator Defines a generic data translator object you can add this bit of markup to your configuration file:

<object id="productTranslator" class="com.mytranslators.XMLToProductsDataTranslator"/>

<object id="productsDelegate" class="com.mydelegates.GetProductsDelegate">
  <property name="dataTranslator" ref="productTranslator"/>
</object>

Or you can create your own version of the delegate factory that handles this kind of injection.

Problem

We want to be able to execute commands in a sequence, where each command needs to be executed after the previous command has finished. This can be right after a call to execute() in case the command only implements ICommand, or after the invocation of the result() or fault() method, in case the command implements the IResponder interface and fetches some remote data.

The way to do this in Cairngorm is to let your command extend SequenceCommand - which acts as an abstract base class for commands that are executed in a sequence. Then you assign a value to the nextEvent property and call the executeNextCommand() method. This is done in the execute() method, the result() or fault() handler of the command. Each sequence command contains logic that says which command to execute next.

This has a major drawback though: since the sequence logic is coded in the commands themselves, it is very hard - not to say impossible without extra conditional logic - to reuse the command outside a sequence or in another sequence.

Solution

Instead of extending SequenceCommand and coding the sequence logic in the commands themselves, let's define a sequence of events outside of the commands. The commands themselves should not extend SequenceCommand. This will allow to create "standalone" commands that have their specific task and then chain them into a variety of sequences.

Explanation

The solution Spring Actionscript offers comes in the form of the EventSequence An <code>EventSequence</code> represents a sequence of events to be chained. class. As said earlier, we want to have a non-intrusive way of defining sequences of events/commands without the need to code sequence logic in the commands. As an example, let's take an event that causes the user to log in, after which another event is dispatched to fetch the latest private messages for that user. In Cairngorm we would have the following:

public function LoginCommand extends SequenceCommand implements IResponder {

    // code left out...

    public function result(data:Object):void {
        var user:UserVO = data.result as UserVO;
        ModelLocator.getInstance().user = user;
        // here is the problem, the command knows what command to execute next
        // we can't reuse this command in another chain
        nextEvent = new LoadPrivateMessagesEvent(user.id);
        executeNextCommand();
    }

}

In the above code, the sequence logic in the result() handler prevents us from reusing the command outside of the sequence or in another sequence. This will most often result in duplicate code which makes the code base hard to maintain.

Looking at the flow of events and commands, we see that in most cases (but not all) a command will update some property in the ModelLocator. This is a good practice, because it keeps your commands consistent across your application: a command executes, proxies a remote call through a business delegate, adds itself as a responder to the remote call, updates the ModelLocator in the result() or fault() handler.

Example

Let's dive into an example of the EventSequence An <code>EventSequence</code> represents a sequence of events to be chained.. The different parts will be explained individually:

var sequence:EventSequence = new EventSequence();

//add a first event to the sequence which let's the user log in

sequence.addSequenceEvent(
    LoginUserEvent,
    [username, password]
);

//add a second event which fetches the latest private messages

sequence.addSequenceEvent(
    LoadPrivateMessagesEvent,
    [new Property(ModelLocator.getInstance, "user", "id")],
    [new Property(ModelLocator.getInstance, "user")]
);

// start the sequence

sequence.dispatch();

Explanation

First thing we need to do of course is create a sequence. We can do this by creating an instance of EventSequence An <code>EventSequence</code> represents a sequence of events to be chained..

Next, the sequence expects us to define different events in it so that it knows when to fire which event. We do this by calling addSequenceEvent() Adds a Cairngorm event to this sequence. on the sequence and passing in the properties of the event we want the sequence to dispatch.

sequence.addSequenceEvent(
    LoginUserEvent,
    [username, password]
);

The first argument is the class of the event. In our case this is LoginUserEvent with has 2 constructor parameters: username and password. These parameters are defined in the second argument of the addSequenceEvent() Adds a Cairngorm event to this sequence. method as an array.

There are 2 options:

The first option, passing in a concrete value, is quite straight forward. In case of the LoginUserEvent we pass in the credentials of the user, which will normally be fetched from the text inputs of the login form. So the definition of this could look as follows:

sequence.addSequenceEvent(
    LoginUserEvent,
    [username, password]
);

The second option is a property that will be evaluated or looked up at runtime and is defined by a host and a chain. In case of the second event, we want to pass in the user's id, but we can only do this if the user is defined in the ModelLocator and has a valid id (this will be after executing the LoginUserCommand). Doing the following wouldn't work (don't worry about the 3rd argument for now):

sequence.addSequenceEvent(
    LoadPrivateMessagesEvent,
    [ModelLocator.getInstance.user.id],
    [new Property(ModelLocator.getInstance, "user")]
);

This will result in a runtime error (null pointer exception) because we want to pass in the concrete value of the user's id when we define the sequence. Since the ModelLocator does not contain a valid user instance at that point, this won't work. Therefor we need to define the value as a property of which the value will be "looked up" when we really need it (that is when firing the next event in our case).

The property defines a host: that is the variable that contains - or better will contain - the needed parameters for the event. In our case this is the model locator, so ModelLocator.getInstance(). The remaining arguments of the property instance are a chain of properties of the host defined as strings. So to get the user's id from the model locator we would define the following:

var p:Property = new Property(ModelLocator.getInstance(), "user", "id");

The third argument of the addSequenceEvent() Adds a Cairngorm event to this sequence. defines a trigger that will instruct the next event to be fired. In the example above, the next event will get fired when the user property of the model locator has changed.

After we have defined the sequence, all we need to do is call it's dispatch method. Also, the event/command mapping is still defined in the front controller, just like you would do without sequences. There is no need to specify any custom mapping.

Where to create sequences?

Normally one would create a subclass of EventSequence An <code>EventSequence</code> represents a sequence of events to be chained. and define the sequence in the constructor. One would then instantiate the sequence in the appropriate view and dispatch it from there.

An alternative approach could be that the front controller has support for defining sequences. We would then have a centralized place for specifying these sequences instead of having them scattered in different classes. In this case there should also be a way of launching a sequence from the view. There's no such feature yet in the Spring Actionscript extensions but if enough requests are made by the community they can be implemented in due time.

What if the command does not update the model locator.

There will be times when a command does not update a property in the model locator. So we don't really have a point in time when we know we should trigger the next event. To solve this, the CairngormFrontController The <code>CairngormFrontController</code> extends Cairngorm's <code>FrontController</code> and adds the ability to pass in a command map to the constructor. registers every executing command in a central registry called the PendingCommandRegistry . The command then has do decide when its action is finished and unregister itself:

public function result(data:Object):void {
    // do some stuff
    // ... now let the sequence know this command is done
    // we do this indirectly by unregistering
    PendingCommandRegistry.getInstance().unregister(this);
}

When calling unregister, the event sequence will get notified of this and trigger the next event if any.

After some learning, investigation and playing with Flex and ActionScript 3, I've headed toward finding ways which can simplify implementation of large-scale enterprise applications in Flex. Why is this needed? Well, I see Flex as a so called "application framework" which can significantly simplify attractive GUI creation, but it doesn't really help in application structuring. That application structure and architecture are important in big projects for various reasons. Most notably, it provides maintainability and scalability of an application code, but it also defines rules and patterns which can serve as a common denominator for a development team.

In that area I've found only two prominent candidates at the time: Adobe's Cairngorm and PureMVC. I first tried Cairngorm, but I didn't really like it, so I tried PureMvc next. In my opinion, PureMvc represents a very solid foundation for building Flex applications. It is well structured and designed, created around core interfaces which define main framework rules, and it certainly can provide the structure needed for many non trivial applications. It is also very well documented.

While I was going through the PureMvc documentation and samples, I was a little bit surprised to see that the PureMvc applications are usually coded to concrete classes instead to interfaces. For example, the typical PureMVC idiom for using a registered proxy instance is to write something like this in a command:

public class DeleteUserCommand extends SimpleCommand implements ICommand {
  
  override public function execute(notification:INotification):void {
    var user:UserVO = notification.getBody() as UserVO;
    var userProxy:UserProxy = facade.retrieveProxy(UserProxy.NAME) as UserProxy;
    var roleProxy:RoleProxy = facade.retrieveProxy(RoleProxy.NAME) as RoleProxy;
    userProxy.deleteItem(user);
    roleProxy.deleteItem(user);
    sendNotification(ApplicationFacade.USER_DELETED);
  }
}

Here you can find the dependencies to the concrete classes UserProxy and RoleProxy. Of course, this particular case can be refactored to the interfaces, but I'm just trying to illustrate the common usage. Further, it will be ideal if you have an ability just to express the dependencies through setters and getters and that some external entity fulfills them by injecting them automatically at runtime. In such scenario, your command will not be dependent on concrete classes, and at the same time it will not be dependent on framework infrastructure like facade. Then, you will be able to code this command to look something like following:

public class DeleteUserCommand extends SimpleCommand implements ICommand {

  private var m_userProxy:IUserProxy;
  private var m_roleProxy:IRoleProxy;

  public function set userProxy(p_userProxy:IUserProxy):void {
    m_userProxy = p_userProxy;
  }

  public function set roleProxy(p_roleProxy:IRoleProxy):void {
    m_rolePrxy = p_roleProxy;
  }

  override public function execute(notification:INotification):void {
    var user:UserVO = notification.getBody() as UserVO;
    userProxy.deleteItem(user);
    roleProxy.deleteItem(user);
    sendNotification(ApplicationFacade.USER_DELETED);
  }
}

Now, the dependencies on concrete classes and framework infrastructure (i.e. facade) are gone from your code, and automatically it is much more maintainable, scalable and testable.

To my knowledge, to achieve something like this with PureMVC is not easy and will require very careful refactoring and recoding of the internal concrete PureMVC classes like Model, View and Controller (I believe that the core PureMVC interfaces can be left intact). Probably, it is not bad to put high goals as long they do not scare you, but to be on a safe route, we can try to achieve something much easier. Let me try to explain with an example.

In my first PureMVC experiment (which was really not so simple I must say), I have to code a proxy class which can load some remote data encoded in XML and convert it in an internal domain model which is usually termed as value objects in PureMVC. Actually domain model and value objects are not the same at all, but they do not differ in the context of this discussion. So, I didn't want to complicate my project with a server side, and I ended up with local XML files. I've also used the loading delegate pattern known from Cairngorm. A loading delegate handles all communications and conversion of encoded data in the domain model. At the end, I've implemented a method in a proxy class which looks something like following:

public function loadCandlestickCollection(p_stockSymbol:StockSymbol):void {

  LOGGER.debug("Loading candlestick collection for stock symbol " + p_stockSymbol.symbol);

  LOGGER.debug("Notifying observers with " + LoadDataNotification.NAME + "." + LoadDataNotification.TYPE_START);
  facade.notifyObservers(new LoadDataNotification(null, LoadDataNotification.TYPE_START));

  var delegate:CandlestickLoadDelegate = new CandlestickLoadDelegate(this);
  delegate.load(p_stockSymbol);
}

Here, CandlestickLoadDelegate is the concrete class which I don't like very much. I mean, I was just prototyping, and this local data loading delegate will be changed in the final version with its remoting equivalent. This will require either refactoring of the proxy method (and implementation of another loading delegate) or refactoring of the current concrete loading delegate. It will be much better to introduce an appropriate loading delegate interface. This can be done with any variation of the factory pattern, but this typically only moves the concrete class dependency in the factory. It will be much better if I have some general purpose factory (which can be configured, not coded) from which I can fetch the dependencies as needed. Something like Spring, but in Flex/AS3 world. For the further reference I will name this type of usage of an IoC container (which has the role of the general purpose configurable factory in this context) as the "ad hoc IoC container usage". It will be helpful if such ad hoc usage can be enabled in a consistent manner, for example as a built-in feature of the extended PureMvc framework. I believe that this can be done fairly easily if I have a good IoC container at disposal.

As it turns out, there is a good IoC container available in Flex world, it is called Spring Actionscript. There are also some others, but Spring Actionscript has several releases, decent documentation, and a very competent, friendly and collaborative lead developer. All in all I decided to try it in a general manner, and specifically, to try to integrate it with PureMVC.

So, I decided to organize my PureMVC/Spring Actionscript integration endeavour in three steps in which I will try to achieve different levels of integration, from easier to harder, of course. It is important to emphasize that I will try not to change the basic PureMVC programming model. I don't want to create a new MVC framework, I just want to integrate Spring Actionscript with PureMVC. That said, it is still expected that some minor changes in the common PureMVC usage patterns will be required.

In the first level of integration I will just try to bring Spring Actionscript in PureMVC as an additional property of the PureMVC facade. That way a developer can use Spring Actionscript in the consistent ad hoc meaner when he needs it. Typically, the container will not contain any configurations of a PureMVC triad (proxy, mediator, command), but only their external dependencies (this should be easy enough, but you never know). Additionally, I expect that this level of integration will require minor changes in the typical PureMVC application's startup procedure. This is caused with asynchronous nature of the container's startup while it reads configuration files.

If only that first integration level will be all that I can achieve, I will be satisfied enough because I believe that by them self it can significantly help in my future Flex projects.

In the second level of integration I plan to bring Spring Actionscript and PureMVC closer, with some functionality which will help to configure the PureMVC elements in Spring Actionscript. Since PureMVC maintains its own object container (at least for proxies and mediators), at this moment I am planning to take into account only objects configured as prototypes (not singletons). While doing this, I'm hoping to learn much more about repercussions that singletons will bring to table, since at least, I expect that some synchronization between Spring Actionscript and PureMVC container will be needed. Hopefully, at the time you will read this, both prototypes and singletons will be equally supported.

With only prototypes supported, Spring Actionscript will not have to manage the PureMVC elements, but rather it will only create them and hand them over to PureMVC. Naturally, this still will be the ad hoc usage of the container and it can be programmed with only "Level 1 integration" available. However, I plan to add some methods in the PureMVC facade which should be helpful in the process. Support for singletons is left for the third level of integration, but it can happen sooner, you never know.

During second phase of integration I expect to learn a great deal about Spring Actionscript's and PureMVC's internal workings. I also expect that the "Level 2 integration" will be much harder to implement than the level one. The typical PureMVC usage patterns will probably stay intact, they just can be implemented through facade's methods with new names. The original PureMVC API will not change, so if you can't find any benefits in the "Level 2 integration", simply just don't use it.

So we came to the third level of integration. In this phase I plan to fully integrate PureMVC and Spring Actionscript in a way that should be hard to define borders between the Spring Actionscript's and PureMVC's containers. All PureMVC elements should be freely configurable through Spring Actionscript either as prototypes or singletons, depending on application's needs. Framework dependencies in application should be minimal in a way that you no longer need to retrieve the PureMVC elements from the PureMVC facade. The dependencies will be injected automatically. Of course, there still will be need to interact with the facade during registration and notification processes. This kind of IoC usage is no longer the ad hoc usage. This is usage of the IoC container at its full potential. We will see if I'm able to implement something like this. :-)

This whole endeavour is highly experimental, so I decided not to develop it in the typical framework style. This is left for later if and when this experiment can be considered as a success. Instead I will take the referential PureMVC Arch101Demo sample, and start to modifying it.