Class Annotations in Flex

Class annotations, also known as metadata in Flex, are extremely valuable as they allow developers to provide additional information about classes, properties and methods which may not be appropriate to convey through implementation details such as Marker interfaces or some other means. An annotation can be viewed as a comment of sorts that provides a facility which can be utilized to convey the intent of a class, property or method, however unlike comments annotations are compiled into byte code with the class, thus allowing inspection at runtime via object introspection / reflection. Annotations do not directly affect code semantics themselves, however they can be inspected at runtime which in turn may affect the semantics of the running application.

Annotations are also very useful for providing pre-compiler instructions for generating boilerplate code. Although custom annotations can not be used in this way directly in Flex, this usage can be found throughout the Flex Framework. A perfect example of how the Flex framework uses annotations to generate boiler plate code is the [Bindable] meta-data tag, which itself is an annotation as are all meta-data tags in Flex. When a class or property is defined as [Bindable] the pre-compiler in turn reads this attribute and generates the code which facilitates actual data binding; i.e. PropertyChangeEvent, IEventDispatcher etc.

In order to use custom annotations in Flex you first need to instruct the compiler to keep Actionscript 3 metadata. This is achieved by using the keep-as3-metadata compiler argument. An example of setting two custom metadata attributes named “Foo” and “Bar” in the Flex IDE under project > compiler options is as follows.

Additionally annotations can be specified in a flex configuration file as follows:

When you create custom metadata in Actionscript you do so by first declaring the name of the annotation followed by arbitrary properties specified as name/value pairs. For example, you are most likely familiar with the [Event] metadata tag in Flex. The name of the annotation is “Event” and the valid properties for the annotation are “name” and “type”, as can be seen below:

Likewise you create your own custom metadata following the same format. The example which follows defines a custom metadata attribute utilized for annotating a class with version information. The name of the annotation is “Version”, which contains three properties; major, minor and revision.

Accessing custom annotations in Flex is accomplished via the flash.utils reflection APIs; describeType, getQualifiedClassName and getDefinitionByName.

To help simplify the process of accessing custom annotations in Flex I have developed a simple API: MetadataUtils which is an all static class that provides utility operations from which class annotations can be located and inspected, and Metadata which provides a strongly typed implementation of a metadata entry.

As you begin experimenting with your own custom annotations you will quickly find that there are numerous applications where they can be utilized, the most significant of which (IMHO) is to help facilitate IoC / DI solutions. It would be great if at some point Adobe would provide an APT implementation for mxmlc as part of a future release of Flex.

{ 2 comments ... add another one! }

  1. Thanks – very nice :-)

  2. Very nice. This is really going to come in handy for a typed JSON decoder. I can just read the ArrayElementType annotated on an array property.

{ 0 Pingbacks/Trackbacks }