Eric Feminella

One of the most powerful and convenient features of Flex is data binding. Data binding is the process of tying the data in one object (the source) to another object (the destination). Data binding can be used at compile time via the [Bindable] meta data tag and at runtime via the mx.bindings.utils API.

The mx.bindings.utils API provides a mechanism for dynamically applying data binding to an object. However, it does not provide a means for managing a specific data binding chain as a single unit.

The DynamicBindingChain API provides developers with a basic, yet robust API which allows multiple objects in a data binding chain to be managed. It provides a wrapper interface into the mx.bindings.utils API allowing objects to be added to a data binding chain, removed from the chain, validated against the property criteria in the chain as well as other methods for working with a managed data binding chain.

I have provided an example demonstrating some of the features available in the DynamicBindingChain API. In the example,  four TextArea objects text properties are dynamically bound and unbound to a TextInput objects text value.

Click here to view an example of the DynamicBindingChain. You can also view the source as well as the accompanying ASDoc.

A very important, yet somewhat overlooked area of design is documentation. For every public API published the quality of the code and it’s resulting usage is dramatically affected by the accompanying documentation.

In ActionScript 3.0 the ASDoc tool is invaluable. Not only is it fully supported, it is the standard for all ActionScript and mxml code documentation. Unfortunately, it is somewhat tedious to manually compile the documentation from the command line for each API you develop. To help assist developers in generating ASDocs from their code I have created a very simple ANT task which can easily be integrated within a Flex project to automate ASDoc generation.

The ASDocAntTask can be utilized from within Eclipse just as one would typically use a standard build file. Simply create an Eclipse project from the extracted file and specify the location of the source code you would like to compile documentation for as well as the directory where the generated ASDocs are to reside.

The ASDocAntTask project is comprised of the following files: asdoc.xml and asdoc.properties. Developers can specify project specific settings in asdoc.properties and run the default main target from asdoc.xml to both create the output directory, generate documentation from the source code as well as create a log file for the generated ASDocs.

The asdoc.properties file contains the following properties:

• asdoc.exe (location of asdoc.exe)
• src (location of source code)
• main.title (Documentation title)
• window.title (HTML window title)
• output.dir (Documentation output location)

The asdoc.xml contains file contains the following targets:

• clean (creates the output directory)
• create-docs (generates the ASDocs)
• log (creates the log.txt file)

These tasks can easily be modified to match your specific environment. They are very easy to use so if you do not regularly document your work then hopefully this will help get you in the habit.

You can download the ASDocAntTask eclipse project here

I have updated Cairngen to version 1.2 which introduces complete support for all Cairngorm 2+ releases as well as additional features to further improve usability.

If you are not familiar with Cairngen, it is an Ant based code generation tool for Adobe Cairngorm which allows developers to create Cairngorm project directories and classes from Flex Builder.

This latest release of Cairngen includes a few new features which have been added in addition to the original Cairngen 1.0 release which was published last week.

Below is a list of new features available in Cairngen 1.2:

• Complete support for Cairngorm 2.0

• Complete support for Cairngorm 2.1

• Complete support for Cairngorm 2.2

• Added logging capabilities for all targets

• Abstracted user / project specific properties. User properties are now located in the project.properties file.

If you are using Flex builder as an Eclipse plugin, follow these steps to set up automatic project refreshes when using Cairngen: Select Run > External Tools > External Tools; select the build file then select the refresh tab and check the “refresh resources upon completion” checkbox. This will force a refresh everytime classes are generated to your project from Cairngen.

Download Cairngen 1.2

It has been awhile since I released Cairngen to the Flex community as an open source project. Cairngen, a one-shot code generation tool for Adobe Cairngorm was a tool I created to save time and rid myself of redundant copy / paste work I often found myself dealing with while developing with Cairngorm.

I have since realized that using Cairngen as a solution simply involved to much effort as developers were required to install Apache, PHP and AMFPHP as well as start the application server and run the Cairngen.swf every time there was a need to generate classes for a project built on Cairngorm. This complexity seemed out of sync with the simplicity which Cairngorm provides.

