Robotlegs and AS3-Signals play really well together. Both apply solid object-oriented principles to accomplish their respective goals. Signals is extremely well suited for automated Dependency Injection. By combining Signals and Robotlegs you are able to eliminate the use of Flash Events in the framework layer of your application. Eliminating Events means eliminating the ambiguity that can accompany Events and their String registry based approach to the Observer pattern. Signals provides a strongly-typed object-oriented approach to this same pattern.

With the standard Robotlegs MVCS implementation you leverage the events provided by Actionscript 3 to communicate amongst the various actors of an application. From models and services dispatching notifications of their actions to triggering commands, events are a core piece of the implementation. To facilitate the use of Signals within MVCS it was necessary to create an extension to allow for Signals to be registered as Command triggers. This need spawned the SignalCommandMap utility.

The SignalCommandMap extends the normal MVCS context and creates a SignalContext. The SignalContext instantiates and provides access to the SignalCommandMap alongside the other maps that are standard to Robotlegs. The SignalCommandMap allows you to map Signal classes and instances to commands that will be executed when the Signal dispatch() method is called. The value objects that are passed in the dispatch are then injected into the command alongside any other mapped injections you have created.

Let's take a look at a simple example that makes use of the SignalCommandMap and discuss some of the underlying code to see how it works:

Source available on Github (zip)

The example is a menu that allows you to add food which is displayed in a list. The total cost of your selected items is displayed and you can remove items from your order. First let's get started by taking a look at the context of the Application, which extends SignalContext:

SignalCafeContext.as Bootstraps the Application

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public class SignalCafeContext extends SignalContext
{
    override public function startup():void
    {
      injector.mapSingleton(FoodOrderModel);
      injector.mapSingleton(FoodOrderUpdated);
      injector.mapSingleton(FoodItemAddedToOrder);
 
      signalCommandMap.mapSignalClass(AddFoodItemToOrder, AddFoodItemToOrderCommand);
      signalCommandMap.mapSignalClass(FoodItemSelected, FoodItemSelectedCommand);
      signalCommandMap.mapSignalClass(RemoveAllOfSelectedItem, RemoveAllSelectedItemCommand);
      signalCommandMap.mapSignalClass(NoFoodItemSelected, NoFoodItemSelectedCommand);
 
      mediatorMap.mapView(FoodSelectionView, FoodSelectionViewMediator);
      mediatorMap.mapView(CurrentOrderView, CurrentOrderViewMediator);
      mediatorMap.mapView(FoodOrderSummaryView, FoodOrderSummaryViewMediator);
      mediatorMap.mapView(FoodItemRemovalView, FoodItemRemovalViewMediator);
    }
}

A SignalContext is structured exactly the same as a standard Robotlegs MVCS Context class. You override the startup() method and bootstrap your application. The major difference here is that you are mapping signals to commands instead of mapping events to commands. With the SignalCommandMap you are not restricted to just using Signals for triggering commands. You could mix events and Signals liberally as your needs or requirements dictated. As a warning, this could quickly became confusing and choosing one or the other might be a saner choice.

SignalCafeContext is mapping 4 Signals to 4 commands. The Signals are typed extensions of the base Signal class. This is necessary to provide Robotlegs (and more specifically in this case SwiftSuspenders) object types to differentiate for the purposes of injection. You could use named injections, but this would rapidly riddle your application with strings that would need to be laboriously checked for accuracy. Avoiding strings in favor of compiler-checked object types is always a good choice.

The strongly typed Signals are relatively simple. They contain a constructor and no additional methods or properties are added to the Signal. You can of course add properties and methods to the extended Signals,, but it wasn't necessary for this example. The SignalCommandMap will accept any class that implements the ISignal interface. Let's take a look at one of the commands triggered by a Signal mapped in the SignalCafeContext:

AddFoodItemToOrder.as triggers the AddFoodItemToOrderCommand

1
2
3
4
5
6
7

public class AddFoodItemToOrder extends Signal
{
	public function AddFoodItemToOrder()
	{
		super(FoodType);
	}
}

That is the whole of the extended Signal. As mentioned, it is not very complex at all. You will notice that super(FoodType) is being called. Signals take constructor arguments consisting of classes or interfaces that will be used as the value objects transmitted via the dispatch() method. In this case we are using FoodType as this value to ensure that our Signal will carry the payload that the mapped command is expecting.

Command signals are named a bit differently than standard reaction Signals. A Signal that is triggering a command is "requesting action" or specifying an action that needs to occur. Standard signals are typically past tense, or informative, describing an action that has occurred. By using this standard it is much easier to differentiate quickly what each Signal's purpose is. This can help with overall clarity within your application.

The AddFoodItemToOrder signal is dispatched by the FoodSelectionViewMediator which is mediating the DropDownList of FoodTypes and the "Add Some Food" button:

FoodSelectionViewMediator.as mediates a view and dispatches a Signal when the user has clicked the "Add Some Food" button

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

	public class FoodSelectionViewMediator extends Mediator
	{
		[Inject]
		public var view:FoodSelectionView;
 
		[Inject]
		public var addItem:AddFoodItemToOrder;
 
		override public function onRegister():void
		{
			view.itemTypeAdded.add(handleItemTypeAdded);
		}
 
		protected function handleItemTypeAdded(itemType:FoodType):void
		{
			addItem.dispatch(itemType);
		}
	}

When the AddFoodItemToOrder Signal's dispatch(aFoodTypeInstance) is called the AddFoodItemToOrderCommand is triggered:

AddFoodItemToOrderCommand.as is executed in response to AddFoodItemToOrder Signal dispatch

1
2
3
4
5
6
7
8
9
10
11
12
13

public class AddFoodItemToOrderCommand extends SignalCommand
{
	[Inject]
	public var itemType:FoodType;
 
	[Inject]
	public var model:FoodOrderModel;
 
	override public function execute():void
	{
		model.addItemToOrder(itemType);
	}
}

AddFoodItemToOrderCommand has two public properties that are marked for injection. The itemType property is a FoodType object. As you will recall, FoodType is the parameter that was passed to the AddFoodItemToOrder Signal super constructor. The AddFoodItemToOrder Signal dispatch() included an instance of a FoodType object which will be injected into the AddFoodItemToOrderCommand alongside any other injections that have been mapped and specified. In this case we are also injecting the FoodOrderModel instance that was mapped as a singleton in the SignalCafeContext.

The AddFoodItemToOrderCommand has a simple job. It accesses the FoodOrderModel instance and calls its addItemToOrder method adding the FoodType parameter that was dispatched with the Signal to trigger the command.

That covers the basics of using the SignalCommandMap within a Robotlegs application. There are options that this example doesn't cover. I would recommend looking through the SignalCommandMap unit test suite for a thorough review of its capabilities. There are several more commands and Signals in the example for you to look over as well. Additionally the example uses Signals within views and the model to dispatch notifications. Outside of binding and UI events, no events are being passed within the application.

