It has been awhile since the release of Cairngen 1.0, and the feedback I have received from the community has been very encouraging. I am happy to have provided a first-of-it’s-kind utility which allows developers to save time when building Flex applications on Adobe Cairngorm. Additionally, many of you have contacted me with some really cool new features that you have added, some of which are now available in this latest release.

Objective
The main objective of Cairngen 2.0 was to address 2 issues which were inherent to Cairngen 1.0. The first being that Event / Command mappings were not automated. In Cairngen 1.0 developers had the ability to generate sequences which consisted of an Event, Command and optional Business Delegate. And although this was very useful as it generated all of the required classes, handled upcasting events and instantiating Business Delegates, developers were still required to implement addCommand() in the FrontController manually. The second issue was that Event types were not generated as uppercase. Event types are static constants therefore they should always be uppercase. This is not required, however it is a best practice. Again developers could easily generate the required Event class but they would have to manually modify the event type to make it uppercase.

These two issues were the main thing preventing Cairngen from full circle code generation and implementation. Cairngen 2.0 addresses these 2 issues by automating the process, thus allowing for even faster development of Cairngorm projects.

So what’s new in Cairngen 2.0?

What’s next?
I don’t know, you tell me? If you have additional features you would like to see added to Cairngen, or if you have extended Cairngen to provide these features, feel free to leave a comment on this page. I am planning on adding some new features in the near future. One of which will be the ability to detect duplicate addCommands.

I would like to thank the many developers who have contributed to the development of Cairngen 2.0. I am in the process of compiling a list of contributors, at which point I will update the release notes.

Cairngen is licensed under the MIT License.

Ant and Ant-contrib are licensed under The Apache Software License

Download Cairngen 2.0

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