As I mentioned in the last post, one of the coolest things in Swiz 1.0 is support for custom metadata processors. In actuality, this feature emerged somewhat organically as we discussed the 1.0 architecture and how we wanted to implement metadata processing. We quickly realized that exposing the system used to implement Autowire and Mediate (VirtualBean came later) would make for an incredibly powerful extension mechanism. The backbone of these processors is the metadata focused reflection API that was implemented. This post aims to explain the reflection API in order to facilitate an understanding of the topic and, by extension, how to implement custom metadata processors.
Reflection classes
The org.swizframework.reflection package contains, not surprisingly, the classes used in the reflection API.
The core concept in the reflection API is that of a metadata host. A metadata host is anything that has been decorated with metadata, whether it be a class, property or method. The related classes and interfaces are as follows, with IMetadataHost being the primary interface involved.
There are also classes to represent the metadata tags themselves, and the arguments they can contain.
A fully reflected representation of a class is stored as an instance of TypeDescriptor, and those instances are tracked in TypeCache to prevent reflection of any single type more than once. A solid understanding of this system will go a long way in making the authoring of custom metadata processors easier for you.
Custom Metadata Processors
I'm not going to cover all of the classes in org.swizframework.processors in this post but I would encourage you to do so before going too far into custom processor development. (If you would like to see another post going into more depth around these classes let us know in the comments.) To understand the basics simply look at the example below, taken from the posted demo apps (Flex 3, AS3) with some additional comments added.
Registering your processors
You then simply register your custom processors with Swiz, which looks like the following in Flex and AS3, respectively.
Keep your metadata!!!
This is essential! You need to instruct mxmlc to retain any custom metadata tags you are interested in, because by default it will not include anything but its built in tags like [Bindable]. You do this by adding a compiler argument to your project that looks like -keep-as3-metadata+=Random,Clock. Note the +=, rather than a plain old equals. Without the plus mxmlc will discard [Bindable] and friends, and you will be sad.
Conclusion
That's it! That is all there is to implementing custom metadata processing in Swiz 1.0. This is obviously a very simple example, but hopefully you can see the potential here. There is a slightly more involved example called ClockProcessor that creates a timer and updates the decorated property with the current time every second, but even that is just scratching the surface of what is possible. We hope to see a robust library of Swiz extensions start to emerge from the community over time in the form of custom metadata processors. Things like [TwitterTimeline], [AmazonWishlist] and others are just some of the ideas we've had during development, and we can't wait to see what others build. As always, head on over to the mailing list with any questions, comments, concerns or code samples! Enjoy!