Hopefully this will give you the basic understanding of using the SignalCommandMap in a Robotlegs application. Let me know if you have any criticisms, comments, suggestions, or ideas regarding the utility's implementation at http://knowledge.robotlegs.org

Jason Crist posted a thought provoking request for his upcoming presentation comparing Robotlegs and Swiz. He's got a clever knack for stirring the framework ant pile and getting developers eyes off their IDEs long enough to discuss their passions. In this case the developers include Ben Clinkinbeard, Shaun Smith, Jesse Warden and myself.

These conversations are always good natured. While we work on (or use) "competing" frameworks there is always a sense of mutual respect. We like our tools but have obvious inclinations towards the projects that we've invested our hearts and souls into.

Ben Clinkinbeard has pointed out (several times!) that Robotlegs is all about extending the MVCS classes. My stock answer is that there is a clear separation between the framework and the concrete MVCS implementation. To paraphrase Ben, "Well show it to me then!"

All of the "official" Robotlegs examples are making use of the MVCS implementation. Why? Because it is solid, recognizable, and fairly easy to get one's head around. It provides a common ground for developers and a set architectural structure which is a huge advantage in any team environment. It is important to make the distinction between the framework and the MVCS implementation. What does that even mean? At the core, Robotlegs is a modular set of tools to provide a convenient mechanism for wiring applications. Robotlegs is not doing class reflection. Robotlegs is not an automated dependency injection solution. Robotlegs is an adapter to a dependency injection solution,by default the lightweight SwiftSuspenders library. Through a set of tools, namely the MediatorMap, CommandMap, ViewMap, and the injection adapter Robotlegs provides a robust starting place to begin coding your application.

The MVCS implementation is a set of base classes loosely modeled on PureMVC. At the heart of the implementation is the Context. The Context creates instances of the various mapping classes, the injection adapter, and gives the developer a centralized IEventDispatcher that can be used for messaging between application tiers.. The other three classes, Actor, Mediator, and Command, reduce boiler plate and provide convenient access to injected dependencies typically used in the the MVCS tiers.

What if you hate PureMVC, don't want to extend any framework classes, or generally just want to work in a different way outside of a prescribed MVCS architecture?

No problem.

Here's the deal. Robotlegs, the framework, is a set of interfaces. You can effectively do whatever you want with these interfaces. You can make use of the base concrete implementations of the core interfaces, use a class from the MVCS implementation, implement your own concrete classes based on the framework core, bring in other libraries or any combination you can think of. In terms of a framework, Robotlegs can be whatever you want/need it to be.

Man Joel, that was a long intro. Where's the freaking code??!?

So, to that end, I sat down to rework my first (and still favorite) Robotlegs example application and demonstrate this concept a bit.

I've stripped the example down slightly, using just the XMLImageService and not connecting to Flickr (in an effort to keep it simple).

Get the source on GitHub
Download the full source as a Zip

This example requires:
Robotlegs
AS3-Signals
SignalsCommandMap library
Flex 4 SDK (a fairly recent version)

The example should be familiar if you've looked at the Image Gallery previously. It loads images from a service and displays them. This version is much different on the code level however. Instead of mediators and data models, the gallery is using presentation models and AS3-Signals. It still uses the Context from the MVCS implementation. it's so f'n handy and I don't want to manually instantiate the maps.

ImageGalleryContext

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public class ImageGalleryContext extends Context
{
	private const VIEW_PACKAGE:String = "org.robotlegs.examples.imagegallery.view.components";
	private const LOAD_GALLERY:String = "loadGallery";
 
	override public function startup():void
	{
		//map the views
		viewMap.mapPackage(VIEW_PACKAGE);
 
		//map the presentation models
		injector.mapSingletonOf( IGalleryViewPresentationModel, GalleryViewPresentationModel );
		injector.mapSingletonOf( IGalleryThumbnailsPresentationModel, GalleryThumbnailsPresentationModel );
 
		//map the services and their factories
		injector.mapSingletonOf( IGalleryImageService, XMLImageService );
		injector.mapSingletonOf( IGalleryFactory, XMLGalleryFactory );
 
		//map the signals
		injector.mapSingleton(GalleryUpdatedSignal);
		injector.mapSingleton(GalleryImageSelectedSignal);
 
		//map the command
		commandMap.mapEvent( LOAD_GALLERY, LoadGalleryCommand );
 
		//go!!
		eventDispatcher.dispatchEvent(new Event(LOAD_GALLERY));
	}
}

As you can see here the context is performing the duty of mapping the injections the application will use.

Automated Dependency Injected View

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

<s:Group xmlns:fx="http://ns.adobe.com/mxml/2009"
		 xmlns:s="library://ns.adobe.com/flex/spark"
		 xmlns:mx="library://ns.adobe.com/flex/halo" width="100%" height="100">
	<fx:Script>
		<![CDATA[
			import org.robotlegs.examples.imagegallery.view.models.IGalleryThumbnailsPresentationModel;
 
			private var _model:IGalleryThumbnailsPresentationModel;
 
			public function get model():IGalleryThumbnailsPresentationModel
			{
				return _model;
			}
 
			[Inject]
			[Bindable]
			public function set model(value:IGalleryThumbnailsPresentationModel):void
			{
				_model = value;
			}
		]]>
	</fx:Script>
	<s:Rect width="100%"
			height="100%">
		<s:fill>
			<s:SolidColor color="#111111"/>
		</s:fill>
	</s:Rect>
	<s:Group width="100%" height="100%">
		<s:layout>
			<s:VerticalLayout gap="0"/>
		</s:layout>
		<s:DataGroup id="dgThumbnails"
					 clipAndEnableScrolling="true"
					 dataProvider="{model.dataProvider}"
					 width="100%"
					 height="85"
					 itemRenderer="org.robotlegs.examples.imagegallery.view.components.renderers.GalleryImageThumbnailItemRenderer">
			<s:layout>
				<s:HorizontalLayout gap="0"/>
			</s:layout>
		</s:DataGroup>
		<s:HScrollBar id="thumbScrollBar"
					  viewport="{dgThumbnails}"
					  width="100%"
					  smoothScrolling="true"/>
	</s:Group>
</s:Group>

The viewMap is set to map the entire components folder. This is a convenient way to provide automated dependency injection to a large number of views. It also maps views in any sub-package of the mapped package.

GalleryViewThumbnailsPresentationModel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

[Bindable]
public class GalleryThumbnailsPresentationModel implements IGalleryThumbnailsPresentationModel
{
	[Inject]
	public var updated:GalleryUpdatedSignal;
 
	[Inject]
	public var imageSelected:GalleryImageSelectedSignal;
 
	[PostConstruct]
	public function mapSignalListeners():void
	{
		updated.add(galleryUpdated);
		imageSelected.add(updateImageSelectionState);
	}
 
	private var _dataprovider:ArrayCollection;
 
	public function get dataProvider():ArrayCollection
	{
		return _dataprovider;
	}
 
