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.
- IMetadataHost
- BaseMetadataHost
- MetadataHostClass
- MetadataHostMethod
- MetadataHostProperty
- MethodParameter
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!
{ 5 } Comments
Thanks for this Ben. Being a Java programmer and now working with Flex I know what the addition of annotations (custom metadata tags) to Java5 did for the Java community. I expect this new addition to Flex to accomplish the same level additional functionality for the Flex community. This starts a whole new ballgame!
Great stuff but TypeDescriptor seems to be buggy! If a method called toString() has any metadata, metadataHosts[metadataHostName] will fail (line 98). I made an ugly workaround:
if (metadataHostName == “toString”) {
return new MetadataHostFactory().getMetadataHost( hostNode );
}
Hi Florent,
I assume you are using Flex 4? Shortly after this post we discovered that Flex 4 adds metadata to every property and method of every class when compiling debug builds. We have updated the code on GitHub to ignore that metadata (by ignoring any metadata tags that start with an underscore) to fix this problem. We have not released a new build yet, but if you pull the code down yourself you should see the errors go away.
Thanks,
Ben
I am testing this but not having any luck.
Hi Sharedtut,
Please use the list at http://groups.google.com/group/swiz-framework for implementation help. Be aware though, you will have to provide more information than you have here in order to be helped. Providing sample code is usually the best way for us to figure out where you might be getting tripped up.
Thanks,
Ben
{ 1 } Trackback
[...] is the ability to create custom metadata processors. To get more familiar with the idea, check this docs page. Note that some items from the docs has changed, such as you no longer extend MetadataProcessor, [...]
Post a Comment