Annotating ActionScript Classes with Custom Metadata + Simple ORM Framework for AIR

A little known feature of Flex 3 is that you can annotate ActionScript classes with your own metadata. For example you could annotate a class as follows:

package
{
	[Bindable]
	[Table(name="contact")]
	public class Contact
	{
		[Id]
		[Column(name="contact_id")]
		public var contactId:int;

		[Column(name="first_name")]
		public var firstName:String;

		[Column(name="last_name")]
		public var lastName:String;
		public var address:String;
		public var city:String;
		public var state:String;
		public var zip:String;
		public var phone:String;
		public var email:String;
	}
}

In this example, [Bindable] is a standard Flex metadata annotation while Table, Id and Column are custom. The -keep-as3-metadata compiler flag allows you to instruct the compiler to keep your metadata in the generated SWF so that you can get to this information at runtime using the reflection API (describeType).

To set the compiler flag, right-click the AIR project name in FlexBuilder, select “Properties”, and “Flex Compiler”. For this example, I added -keep-as3-metadata+=Table,Id,Column to the “Additional compiler arguments”. Notice that it is important to use += and not =, otherwise standard metadata annotations (like [Bindable]) will not be available in the SWF.

Custom metadata annotations can be used for all sorts of interesting things . For my session at MAX this year, I used custom annotations to build a simple persistence framework for AIR.

Using this framework, you annotate your model classes to indicate the database table that should be used to persist instances of that class, the identity field in your class (which corresponds to the primary key of that table), and name mappings when the database column name is different from the class field name. That’s all you have to do to provide your AIR applications with automatic persistence to the embedded SQLite database. No SQL to write! The framework will even generate the table if it doesn’t already exists.

For example to add a new contact to your database, you’d simply do something like this:

var contact:Contact = new Contact();
contact.firstName = "Christophe";
contact.lastName = "Coenraets";
contact.email = "ccoenrae@adob.com";
entityManager.save(contact);

to modify the contact:

contact.firstName = “Chris”;
entityManager.save(contact);

to remove the contact:

entityManager.remove(contact);

You can provide the entityManager with instances of any annotated class and it will figure out how to persist the object (how to generate the appropriate SQL statements) based on your metadata annotations.

Disclaimer: This is a simplistic proof of concept and is by no means a production ready ORM solution. Some basic assumptions are made for simplicity. For example, I assume that all primary key are autoincremented integers.

You can download the sample application here. To test it, create an AIR project in FlexBuilder, copy the sample files in that project, and set the compiler options as described above.