	public function set dataProvider(v:ArrayCollection):void
	{
		_dataprovider = v;
	}
 
	private function galleryUpdated(gallery:Gallery):void
	{
		dataProvider = gallery.photos;
		if(gallery.photos[0])
		{
			imageSelected.dispatch(gallery.photos[0]);
		}
	}
 
	private function updateImageSelectionState(image:GalleryImage):void
	{
		for each(var galleryImage:GalleryImage in dataProvider)
		{
			galleryImage.selected = galleryImage == image;
		}
	}
}

IGalleryViewThumbnailsPresentationModel

1
2
3
4
5
6
7
8

/**
 * This interface is simple because the application is simple. Obviously in
 * a large application you'd get more complex interfaces.
 */
public interface IGalleryThumbnailsPresentationModel
{
	function get dataProvider():ArrayCollection;
}

The presentation models are provided as singletons. The application will only display one of each view that requires the model. They are also mapped as interfaces with the interfaces being injected into the views. With the presentation model, the view does not update the model directly. By using interfaces we can supply read-only contracts between the presentation models and the views they control:

XMLImageService

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

public class XMLImageService implements IGalleryImageService
{
	protected static const BASE_URL:String = "assets/gallery/";
 
	[Inject]
	public var galleryFactory:IGalleryFactory;
 
	[Inject]
	public var galleryUpdated:GalleryUpdatedSignal;
 
	public function XMLImageService()
	{
		super();
	}
 
	public function loadGallery():void
	{
		var service:HTTPService = new HTTPService();
		var responder:Responder = new Responder(handleServiceResult, handleServiceFault);
		var token:AsyncToken;
		service.resultFormat = "e4x";
		service.url = BASE_URL+"gallery.xml";
		token = service.send();
		token.addResponder(responder);
	}
 
	protected function handleServiceResult(event:Object):void
	{
		var gallery:Gallery = galleryFactory.createGallery(event.result.image, BASE_URL);
		galleryUpdated.dispatch( gallery );
	}
 
	protected function handleServiceFault(event:Object):void
	{
		trace(event);
 
	}
}

IGalleryImageService

1
2
3
4

public interface IGalleryImageService
{
	function loadGallery():void;
}

The service and its factory class are also mapped as singleton interfaces. This makes it really easy to swap out services (to add a Flickr service for example).

GalleryUpdatedSignal

1
2
3
4
5
6
7

public class GalleryUpdatedSignal extends Signal
{
	public function GalleryUpdatedSignal()
	{
		super(Gallery);
	}
}

The signals are simple classes that merely extend the Signal class and declare their payload type in the super() of the constructor. Signals are a really marvelous concept and provide a lot of very nice functionality. They make a great companion to Robotlegs and I think you will see some really cool stuff being done with Signals and Robotlegs in the very near future.

LoadGalleryCommand

1
2
3
4
5
6
7
8
9
10

public class LoadGalleryCommand
{
	[Inject]
	public var service:IGalleryImageService;
 
	public function execute():void
	{
		service.loadGallery();
	}
}

The application has a single command, LoadGalleryCommand, that is used to actually load the initial images from service and is only called once. In fact, the event that is fired to launch this command in the context startup method is the only event that this application uses (outside of the Flex events on the UI items). That is awesome!

Something you will notice right away looking at the source is that the ImageGalleryContext is the only class that extends a Robotlegs class. You could do without that too, frankly, and create your own context that created the maps and injector instances. I'm not a masochist however, and I will use the provided context for this example. There is a huge amount of potential there for implementing your own custom contexts. I think an interesting implementation might pitch Flash Events altogether and use only Signals for communication between application actors. This example is essentially doing that, but I'd like to get rid of that single event in startup too!

Download the full source as a Zip

Let me know if you make something cool with Robotlegs and post details about it, I've got a stack of these to give away:

Live demos are available on robotlegs.org here

Acme Widget Factory:
The Acme Widget Factory is modular example and deals with loading multiple modules into a shell and communicating between those modules. The shell and each module has its own context.

Lazy Stack:
Lazy Stack is an example of deferred instantiation of Flex components, and how this is handled by the Robotlegs framework.

Wheres Window:
Where's Window is a simple example to show how to mediate and communicate between a set of instances of the same view component that have individual mediators. In this case, the view components are windows in an AIR application. This uses a proxy to register and manage the currently open unique windows. I am going to write a more detailed breakdown of this particular example soon.

The Elevator Pitch

Robotlegs is an IoC/DI container that is modeled on the PureMVC application structure. It is designed to be MVCS, model-view-controller-service, providing metadata dependency injection across these layers. While following the well organized approach of PureMVC, it eliminates the use of framework singletons and takes full advantage of the Flash Platform to keep the dreaded boiler plate code to a minimum. Eliminating these singletons makes unit testing and TDD much easier, which can be a real struggle when trying to isolate classes for testing where these singleton dependencies exist. Robotlegs is fast, clean, and perhaps more importantly fun to work with. There is a smorgasbord of architectural frameworks available for Flex/AS3, but Robotlegs is worth a look even if you are sick of looking at architectural frameworks.

I've been reviewing the various IoC containers available for Flex/Actionscript. One of the benefits of IoC and DI is that it greatly facilitates unit testing. By injecting our dependencies into our applications actors, we are effectively isolating them from the other classes that make the application function. "So what?"

In computer programming, unit testing is a software verification and validation method in which a programmer tests that individual units of source code are fit for use. A unit is the smallest testable part of an application. In procedural programming a unit may be an individual program, function, procedure, etc., while in object-oriented programming, the smallest unit is a class, which may belong to a base/super class, abstract class or derived/child class.

Ideally, each test case is independent from the others: substitutes like method stubs, mock objects, fakes and test harnesses can be used to assist testing a module in isolation. Unit tests are typically written and run by software developers to ensure that code meets its design and behaves as intended. Its implementation can vary from being very manual (pencil and paper) to being formalized as part of build automation. -wikipedia unit testing entry

To effectively unit test classes, we want them to be as isolated as possible. The class needs to stand on its own and have its functionality vetted to ensure that it behaves as expected. When we start to test how our classes behave together, we have entered the land of integration testing. Integration testing is a worthwhile pursuit also, but before we get to that point, we really want to ensure that our classes are solid by themselves.

Using the example in this Robotlegs Image Gallery demonstration, we are going to test a couple of the classes that make up the application. The demo isn't complex. It has a very simple model, a single service, and just a few views. In fact, it might even seem like a waste of time to unit test a simple example such as this, but the concepts are applicable to larger applications where the benefits of this type of testing really start to pay off.

FlexUnit 4 is the framework that is used here. It provides very handy asynchronous testing, meta data support, and a whole bucket of stellar features that I won't even begin to scratch the surface of. FlexUnit 4 also comes with a graphical testrunner interface:

On to the code...

full source is here...

