flex2-custom-metadata

Flex2 has a pretty cool metadata construct that can be a huge feature for development - especially for certain types of tools and common objects. Mark at work put together a clever and very effective XMLNode-to-Typed-Class conversion tool using this technique and I thought I would share some of the bumps encountered to help anyone else with a similar task.

Here is a quick and to the point example. Using your own metadata requires Flex 2.0.1 as a required argument to mxmlc wasn’t added until that version. For this small example, lets say we wanted to use a [Transient] metadata tag to mark properties of a value object as client-side only to let some sort of imaginary persistence manager know that property should not be written to a database. You could use the same technique to specify types for objects in a collection (though this can be done with the specialized [ArrayElementType] tag), to specify types for both keys and values in a map structure, or any number of other scenarios.

With this example, you could have a value object that looks like this:


-----
public class ContactVO{
    [Transient]
    public var fullName: String = “John Doe”;

    // more properties and methods follow
}
—–


Now you can write code that can read this metadata information from these ContactVO objects at run time. Here is a drawn out and hardcoded example of doing this. You basically just use Flex2’s describeType method to obtain an XML description of an object and then use e4x to query that information.


-----
var contact:ContactVO = new ContactVO();

// get the E4X XML object description
var typeInfo:XML = describeType(contact);

// get the property we marked up with metadata
var fullNameInfo:XMLList = typeInfo..accessor.(@name == “fullName”);

// check for the [Transient] tag
if (fullNameInfo..metadata.(@name == “Transient”).length() > 0){
    // do something - maybe exclude it from a commit list
}
—–


Metadata tags can have properties too. Lets say you want to mark up a map structure so that you can determine the type of both the keys and values at run time. Flex2 doesn’t provide a convenient hashmap-ish class by default, so just assume you’ve made one.


-----
public class ContactVO{
    [HashMap(keyType="String", valueType="String")]
    public var phoneNumbers: MyHashMap = new MyHashMap();

    // more properties and methods follow
}
—–


You can access the metadata properties like this.


-----
var contact:ContactVO = new ContactVO();

// get the E4X XML object description
var typeInfo:XML = describeType(contact);

// get the phoneNumbers property we marked up with metadata
var phoneDesc:XMLList = typeInfo..accessor.(@name == “phoneNumbers”);

// grab the “HashMap” metadata description
var phoneMetaData:XMLList =
phoneDesc..metadata.(@name == “HashMap”);

// grab the “keyType” property from the “HashMap” metadata
var metaDataDesc:XMLList = phoneMetaData..arg.(@key == “keyType”);

// finally, grab the value of this “keyType” argument
var typeValue:String = metaDataDesc.@value;

Alert.show(”This HashMap has keys of type: ” + typeValue);
—–


To use your own metadata tag like this, you will need to use a custom argument when building your swfs. For the transient example above it would look like -keep-as3-metadata+=Transient. You can repeat this for as many custom metadata tags as you like. If you are building with Flex Builder, you can add this to the compiler arguments under Project -> Properties -> Flex Compiler. The problem we found was that Flex Builder ignores this entirely unless you are building a DEBUG swf. This was a enourmous headache and I still don’t know how to make Flex Builder use the additional arguments in both DEBUG and RUN mode. Only having DEBUG buildable through Flex Builder is fine for development but certainly not for production. The workaround available now is to use ANT (see my earlier post for an example of setting this up).

Hope someone else finds this helpful. The metadata construct available in Flex2 is quite powerful, you can use it to build tools and libraries that use annotations similar in some ways to those of Java 1.5.