Eric Feminella

Introducing Cairngen: Adobe Cairngorm Code Generator

Overview:
A tell tail sign of a well designed architectural framework is in it’s ability to facilitate code generation. And Adobe Cairngorm does just that.

Cairngen is a tool in which I originally developed for myself in order to save time. I am sharing it with the Flex community as I believe that it is a very useful tool and it has saved me countless hours to date.

Cairngen is not intended to be all thing to all people, it is simply intended to speed up the development process. My hopes are that the Cairngorm team will take this idea and improve upon it by developing a proper Eclipse Plugin.

Cairngen is a code generator for Adobe Cairngorm which allows developers to easily and consistently generate Cairngorm project structures for Flex which consist of the standard Cairngorm folder structure, a default ModelLocator, Controller, and ServiceLocator. Cairngen also allows developers to generate Event, Command and Delegate classes.

Cairngen is a solution which removes the additional development time spent creating Cairngorm projects and classes and enforces consistency when developing a project with Adobe Cairngorm.

Cairngen was developed entirely in Flex 2 and PHP 5.2.0 utilizing AMFPHP via AMF3. Initial set up is easy and straightforward. You can run Cairngen from a browser instance inside of Flex Builder to quickly and easily generate Cairngorm classes. Cairngen will stub out all of your Cairngorm classes for you, all you ever have to do is implement them.

Cairngen uses the term ‘Sequence’ to describe the relationship between Event, Command and Business Delegate classes, and is not to be confused with a Cairngorm Sequence Command. In Cairngen you can quickly add a Sequence simply by naming the Sequence and clicking generate. You can then re-fresh your Flex Project and the classes will be stubbed out and ready for your specific implementation. In certain cases you may not need to add a delegate to your sequence in which case you can choose to exclude the delegate from being generated. Cairngen will then generate an Event and Command class for the sequence. The Command class will implement Cairngorm Command and not mx.rpc.IResponder. Cairngen will also handle casting events to the correct type in a Command as well as importing all associated classes.

As of this preview, Cairngen does not allow developers to overwrite existing files. This restriction is intentional in order to prevent developers from unintentionally overwriting files.

System requirements:
This informal documentation assumes that you are familiar with AMFPHP, Apache 2.0.59 and PHP 5.2.0. In this preview of Cairngen you must have amfphp installed on localhost as the Flex UI will need to resolve the AMFPHP gateway.php as follows: http://localhost/amfphp/gateway.php. In the final version 1.0 release this location will be configurable.

You will need to install Adobe Flex 2, PHP and AMFPHP on your local machine. To install PHP and Apache 5.5 in one quick and easy bundled windows installer use WAMP5. Run the WAMP5 installer and when completed, start the wamp5 service. Once PHP and AMFPHP are installed you will need to extract the Cairngen Alpha 1 PreRelease.zip to your local disc. Copy the services directory and paste it in the root of your amfphp directory. Then copy the cairngen-ui folder to your www root directory so as to reside in the same sandbox as the services directory.

Usage:
Once you have PHP and AMFPHP installed and running, you are ready to start using Cairngen. Open a browser and run the generator UI from http://localhost/cairngen-ui/Cairngen.html. You can launch cairngen.html as a browser instance in Eclipse as well.

To create a Cairngen Project:

1. Click begin
2. Name your Cairngen Project. This name is typically the same name as your Flex Project
3. Select the Adobe Cairngorm version you want to work with (In this pre-release only Cairngorm version 2.0 is available)
4. Select the location of your flex Project. (e.g; C:\workbench\EricFeminella\Cairngen)
5. Set the com directory for your project (e.g; com.domain.projectname)
6. Finally, verify that all locations and names are correct. If so click “Create Project”.
7. Refresh your Flex Project to view the default Cairngorm project structure, ModelLocator, Service and Controller classes

To create a Sequence:

1. Name the Sequence
2. Select Include delegate to add a Business Delegate, or Exclude Delegate if the sequence does not require a service
3. Click generate and refresh your Flex Project. The stubbed out classes are now ready to be implemented. You will need to add them to your Controller.

Editing template files:
You can modify the template files (.tpl) in order to reflect your particular implementation of Cairngorm; however, I strongly advise that you’re implementation is inline with Cairngorm best practices. The template files can be found in: amfphp\services\com\ericfeminella\cairngen\templates.

Updates:
In the final release of Cairngen the following additional requirements will be implemented:

1. Ability to specify any root directory in which to generate classes to. As of this pre release you are restricted to a single com.domain.project directory as the project root.
2. Read / write capabilities will update a Controller and add additional addCommand(); calls so that adding Event / Command mappings will be automated. As of this pre release you must add them manually.
3. Local persistence will enable you to open and work with existing Cairngen projects as well as add new ones. As of this pre-release you can only work with a session based Cairngen project.
4. Templates for Cairngorm 2.1. As of this pre-release only Cairngorm 2.0 is available. However, Cairngen will implement mx.rpc.IResponder for generated Command classes.
5. Proper folder browsing will be implemented. Unfortunately in this preview you must type or paste the location of a Flex Project manually.

Licensing:
Cairngen is an open source project protected under the MIT license.

I will begin to formally document Cairngen over the course of it’s development. In the meantime enjoy the extra time that you will gain from using Cairngen.
Feel free to post your comments and suggestions.

Download Cairngen Alpha 1 Preview

I recently had to write a component for an application which allows users to inspect an IP address in detail as well as validate the address against various different criteria. I couldn’t find an API which provides this type of functionality in any of the Adobe classes so I wrote my own. I figured someone else may need to do something similar at some point so I am publishing the API under the MIT License.

The IPV4 API allows detailed inspection of an IP version 4 address (IPv4). It provides a robust API which is not available from Adobe at the moment. Usage is simple and straight forward and contains methods which perform the following:

• Determine if the address specified is a valid IP address
• Determine the network class of the specified IP Address
• Determine the network octet of the specified IP Address
• Determine the host octet of the specified IP Address
• Determine if the IP Address is valid for Network assignment
• Determine if the IP Address is within the Class range specified
• Determine if the IP Address is a loopback address.

Below is a simple usage example which performs various operations on a specific IP Address:

The IPV4 inspector API can be used for inspecting and validating an IP Address. I plan on adding an update which contains methods for dealing with masks and prefix notation as well.

You can view the ASDoc as well as download the source swc

The inclusion of the Dictionary class in ActionScript 3 creates numerous possibilities when sub classing. The Dictionary class allows for creating key / value mappings or tables which are more commonly known as Hashes or Hash Maps. The only problem is that the Dictionary class does not provide an API for working with the map. The Dictionary class is a good starting point in which sub classes can create managed key / value hash maps and provide methods for retrieving values and keys as well as removing values, determining how many key / values exist and so on.

I am working on a project in which the data set is comprised of sentences tokenized into their individual parts of speech; noun, verb, preposition etc. Part of the requirement is that a lookup can be made on any individual part of speech to retrieve further information such as tense, plurality and so on. At first I simply used a Dictionary for the mappings but ended up adding all kinds of logic outside of the map whenever I needed to check for a key or add a value and so on. So I decided to write a simple HashMap class for AS3 which is similar to the HashMap available in java.util.HashMap.

Below is an example of how to use the HashMap class:

You can view the source for the HashMap class as well as the IMap interface which defines the methods necessary for working with the HashMap.