This test runner interface is added to the RobotlegsImageGalleryTestRunner.mxml application:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<?xml version="1.0" encoding="utf-8"?>
<s:Application
	xmlns:fx="http://ns.adobe.com/mxml/2009"
	xmlns:s="library://ns.adobe.com/flex/spark"
	xmlns:mx="library://ns.adobe.com/flex/halo"
	xmlns:flexUnitUIRunner="http://www.adobe.com/2009/flexUnitUIRunner"
	creationComplete="onCreationComplete()">
	<s:layout>
		<s:BasicLayout/>
	</s:layout>
	<fx:Script>
		<![CDATA[
			import org.robotlegs.demos.imagegallery.test.suites.RobotlegsImageGalleryTestSuite;
			import org.flexunit.listeners.UIListener;
			import org.flexunit.runner.FlexUnitCore;
 
			private var core:FlexUnitCore;
			private function onCreationComplete():void
			{
				this.core = new FlexUnitCore();
				core.addListener( new UIListener( uiListener ));
				core.run( RobotlegsImageGalleryTestSuite )
			}
		]]>
	</fx:Script>
 
 
	<flexUnitUIRunner:TestRunnerBase id="uiListener" width="100%" height="100%"/>
</s:Application>

The core runs our test suites, in this case we are only running a single suite: the RobotlegsImageGalleryTestSuite. The test suite carries metadata that identifies it as a FlexUnit suite. There is no need to extend TestSuite as in previous version of FlexUnit:

1
2
3
4
5
6
7
8
9
10
11
12
13

package org.robotlegs.demos.imagegallery.test.suites
{
	import org.robotlegs.demos.imagegallery.test.cases.TestFlickrService;
	import org.robotlegs.demos.imagegallery.test.cases.TestGalleryProxy;
 
	[Suite]
	[RunWith("org.flexunit.runners.Suite")]
	public class RobotlegsImageGalleryTestSuite
	{
		public var testFlickrService:TestFlickrService;
		public var testGalleryProxy:TestGalleryProxy;
	}
}

The suite further defines the test cases that we are going to run, TestFlickrService and TestGalleryProxy. Any other test cases would also be included in this suite. TestFlickrService extends the Robotlegs Service class. It makes an asyncronous call to the Flickr API and retrieves images via the 'interestingness' category, as well as through a text search. The Service class has a dependency that is injected by the framework on its eventBroadcaster property. EventBroadcaster simply wraps an event dispatcher to provide a simplified interface for the framework to access. Service also provides a dispatch(event) convenience method for sending event notifications to the framework context. Our tests are not run within this context, however, so we have run into a problem. Since the framework injects the EventDispatcher into the EventBroadcaster automatically, we apparently have no way to access it and we can't receive framework notifications.

As it happens, we can simply inject our dependencies manually. The TestFlickrService case has a serviceDispatcher property that extends EventDispatcher. In our setUp() method that is called prior to every test, we create a new EventBroadcaster (which takes our serviceDispatcher as an argument) and add it to our fresh FlickrImageService instance. Now the test case has access to the injected dispatcher, and we can listen for our normal flash events that Robotlegs uses for notifications.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

package org.robotlegs.demos.imagegallery.test.cases
{
	import flash.events.EventDispatcher;
 
	import org.flexunit.Assert;
	import org.flexunit.async.Async;
	import org.robotlegs.demos.imagegallery.events.GalleryEvent;
	import org.robotlegs.demos.imagegallery.remote.services.FlickrImageService;
	import org.robotlegs.mvcs.EventBroadcaster;
 
	public class TestFlickrService
	{
		private var service:FlickrImageService;
		private var serviceDispatcher:EventDispatcher = new EventDispatcher();
 
		[Before]
		public function setUp():void
		{
			serviceDispatcher = new EventDispatcher();
			service = new FlickrImageService();
			service.eventBroadcaster = new EventBroadcaster(this.serviceDispatcher);;
		}
 
		[After]
		public function tearDown():void
		{
			this.serviceDispatcher = null;
			this.service.eventBroadcaster = null;
			this.service = null;
		}
 
		[Test(async)]
		public function testRetreiveImages():void
		{
			this.serviceDispatcher.addEventListener( GalleryEvent.GALLERY_LOADED, Async.asyncHandler(this, handleImagesReceived, 3000, null, handleServiceTimeout), false, 0, true);
			this.service.loadGallery();
		}
 
		[Test(async)]
		public function testSearchImages():void
		{
			this.serviceDispatcher.addEventListener( GalleryEvent.GALLERY_LOADED, Async.asyncHandler(this, handleImagesReceived, 3000, null, handleServiceTimeout), false, 0, true);
			this.service.search("robotlegs");
		}
 
		protected function handleServiceTimeout( object:Object ):void
		{
	    	        Assert.fail('Pending Event Never Occurred');
		}
 
		protected function handleImagesReceived(event:GalleryEvent, object:Object):void
		{
			Assert.assertEquals("The gallery should have some photos: ", event.gallery.photos.length > 0, true)
		}
 
 
	}
}

After each test is run, our tearDown method is called by FlexUnit which sets our service and its eventBroadcaster to null in preparation for the next test in this case to be run. While this example isn't very complex, it is easy to see how this could be extended to a much more complicated service.

The GalleryProxy class is tested in much the same way, though it doesn't have any async methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

package org.robotlegs.demos.imagegallery.test.cases
{
	import org.flexunit.Assert;
	import org.robotlegs.demos.imagegallery.models.proxies.GalleryProxy;
	import org.robotlegs.demos.imagegallery.models.vo.Gallery;
	import org.robotlegs.demos.imagegallery.models.vo.GalleryImage;
 
	public class TestGalleryProxy
	{
		private var galleryProxy:GalleryProxy;
 
		[Before]
		public function setUp():void
		{
			this.galleryProxy = new GalleryProxy()
		}
 
		[After]
		public function tearDown():void
		{
			this.galleryProxy = null;
		}
 
		[Test]
		public function testSetGallery():void
		{
			var gallery:Gallery = new Gallery();
			this.galleryProxy.gallery = gallery;
			Assert.assertEquals("GalleryProxy should have a gallery", this.galleryProxy.gallery != null, true );
		}
 
		[Test]
		public function testSetSelectedImage():void
		{
			var image1:GalleryImage = new GalleryImage()
			var image2:GalleryImage = new GalleryImage()
			var gallery:Gallery = new Gallery()
			this.galleryProxy.gallery = gallery;
			gallery.photos.addItem(image1);
			gallery.photos.addItem(image2);
			image1.selected = false;
			image2.selected = true;
			this.galleryProxy.setSelectedImage(image1);
			Assert.assertEquals("Image1 should be selected", image1.selected, true);
			Assert.assertEquals("Image 2 should NOT be selected", image2.selected, false);
		}
	}
}

With these simple tests we are 100% certain that our classes function as expected on their own, completely isolated from the rest of the application.

You really should call your mom...

