Cairngorm 2 (for Flex 2) – Overview and Migration Path

Earlier this week Cairngorm for Flex 2 has been released. There have been a number of changes compared to Cairngorm for Flex Beta 3. This post intents to explain some of what’s changed, why it changed and how you can handle the changes for migrating your Cairngorm applications to the newest version. Sorry for the delay of this post, but as you might know, there’s a fantastic soccer World Cup in Germany going on these days. ;)


1. Responder interface now optional and typeless.
The signature of Responder has changed to an optional typeless (wildcard type ‘*’) from the mx.rpc.events.ResultEvent and mx.rpc.events.FaultEvent signatures. Here are three reasons for this:

  • You can now handle RemoteService, WebService, RemoteObject and non Flex framework remoting responses.
  • You can now more easily perform spikes (prototypes) to simulate a server side response. Just place stub data into the delegate and return that to the onResult handler of your Command. Since it’s optional, you don’t have to return any data to the Command.
  • If you unit test your Commands, this signature might also be handy.

2. Minor improvements
There have been a number of minor improvements i.e. Cairngorm now prevents to add an already registered Command, the ViewHelper adds and removes itself from the ViewLocator once added or removed from the display list and other minor code refactorings have been performed as well.
3. New Cairngorm Event Dispatcher
This is the most significant change. For Cairngorm Flex 1 users this is familiar as it basically is EventBroadcaster with a more “Flex 2 EventDispatcher-like” syntax.
Here are the corresponding release notes:

In the beta releases of Cairngorm for Flex 2, we departed from the Cairngorm 0.99 approach of dispatching events, and used the new built-in dispatchEvent method with bubbling available on Flex components. However, since bubbling is only available on the display list we had to listen to a top level child on the display list for all events, which we decided to be mx.core.Application.application. In cases where a view reference on the display list below mx.core.Application.application is not available, users had to obtain mx.core.Application.application directly in order to dispatch a Cairngorm event. This was often the case in for example pop-ups and other ActionScript classes without the appropiate view reference. Our experience within Adobe Consulting in delivering Flex 2 projects, coupled with community feedback, has encouraged us to revert to an architecture more like the original Cairngorm 0.99 architecture using EventBroadcaster.

This is indented to encourage developers to have a clear separation of Cairngorm events and application events. The new CairngormEventDispatcher offers exactly this, since only event objects of type CairngormEvent can be dispatched and handled. Furthermore, CairngormEvent has the typeless data property for lazy people. ;) For more information about CairngormEventDispatcher, check out the ASDocs, temporarily available through Alistair McLeod’s blog.
Migrating your Cairngorm Application.
The Flex 2 compiler helps you most with migrating your application. For example it will tell you that the new Responder interface might not be compatible to your pre Cairngorm for Flex 2 application.
However, for larger applications a migration of the event dispatching system from legacy Cairngorm Flex beta Application.application event dispatching to the new event dispatching system using CairngormEventDispatcher could be a bit trickier to accomplish.
The reason is that there could be Cairngorm events that trigger and modify various things while they bubble up the display list till they arrive to the root of the display list and the FrontController. If you would just replace the dispatchEvent calls from the view with CairngormEventDispatcher calls, code that relies on bubbling of events will break. Therefore; in larger applications, this migration should probably not be done in one step.
I’ve created a little migration Front Controller, which can use both techniques simultaneously, so developers can replace this event dispatching code carefully step by step. Here is a potential migration path that you could perform:

  • Delete all legacy Cairngorm framework code with the updated framework. Since it’s a package change, Flex Builder will make it easy for you to spot the places in the application that have to be changed due to Cairngorm 2.
  • Now, here’s the ugly part: In order to make this migration work, you’ve got to temporarily change a Cairngorm source file. Open com.adobe.cairngorm.control.CairngormEvent and set the default value of the bubbles property to true. Make sure you reverse this change after your migration. Or better: Use the Cairngorm framework ActionScript source files while you are in a migration period and replace all Cairngorm framework source files with the Cairngorm SWC file that accompanies the latest release of Cairngorm.
  • Let your application FrontController extend com.adobe.cairngorm.control.MigrationFrontController instead of com.adobe.cairngorm.control.FrontController.

When you now run the application, you’ll receive logging statements if the deprecated cairngorm event dispatching call is invoked. This logging statement can help you to locate the event and help you to make a decision if it can be replaced without side effects.
using trace

---------------------------------------------------------------------------
MigrationFrontController.handleDeprecated: Deprecated event dispatching used with:
event object: com.adobe.cairngorm.samples.dashboard.events::GetStockQuoteEvent
event.type: EVENT_GET_STOCK_QUOTE
event.target: Dashboard0.StockMarketDashboard5._StockMarketPod1
event source: com.adobe.cairngorm.samples.dashboard.view::StockMarketPod
event.currentTarget: Dashboard0

or using mx.logging:

10:27:59.760 [INFO] com.adobe.cairngorm.samples.dashboard.control.DashboardController
---------------------------------------------------------------------------
MigrationFrontController.handleDeprecated: Deprecated event dispatching used with:
event object: com.adobe.cairngorm.samples.dashboard.events::GetStockQuoteEvent
event.type: EVENT_GET_STOCK_QUOTE
event.target: Dashboard0.StockMarketDashboard5._StockMarketPod1
event source: com.adobe.cairngorm.samples.dashboard.view::StockMarketPod
event.currentTarget: Dashboard0

Download MigrationFrontController here.