Cairngorm, as you may know, is a micro-architecture which provides a consistent architectural solution for developing mid to large scale applications with Adobe Flex. If you read my blog you will know that I am a huge advocate of Adobe Cairngorm and believe it to be the most effective way to build scalable Flex applications. The beauty of Cairngorm is in it’s simplicity – yes simplicity. Despite certain opinions, in my experience I have found that once you fully understand Cairngorm you begin to realize just how simple it really is. Eventually you no longer have to give any thought as to how to go about building an application in Flex, you get to a point where all you ever need to think about is what is most important to your application – business logic and display logic. Cairngorm takes care of all of the plumbing, but more importantly, Cairngorm trains you to think consistently when building applications. It is through this simplicity which Cairngorm provides that I realized how ineffective the original version of Cairngen was. But like I said, my original intension was to share it with the community “as is”, if it helps great, if it’s to much effort, then don’t use it.

There has also been many other useful tools that are similar to Cairngen which provide various solutions as well. I had mentioned in a previous post that part of my intension when releasing Cairngen was that someone with enough time available would build a proper eclipse plug in, which I think we all can agree would be the ideal solution.

With that being said, I still have been facing the same dilemma – I need the ability to create Cairngorm project directories, Events, Commands Delegates and so forth with minimal effort, in any environment, and have as much configurability as possible. My solution? ANT! I don’t know why I didn’t think of this originally as it makes perfect sense for many different reasons. Best of all it only took me about an hour or so to develop.

Cairngen 1.0
Cairngen 1.0 is built entirely in Ant and provides a solution for one-shot code generation of Adobe Cairngorm 2.2 classes. You can get started with Cairngen 1.0 simply by extracting the cairngen folder to the root of your Flex project and modifying the config.properties file to reflect your environment and project. If you are familiar with ANT, this will be very straight forward and you should be up and running in no time at all. Cairngen 1.0 is completely configurable. Developers can modify the Cairngorm templates, config.properties file and build.xml document as needed to suite their particular needs. Users can view code generation in real time via the console in Flex builder.
Cairngen 1.0 contains a default target which will create the typical Cairngorm project structure as follows:

business
commands
control
events
model
view
vo

Cairngen 1.0 will create a stub class for the applications ModelLocator, FrontController and Service.mxml for Cairngorm 2.2.

I have also retained the notion of a “Sequence” in order to identify the relationship between an Event, Command and Business Delegate. The Cairngen build.xml contains two targets for creating Sequences. In addition, developers can create Value Objects as well.

Targets
Below is a description of all targets available in Cairngen 1.0 build.xml:

main: cleans the project structure and generates project directories, the Cairngorm folder structure and default Cairngorm classes. Executes in approximately 750 milliseconds.

clean: deletes Cairngorm project directories and creates Cairngorm project directories. Executes in approximately 450 milliseconds.

delete-cairngorm-directories: deletes previously created Cairngorm project directories. Executes in approximately 380 milliseconds.

create-cairngorm-directories: creates Cairngorm project directories. Executes in approximately 385 milliseconds.

create-model-locator: creates the applications ModelLocator. Executes in approximately 450 milliseconds.

create-front-controller: creates the applications FrontController. Executes in approximately 450 milliseconds.

create-services: creates the applications ServiceLocator. Executes in approximately 450 milliseconds.

create-sequence-include-delegate: creates an Event – Command – Delegate sequence. Executes in approximately 482 milliseconds.

create-sequence-exclude-delegate: creates an Event – Command sequence, in which the Command will not implement mx.rpc.IResponder. Executes in approximately 460 milliseconds.

create-value-object: creates a typical Cairngorm value object. Executes in approximately 400 milliseconds.

Usage
To use Cairngen follow these simple steps:

1. Download Cairngen 1.0.
2. Extract Cairngen to your Flex project directory and refresh.
3. Open the config.properties file and modify accordingly to reflect your projects environment.
4. Right + Click the build.xml file and select Run as > Ant build. This will run the default target which generates the com.domain.project directories as well as the default Cairngorm folders, ModelLocator, ServiceLocator and FrontController. Ideally, if you are using Eclipse select Window > Show View > Other > Ant, select Ant and click OK. In the Ant panel select the “Add Buildfiles” icon (first icon on left). Select Cairngen > build.xml. Expand and you will see all tasks. double click main.
5. To create sequences, edit the sequence property in the config.properties file (this is the name of the event, command and delegate) and run either of the sequence targets, make sure to refresh your project in order to see the generated files.
6. To create a ValueObject edit the vo.name property and double click the create-value-object target. Refresh your project in order to see the generated files.