We are all unit testing our code and following strong Agile/TDD processes, right.... right? I don't know how much unit testing is going on in the Flash/Flex world, but my guess that the overall test coverage percentage is very small. RIAs are here. They are becoming full fledged applications that people rely on to do business. There will come a time in your RIAs life that you will need to get in there and do some refactoring. It might be for performance, fixing bugs, or adding some new kickass feature to push your app to the next level. Fact, without unit testing:

you're not refactoring; you're just changing shit. -Hamlet D'Arcy

There are many, many arguments for unit testing your code, but for me this is the most compelling. At some point in the future, you are going to want to get in there and make some changes. If your application is important to your users, you want to make sure those changes don't break everything. It is guaranteed that they will break something, the question is will you know immediately what happened, or at least where to look?

We are getting the proper tools for the job. FlexUnit 4 is an incredible project. There is a robust selection of frameworks that all have merits and can facilitate structured, well designed applications. I'm personally out of excuses. I want to develop applications that my users can trust and rely on to do business, and unit testing is a part of that recipe.

This is the second part in a series exploring Inversion of Control and Dependency Injection containers available for Flex. In the first part of the series we discussed what IoC and DI are and how they can benefit our applications. In this part, we will explore the Parsley IoC Container through a simple image gallery application.

Here's the source on github...

Less talk. More Code.

One aspect of an IoC/DI container that is consistent across frameworks is the need to bootstrap the configuration. Parsley provides several ways to accomplish this.

from the docs:

Configuring and initializing the Parsley Framework usually consists of the following steps:

Step 1: Telling the IOC Container which classes it should manage. This can be done with MXML, XML files or in ActionScript. All three mechanisms will be described in the following sections.

Step 2: Configure the container services like Dependency Injection or Messaging for each individual class. This can be done with the mechanism you had chosen for step 1 (e.g. with MXML or XML configuration tags) or - in most cases - conveniently with AS3 Metadata Tags right within the classes themselves.

Step 3: Initialize the IOC Container (usually on application startup). In Parsley 2 this is a one-liner in most cases. See the sections below for examples.

In the image gallery sample step one is accomplished in Beans.mxml. Beans is, I assume, a throwback to Java that I don't fully understand, but it seems to be a popular convention and I'm not here to rock the boat.

Beans.mxml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<mx:Object
    xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns="http://www.spicefactory.org/parsley"
    xmlns:models="com.joelhooks.parsley.example.models.*"
    xmlns:controllers="com.joelhooks.parsley.example.controllers.*"
    xmlns:presentation="com.joelhooks.parsley.example.models.presentation.*">
 
    <mx:Script>
    	<![CDATA[
    		import com.joelhooks.parsley.example.delegates.FlickrImageServiceDelegate;
    	]]>
    </mx:Script>
 
    <!-- Service Delegate -->
    <object id="photoServiceDelegate" type="{FlickrImageServiceDelegate}">
    	<property name="apiKey" value="YOUR_KEY_HERE"/>
    	<property name="secret" value="YOUR_SECRET_HERE"/>
    </object>
 
    <!-- Model -->
    <presentation:FlickrGalleryPresentationModel id="galleryPresentationModel"/>
 
    <!-- Actions -->
    <controllers:RetrieveGalleryAction />
    <controllers:DisplayGalleryAction />
    <controllers:SelectImageAction />
 
</mx:Object>

The application has several actors that Parsley needs to be aware of, and this is where you let the container know what they are. In most cases we can simple use MXML notation to include our classes in the configuration. The photo service, in this case Flickr, needs additional configuration so it is added a bit differently utilizing the Parsley Object and Property tags. When using this method the class needs to be imported as above to provide a reference. In addition to the service the presentation model is also added to the configuration, as well as several actions that will react to various events. The Model and Controller of the MVC triad are what we are configuring here. The View is handled a bit differently.

The configuration is loaded in the preinitialize handle of the main application MXML.

ParsleyGallery.mxml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<s:Application
	xmlns:fx="http://ns.adobe.com/mxml/2009"
	preinitialize="onPreInitialize()"
	xmlns:s="library://ns.adobe.com/flex/spark"
	xmlns:mx="library://ns.adobe.com/flex/halo"
	minWidth="1024" minHeight="768"
	xmlns:tag="org.spicefactory.parsley.flex.tag.*"
	xmlns:spicefactory="http://www.spicefactory.org/parsley/flex"
	addedToStage="this.addedToStageHandler(event)"
	applicationComplete="trace('application complete');"
	xmlns:views="com.joelhooks.parsley.example.views.*"
	xmlns:delegates="com.joelhooks.parsley.example.delegates.*">
	<s:layout>
		<s:VerticalLayout/>
	</s:layout>
	<fx:Script>
		<![CDATA[
			import com.joelhooks.parsley.example.delegates.FlickrImageServiceDelegate;
			import mx.controls.Button;
			import org.spicefactory.lib.reflect.types.Void;
			import org.spicefactory.lib.logging.Logger;
			import mx.logging.LogEventLevel;
			import com.joelhooks.parsley.example.events.GalleryImageServiceEvent;
			import org.spicefactory.parsley.flex.FlexContextBuilder;
 
			protected function onPreInitialize():void
			{
				this.logTarget.level = LogEventLevel.ALL;
				FlexContextBuilder.build(Beans);
			}
 
			protected function addedToStageHandler(event:Event):void
			{
				//Let the container know that this component is ready to be added
				//to the view context
				dispatchEvent(new Event('configureIOC', true));
			}
 
		]]>
	</fx:Script>
	<fx:Declarations>
		<mx:TraceTarget id="logTarget"/>
	</fx:Declarations>
	<views:GalleryView/>
</s:Application>

We want to make sure that the Parsley container is configured at the first opportunity, and preinitialize provides this hook. After the application has been added to the stage, we need to dispatch a message to the container so that it can be added to the ViewContext allowing the visual components to interact with the container. This is done by dispatching a bubbling 'configureIOC' event in the addedtoStage handler.

This needs to be done for all viewComponents that require access to the container as you will see in the child GalleryView. At this point, the application is fully configured within the IoC Container. Our actors that have been configured in Beans.mxml have had their appropriate dependencies injected, and our Actions are ready to receive messages from the other objects in the container.

DisplayGalleryAction.as:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

/*
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
*/
package com.joelhooks.parsley.example.controllers
{
	import com.joelhooks.parsley.example.events.GalleryEvent;
	import com.joelhooks.parsley.example.events.GalleryImageEvent;
	import com.joelhooks.parsley.example.models.presentation.IGalleryPresentationModel;
	import com.joelhooks.parsley.example.models.vo.GalleryImage;
 
	import flash.events.EventDispatcher;
 
	[Event(name="selectGalleryImage", type="com.joelhooks.parsley.example.events.GalleryImageEvent")]
	[ManagedEvents("selectGalleryImage")]
	public class DisplayGalleryAction extends EventDispatcher
	{
		[Inject(id="galleryPresentationModel")]
		public var galleryPresentationModel:IGalleryPresentationModel;
 
		public function DisplayGalleryAction()
		{
		}
 
		[MessageHandler(selector="galleryLoaded")]
		public function handleGalleryLoaded(event:GalleryEvent):void
		{
			this.galleryPresentationModel.gallery = event.gallery
			trace(event.gallery.photos.length);
			this.dispatchEvent(new GalleryImageEvent(GalleryImageEvent.SELECT_GALLERY_IMAGE,
				event.gallery.photos[0] as GalleryImage));
		}
	}
}

The DisplayGalleryAction class is wired to listen for the system message (event) galleryLoaded. It has no interest in where this message originates, and simply responds as instructed when the message is received. The handleGalleryLoaded method is designated as the MessageHandler for the galleryLoaded message. The message is an actionscript event that has been intercepted by the container and routed to interested parties. You will notice that the handleGalleryLoaded method is constructed exactly like any other Actionscript event handler (with the addition of the Parsley metadata). In this case it receives the custom GalleryEvent that carries some information.

Additionally, DisplayGalleryAction has been injected with our FlickrGalleryPresentationModel from Beans.mxml. FlickrGalleryPresentationModel implements IGalleryPresentationModel, and Parsley will inject any class that implements this interface and has the appropriate ID 'galleryPresentationModel'.

DisplayGalleryAction also dispatches the ManagedEvent 'selectGalleryImage'. Any container actor that dispatches events that need to be distributed to other interested parties need to let the container know. The class is annotated with AS3 metadata designating which ManagedEvent the class will be sending to the container.

DisplayGalleryAction receives Messages from FlickrImageServiceDelegate. it could, of course, receive its Messages from any class that is managed by the container, but in this case it is only interested in the data loaded by the delegate.

FlickrImageServiceDelegate.as:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

/*
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
*/
package com.joelhooks.parsley.example.delegates
{
	import com.adobe.webapis.flickr.FlickrService;
	import com.adobe.webapis.flickr.Photo;
	import com.adobe.webapis.flickr.events.FlickrResultEvent;
	import com.adobe.webapis.flickr.methodgroups.Photos;
	import com.adobe.webapis.flickr.methodgroups.helpers.PhotoSearchParams;
	import com.joelhooks.parsley.example.events.GalleryEvent;
	import com.joelhooks.parsley.example.events.GalleryImageServiceEvent;
	import com.joelhooks.parsley.example.models.vo.Gallery;
	import com.joelhooks.parsley.example.models.vo.GalleryImage;
 
	import flash.events.Event;
	import flash.events.EventDispatcher;
 
	import mx.collections.ArrayCollection;
 
	[Event(name="serviceReady", type="com.joelhooks.parsley.example.events.GalleryImageServiceEvent")]
	[Event(name="galleryLoaded",type="com.joelhooks.parsley.example.events.GalleryEvent")]
	[ManagedEvents("galleryLoaded,serviceReady")]
	public class FlickrImageServiceDelegate extends EventDispatcher implements IGalleryImageServiceDelegate
	{
		private var service:FlickrService;
		private var photos:Photos;
 
		public var apiKey:String;
		public var secret:String;
		public var NSID:String;
 
		public function FlickrImageServiceDelegate()
		{
		}
 
		[PostConstruct]
		public function init():void
		{
			trace("Configuring Service");
			this.service = new FlickrService(this.apiKey);
			this.photos = new Photos(this.service);
			this.dispatchEvent(new GalleryImageServiceEvent(GalleryImageServiceEvent.SERVICE_READY));
		}
 
		public function loadGallery():void
		{
			service.addEventListener(FlickrResultEvent.INTERESTINGNESS_GET_LIST, handleSearchResult);
			service.interestingness.getList()
		}
 
		protected function handleSearchResult(event:FlickrResultEvent):void
		{
			this.processFlickrPhotoResults(event.data.photos.photos);
		}
 
		protected function processFlickrPhotoResults(results:Array):void
		{
			var gallery:Gallery = new Gallery();
			gallery.photos = new ArrayCollection();
			for each(var flickrPhoto:Photo in results)
			{
				var photo:GalleryImage = new GalleryImage()
				var baseURL:String = 'http://farm' + flickrPhoto.farmId + '.static.flickr.com/' + flickrPhoto.server + '/' + flickrPhoto.id + '_' + flickrPhoto.secret;
				photo.thumbURL = baseURL + '_s.jpg';
				photo.URL = baseURL + '.jpg';
				gallery.photos.addItem( photo );
			}
 
			this.dispatchEvent(new GalleryEvent(GalleryEvent.GALLERY_LOADED, gallery));
		}
	}
}

As we've seen, the FlickrImageServiceDelegate is an implementation of the IGalleryImageServiceDelegate interface. This allows us to program to an interface instead of an implementation for that loose coupling goodness we all crave. This will come in very handy when we want to modify the application to handle multiple services or build mock objects for the purpose of unit testing (the subject of part 3).

As with the DisplayGalleryAction class, FlickrImageServiceDelegate is configured to send ManagedEvent messages to the container. One of these events is 'serviceReady'. FlickrImageServiceDelegate utilizes the [PostConstruct] annotation on its init method. When this class was configured, we injected properties (the apiKey and secret), and the service cannot be configured without these. Using [PostConstruct] the container is ordered to run the annotated method after the class has been configured thus ensuring our properties have been injected as expected. FlickrImageServiceDelegate then dispatches the 'serviceReady' Message so that the actors waiting to get to work can do what they need to do.

The GalleryView is responsible for displaying the data and accepting user interaction.