All Cairngorm-stub classes can be modified as needed. The template files are located in the templates/cairngorm2.2 directory.

I have a small amount of re-factoring which I plan to complete within the next few days, at which point I will post an update of the source. In the interim, there is enough to get you started. I welcome your thoughts and ideas in regards to making Cairngen a better tool while we await a release of an Eclipse plugin for Cairngorm. If you wish to contribute to Cairngen feel free to contact me.
Cairngen is released under the MIT license.

Download Cairngen 1.0

After a long beta release Adobe has finally released Cairngorm 2.2, which is now available on labs.

Though only a dot release, there are some pretty significant changes which are worth mentioning; specifically the distributed binaries. For instance, Flex Data Services has a dependency on fds.swc, which is shipped with the standard Flex Framework. In order for Cairngorm ServiceLocator to contain a reference to mx.data.DataService, the fds.swc needed to be included in the Cairngorm.swc. This resulted in increased file size as all Cairngorm classes were bundled in the same swc. regardless if you needed FDS or not. Adobe has resolved this by externalizing all FDS specific dependencies to the new Cairngorm Enterprise edition.

Another major improvement is the additional dispatch() method which has been added to CairngormEvent. The dispatch method allows developers to instantiate an CairngormEvent instance and dispatch the event via the instance. In other words, the event instance can dispatch itself into the event flow without a need to invoke CairngormEventDispatcher directly. This is similar to my IViewNotifierEvent solution which is an adaptation of the Stanglware solution which was developed by my former co-worker Fred Stangl.

The ability to remove Commands from the FrontController registry at runtime is of great value. I was actually in the process of developing an API to do just that.

The WebService bug has been fixed which is also a big plus as it caused great confusion initially.

Listeners for Event / Commands now have weak references in the base FrontController, this was also an issue in Cairngorm 2.0 and 2.1 that we were struggling with as objects still had references long after they were no longer being referenced and therefore would not get picked up by GC.

I have been using Cairngorm 2.2 beta for the past few months and have found it to be a big improvement over Cairngorm 2.1 and 2.0. Below I have listed the major changes in Cairngorm 2.2 contrasted with Cairngorm 2.1 and 2.0.

Changes between Cairngorm 2.1 and Cairngorm 2.2

• Removed dependency on Flex Data Services (fds.swc)
• Flex SDK SWCs are no longer linked into Cairngorm.swc
• Added support for setting remote credentials
• Fixed bug with Web services not loading the WSDL
• ModelLocator interface deprecated in favor of IModelLocator
• Added deprecation metadata for compiler support
• Added dispatch() helper method to CairngormEvent
• Commands now added to Controller with weak references
• Added removeCommand to FrontController
• made commands protected in FrontController

Changes between Cairngorm 2.0 and Cairngorm 2.1

• Responder has been deprecated. Use mx.rpc.IResponder
• Command deprecated in favor ICommand
• ValueObject deprecated in favor of IValueObject
• ServiceLocator getService() deprecated in favor getRemoteObject()
• ServiceLocator.getInvokerService() has been deprecated.
• IServiceLocator interface has been created to support unit testing
• ServiceLocator has security methods added
• FrontControler.executeCommand() and getCommand() now protected
• Error messages have been internationalized

If you are not currently leveraging Adobe Cairngorm to build scalable Flex RIAs I highly suggest you begin to explore the solutions which Cairngorm provides. I am a huge advocate of Cairngorm and strongly support Cairngorm as an architectural solution for building Enterprise class RIAs with Adobe Flex.

If you are interested in developing with Cairngorm, but are having trouble getting started, please feel free to contact me directly and I will be happy to walk you through Cairngorm and help get you started.

Download Adobe Cairngorm 2.2