GalleryView.mxml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<s:Group
	xmlns:fx="http://ns.adobe.com/mxml/2009"
	xmlns:s="library://ns.adobe.com/flex/spark"
	xmlns:mx="library://ns.adobe.com/flex/halo"
	width="500" height="600"
	addedToStage="dispatchEvent(new Event('configureIOC', true));" creationComplete="creationCompleteHandler(event)" xmlns:display="com.joelhooks.display.*">
 
	<s:layout>
		<s:BasicLayout/>
	</s:layout>
	<fx:Metadata>
		[Event(name="selectGalleryImage", type="com.joelhooks.parsley.example.events.GalleryImageEvent")]
		[ManagedEvents("selectGalleryImage")]
	</fx:Metadata>
 
	<fx:Script>
		<![CDATA[
			import org.spicefactory.lib.reflect.types.Void;
			import mx.events.FlexEvent;
			import com.joelhooks.parsley.example.events.GalleryImageEvent;
			import com.joelhooks.parsley.example.models.presentation.IGalleryPresentationModel;
			import com.joelhooks.parsley.example.views.renderers.GalleryImageThumbnailItemRenderer;
			import mx.collections.ArrayCollection;
 
			[Bindable]
			[Inject(id="galleryPresentationModel")]
			public var model:IGalleryPresentationModel;
 
 
			protected function creationCompleteHandler(event:FlexEvent):void
			{
				this.dgThumbnails.addEventListener( GalleryImageEvent.SELECT_GALLERY_IMAGE, handleSelectImage);
			}
 
			protected function handleSelectImage(event:GalleryImageEvent):void
			{
				this.dispatchEvent(event);
			}
 
		]]>
	</fx:Script>
	<s:Group width="100%" height="100%">
		<s:Rect width="100%" height="100%">
			<s:fill>
				<mx:SolidColor color="#000000"/>
			</s:fill>
		</s:Rect>
	</s:Group>
	<s:Group width="100%"  height="100%">
		<s:layout>
			<s:VerticalLayout gap="0"/>
		</s:layout>
		<display:ImageSwap id="image" width="100%" height="100%" source="{this.model.selectedImage.URL}" />
 
		<s:DataGroup
			id="dgThumbnails"
			clipAndEnableScrolling="true"
			width="500"
			height="85" mouseEnabled="{!image.changingImages}" mouseChildren="{!image.changingImages}"
			dataProvider="{this.model.gallery.photos}"
			itemRenderer="com.joelhooks.parsley.example.views.renderers.GalleryImageThumbnailItemRenderer">
			<s:layout>
				<s:HorizontalLayout gap="0"/>
			</s:layout>
		</s:DataGroup>
		<s:HScrollBar viewport="{this.dgThumbnails}" width="500"/>
	</s:Group>
</s:Group>

As with the main application MXML, the GalleryView sends a 'configureIOC' event to the container when it is added to the stage. This allows it to participate in the Messaging system and have its dependencies injected. GalleryView dispatches one message, 'selectGalleryImage', when a user clicks a thumbnail. It is also injected with a reference to the applications IGalleryPresentationModel (FlickrGalleryPresentationModel) where it accesses the array collection containing the objects presented in the thumbnail DataGroup.

There are two more Actions, RetreiveGalleryAction and SelectImageAction that function as their names imply. In addition the project has several custom events that are used for messaging. I'm not going to detail these as it would be repetitive, but it is worth noting that this only scratches the surface of the features that are available in Parsley. The docs are extensive, and the API is extremely robust. Typically you won't ever need to access the API directly after you make the call in the preinitialize method to bootstrap the container. After that it does its work silently in the background.

So I think...

Parsley could be considered a 'magical' black box framework. This is the trade off you get removing all of the boiler plate code you see in other frameworks. Looking at the extent of classes and libraries that make up Parsley is intimidating. You are placing a lot of trust in a complicated framework and have to hope that trust isn't misplaced. There is something to be said for a simple 'non-magical' framework like PureMVC. Yes, it comes at the cost of boiler plate code, but comprehension is less of a concern.

The biggest challenge Parsley presents to learning the framework is that code examples are scarce (at best) outside of the out of context examples in the (excellent otherwise) documentation and a couple blog posts. Researching the framework, I actually found myself referring to SWiZ examples to understand some of the applied concepts. This is interesting in that the SWiZ examples really do carry over, as the frameworks have significant overlap in scope and functionality. There is a thread on the SWiZ Google Group that goes into this, and I was surprised to see the complete lack of knowledge even to the existence of Parsley. I've been aware of the framework since early 2008, but didn't take time to get my head around it. It really is perplexing as to why there aren't more examples floating around, as Parsley is very mature and robust at this stage in its development. That is something that I really love about PureMVC. Cliff has done such an excellent job centralizing the examples and framework tutorials with the manifold project. The effort it takes to maintain are huge, so I understand that most don't have the time or inclination to do so, but it is much appreciated to be sure.

In Part 3 we will go into swapping out the service and get a little unit testing coverage on the application.

The Inversion of Control (IoC) design principle and the related Dependency Injection (DI) design pattern have been around for several years. In the Java world, popular frameworks such as Spring make heavy use of these concepts. With the introduction of Actionscript 3 in 2006, the opportunities for framework development increased greatly. As the community matures, we are starting to see robust tools appear on the development landscape. It is a good time to be a Flash geek!

Through this series of articles, we will delve into the Parsley application framework and look at how it implements IoC and DI in the context of a photo slideshow. Through this example we will look at bootstrapping the container, connecting to services, and populating our components with the results. In this first part, we will get an overview of IoC and DI and talk about some of the benefits and drawbacks of using these concepts in our applications.

What is Inversion of Control?

One important characteristic of a framework is that the methods defined by the user to tailor the framework will often be called from within the framework itself, rather than from the user's application code. The framework often plays the role of the main program in coordinating and sequencing application activity. This inversion of control gives frameworks the power to serve as extensible skeletons. The methods supplied by the user tailor the generic algorithms defined in the framework for a particular application. --Ralph Johnson and Brian Foote [1]

If you are using an Actionscript framework in your development, odds are you’re making use of IoC. This includes Flex itself, PureMVC, Mate, SWiZ, Parsley, and other similar frameworks. The framework is providing an abstracted skeleton to which the developer can code against. Communication between the actors in the system are coordinated by the framework within a predefined architecture. In other words, some level of control is inverted from the individual components of an application to the underlying framework.

This inversion can be approached from many different directions. In frameworks such as PureMVC and Cairngorm, this inversion of control is handled by extension of framework classes. By extending these objects, the framework is provided with the appropriate interface to access and manipulate the application specific objects. Frameworks such as Parsley and SWiZ provide metadata annotation as the mechanism for wiring into the framework.

What is Dependency Injection?

DI is a design pattern canonized by Martin Fowler [2]. Essentially, your application’s objects do not configure themselves. They rely on an external mechanism for configuration that ‘injects’ the object’s dependencies by populating its instance variables. Fowler felt that Inversion of Control was too generic of a description (as all frameworks tend to invert control), and decided on the name Dependency Injection for the pattern.

Dependency Injection means giving an object its instance variables [3]

Say what? Given this simple definition of DI, this is something we are all making use of on a constant basis. Unless you are writing strictly procedural AS3 (which is certainly possible), DI is likely being used in your applications. Yes, the concept can quickly become more complex - abstracting simple concepts tends to have that effect.

The pattern describes three primary methods for injecting our dependencies:

1
2
3
4
5
6
7
8
9
10
11
12

package
{
	public class MyObject
	{
		private var dependsOn:IDependency;
 
		public function MyObject(dependsOn:IDependency)
		{
			this.dependsOn = dependsOn;
		}
	}
}

1

var myObject:MyObject = new MyObject(aDependencyImplementation);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package
{
	public class MyObject
	{
		private var dependsOn:IDependency;
 
		public function MyObject()
		{
		}
 
		public function setDependsOn(value:IDependency):void{
			this.dependsOn = value;
		}
	}
}

1
2

var myObject:MyObject = new MyObject()
myObject.setDependsOn(aDependencyImplementation);

1
2
3
4
5
6
7
8
9
10
11

package
{
	public class MyObject
	{
		public var dependsOn:IDependency;
 
		public function MyObject()
		{
		}
	}
}

1
2

var myObject:MyObject = new MyObject()
myObject.dependsOn =  aDependencyImplementation;

Setter and property injection are both very similar, and are useful for optional dependencies. Constructor injection is useful for required dependencies that an object must have to function.

Benefits of Dependency Injection

One of the primary benefits of DI is related to unit testing your application. DI allows you to create loosely couple objects that can be easily replaced with mock or stub objects for testing. Unit testing needs to test your objects in isolation, without regard for how the object interacts with its various dependencies.

A unit test is a user of the object it tests. An object must exist for a reason, so there must be other objects that also use it. Even when only one application object uses it, the fact that the unit test is also a user means it has at least two users, and therefore the object must be reusable by design. Test-driven development (TDD), in which unit tests are written before the objects they test, is gaining as a development best practice. One beneficial consequence of TDD is that objects are designed with testability in mind, and therefore, an object and its dependencies must be loosely coupled and reusable. Dependency injection is a popular pattern to design loosely coupled—and therefore robust, reusable, and testable—objects. [4]

DI can also encourage component reuse in much the same way. Since the object’s dependencies are not hard-coded, it is open for reuse. The injectable objects are more adaptable allowing developers to see clearly where to start adding features. The loose coupling can create a more maintainable code-base allowing developers to more easily track down bugs.

Drawbacks of Dependency Injection

No Silver Bullets. [5]

DI can potentially obfuscate an application. To understand the application a developer has to understand both the code and the configuration defining the dependency injections. In many situations, an IDE will not be able to read and give feedback on the configuration.

Inversion of Control Containers

You don’t need an IoC Container (framework) to benefit from DI. As we have seen, you are probably already using DI in your code, irrespective of your preferred framework. IoC Containers provide out of the box methods for instantiating and configuring your application’s objects. The use of an IoC container is dependent on your (and your application’s) needs. For smaller projects, it might not be appropriate.

In the second part of this series, we will look into the Parsley application framework and its implementation of an IoC container and DI.

[1] http://www.laputan.org/drc/drc.html
[2] http://martinfowler.com/articles/injection.html
[3] http://jamesshore.com/Blog/Dependency-Injection-Demystified.html
[4] http://www.ddj.com/development-tools/185300375
[5] http://www.virtualschool.edu/mon/SoftwareEngineering/BrooksNoSilverBullet.html

That is what Jesse Warden (JesterXL) asks the fine folks over at the PureMVC forums. Cliff gives a good rundown on the why/when/how of PureMVC Commands.

PureMVC's relatively light use of commands, when compared to other widely used MVC frameworks, tends to make one think they are doing something wrong. This isn't really the case. Commands are still viable actors in our applications, but many times the shortest route is the best route. PureMVC doesn't force us to use them, but gives us access when we need to.

I generally use PureMVC Commands for actions that can be initiated from several places, as well as for application startup. I've also found them very useful for popups and AIR window management.

One of the many reasons I love PureMVC is the community of highly intelligent, skilled, object-oriented (oriented) programmers that are constantly using the framework to build new and interesting utilities. This is a by-product of the very nature of PureMVC. Cliff architected the core framework in such a way that is is truly simple, providing a base from which to build new useful structures.

Fabrication, a new utility developed by Darshan Sawardekar is a shining example of this fact. He has taken the PureMVC multi-core apperatus, combined it with Cliff's Pipes utility, and created a wonderfully abstracted means for creating modular PureMVC applications. Not only does this simplify the connection of modules in your application and allow them to communicate seamlessly, but he provides a router/firewall metaphor for controlling the communication as well as undo/redo functionality.

Thanks Darshan, your efforts are appreciated. And as always, thanks Cliff for providing the base from which our community can build and contribute. Cheers.

 My code smells bad. There is no doubt about it. As soon as I read that metaphor my head was nodding with understanding. This book is a classic, and I recommend it to anybody that wants to improve their coding habits and create more flexible applications that don't make you sad and angry.

 It is a thick volume, but 2/3s of the text is the catalog of refactorings. This makes the text describing the concepts of refactoring a relatively short read. Mr Fowler guides you through the process, providing a simple example and clearly explaining the thought processes involved. The catalog covers a wide range of common approaches to refactoring an application.

In computer programming, an enumerated type is an abstract data type used to model an attribute that has a specific number of options (or identifiers) such as the suit of a playing card (i.e. a Club, Diamond, Heart or Spade). Using this type allows the program to handle the attribute more efficiently than a string while maintaining the readability of the source code.
-from Wikipedia

I've found this method (illustrated in code below) for enumeration of datasets to be useful, and at this point even essential, in my applications. Prior to this I was actually cutting and pasting the arrays that I was using in my various combo boxes and other selection components as dataProviders. By breaking the dataset into an enumeration class, it makes it easy to maintain the list and lets the dataset function as a first class citizen, ensuring that your data is consistent throughout the application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

package enum
{
	/**
	 * CloudTypeEnum enumerates cloud types.
	 * @author JHooks
	 *
	 */
	public class CloudTypeEnum
	{
		public static const NONE:CloudTypeEnum			= new CloudTypeEnum( "None",	   -1 );
		public static const CUMULUS:CloudTypeEnum		= new CloudTypeEnum( "Cumulus", 	0 );
		public static const STRATUS:CloudTypeEnum		= new CloudTypeEnum( "Stratus", 	1 );
		public static const CIRRUS:CloudTypeEnum		= new CloudTypeEnum( "Cirrus", 		2 );
		public static const NIMBUS:CloudTypeEnum		= new CloudTypeEnum( "Nimbus", 		3 );
 
		public var value:String
		public var ordinal:int
 
		/**
		 * CloudTypeEnum constructor
		 * @param value
		 * @param ordinal
		 *
		 */
		public function CloudTypeEnum( value:String, ordinal:int )
		{
			this.value = value;
			this.ordinal = ordinal;
		}
 
		/**
		 * A list of cloud types
		 * @return
		 *
		 */
		public static function get list( ):Array
		{
			return [ CUMULUS,
					 STRATUS,
					 CIRRUS,
					 NIMBUS ];
		}
 
		/**
		 * A list of cloud types appropriate for use in ComboBox and other
		 * selection components as a DataProvider
		 *
		 * myComboBox.dataProvider = CloudTypeEnum.cList;
		 * @return
		 *
		 */
		public static function get cList( ):Array
		{
			return list.unshift( NONE );
		}
 
		/**
		 * Select a cloud type by its value property
		 * @param value
		 * @return
		 *
		 */
		public static function selectByValue( value:String ):TaskTypeEnum
		{
			for each ( var cloudType:TaskTypeEnum in CloudTypeEnum.list )
			{
				if ( value == cloudType.value )
					return cloudType;
			}
 
			return NONE;
		}
	}
}

Thanks to Cliff Hall who showed this to me via one of his PureMVC demo applications. For the life of me I can't remember which one.