Swiz RC1 Release Zip (contains SWC, source and ASDocs)
RC1 Release Notes
Swiz RC1 tag on GitHub

You may have noticed the download link is pointing to a JIRA instance. Well, that is because Swiz has a new home, including a Confluence wiki and a JIRA bug tracker! We are still ironing out the details around community access to the bug tracker but intend for it to be as open as possible. You will also notice that the wiki shell is in place but some bare spots remain. We’re working hard to fill out the content as soon as possible.

With that said, go forth and enjoy! Use it, beat on it, report bugs in JIRA and hit up the mailing list with questions or comments!

Update: Because I am a bone head, and I was running low on time, there were some potential problems with the initial SWC. The two files below *actually* support pop up injection, and the one whose name implies as much is compiled with the Flex SDK set to external. If you are using Flex I would recommend that one, so you can choose which SDK to build against. If you are using pure AS3 you will need to use the one with the SDK included, as we have not yet completely separated the logging from the Flex framework. Sorry for any inconvenience.

v1.0.0-beta-patched-externalSDK
v1.0.0-beta-patched

Changes and additions in Swiz 1.0.0 Beta:

• SwizConfig
  • SwizConfig is back and better than ever
  • injectionEvent, injectionEventPhase and injectionEventPriority fully customizes the listener that triggers inspection of your views
  • injectionMarkerFunction allows you to specify a decision maker function that determines if a view should be inspected and processed. Easily checked for property existence, interface implementation or any other custom criteria.
  • eventPackages and viewPackages support for .* – we’ve seen people get tripped up by specifying packages with a trailing *, so we added support for it
  • loggingTargets to see what Swiz is doing behind the scenes
• Parent and child Swiz relationships
  • Swiz instances declared on IEventDispatcher instances that are descendents of another Swiz dispatcher become child instances
  • Child instances can use beans declared in parent instances
  • Child instances inherit eventPackages and viewPackages from their parent
  • Parent instances can mediate events dispatched from child instance
• ISwizInterfaces
  • ISwizInterface is the parent interface for a few interfaces beans can implement to have Swiz give them special treatment. Interfaces are fulfilled after all metadata has been processed. The interfaces are as follows:
  • ISwizAware – Implementers will be provided with a reference to their containing Swiz instance.
  • IBeanFactoryAware – Implementers will be provided with a reference to the BeanFactory for their containing Swiz instance.
  • IDispatcherAware – Implementers will be provided with a reference to the event dispatcher used by their containing Swiz instance. Useful for non-display list beans that need to dispatch system events.
  • IInitializing – Implementers will have their init() method called.
• Service utils
  • Consistent with our principle of never making you extend Swiz classes, we’ve moved the functionality previously provided by AbstractController into their own utility classes.
  • executeServiceCall() is now provided by ServiceRequestUtil
  • executeURLRequest() is now provided by URLRequestUtil
  • You can instantiate these classes directly, but the recommended practice is to define them as beans and inject them by type.
  • AbstractController still provides these methods in order to ease migration pains. Convert to the utilities when you’re ready.
• Generic chaining support
  • We have added a fantastic, robust and extensible chaining infrastructure to the framework.
  • Event chains and command chains available “out of the box”
  • Create custom chain types by extending a base class and overriding a single method
• Processor priorities
  • Metadata processor execution is now ordered using a priority property
  • Configure your custom processors to run at any position in the list of default processors
• Ignore metadata starting with _
  • Thanks to some new metadata generated by Flex 4 debug builds, we ignore all metadata tags starting with an underscore
• Support for multiple Mediate tags
  • You can now pile on as many [Mediate] tags as you want to a method, and it will be called in response to all the specified events
• Support for [Mediate( "MyEvent.*" )] syntax
  • To facilitate easy support for front controllers and the command pattern, specify that you want a method to be called in response to all event types matching public static constant values on a given class
  • Currently in raw form, will be refined in future versions
• Support for properties on dynamic events
  • We’ve corrected the logic that runs in response to tags like [Mediate( event="MyEvent.FOO", properties="username, password" )] to allow the use of dynamic event classes
• Storage beans
  • SharedObjectBean and EncryptedLocalStorageBean added to simplify usage of this type of functionality
• [VirtualBean] has been renamed [Outject]
  • Same functionality, new name
• Initialization changes
  • We completely revamped the way Swiz initializes and processes beans
  • Prototype is now correctly implemented offering deferred instantiation and (by default) a fresh copy to each request for its type/name
  • Each bean is fully initialized and processed before being handed back to whoever requested it, providing full support for proper cascading
• [Inject] is the new [Autowire]
  • [Autowire] is still supported, and will continue to be for the foreseeable future, but it has officially been deprecated
  • If you are listening to Swiz’s logging, you will get a warning for each [Autowire] tag instance
  • Injections are now considered required by default. If a dependency is optional, use the following format [Inject( required="false" )]
• Metadata processors API updated
  • Processors that deal with one tag at a time can simply extend BaseMetadataProcessor and override the public function setUpMetadataTag( metadataTag:IMetadataTag, bean:Bean ):void
  • Processors that need to process groups of tags for purposes of ordering or coordination may override public function setUpMetadataTags( metadataTags:Array, bean:Bean ):void
  • Corresponding tearDown methods are provided as well
  • If you prefer not to extend a Swiz class simply implement IMetadataProcessor
• Metadata processors can support multiple tag names
  • metadataNames specifies the tag names a processor will handle. This is how InjectProcessor handles both [Inject] and [Autowire]
• [PostConstruct]
  • We’ve added support for [PostConstruct], which can be used to decorate methods that will be run after all [Inject] tags have been processed.
  • Supports an order attribute for executing multiple methods in a specific sequence
• SwizLogger and loggingTargets
  • Swiz’s internal classes now use the static SwizLogger class to properly log output in a standardized way
  • The loggingTargets property of SwizConfig allows you to specify an array of ILoggingTarget instances, with full support for filtering, message customization, etc
  • Work in progress, logging has not yet been fully implemented across all Swiz classes. Swiz will be *very* chatty before everything is said and done.
• MockDelegateUtil
  • TestUtil has been renamed and reworked into MockDelegateUtil
  • Provides createMockResult( mockData:Object, delay:int = 10 ):AsyncToken and createMockFault( fault:Fault = null, delay:int = 10 ):AsyncToken methods
• AMFUtil
  • Useful for parsing stored AMF3 data, particularly helpful when combined with MockDelegateUtil to create a mock service layer
• Added FlexFormatter prefs to GitHub
• Pop up support
  • Pop up views can now be properly wired
• IBeanProvider.dispatcher implemented
  • BeanProvider and BeanLoader now include a dispatcher property (again) that is the IEventDispatcher used for “system events” in a Swiz instance.
  • Useful for providing non-view classes a way to dispatch events that will be heard by Swiz.
  • Same instance provided to implementers of IDispatcherAware
• Main dispatcher processed as bean
  • The main view/event dispatcher on which Swiz is defined can now be properly wired

Enjoy!

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.

• IMetadataTag
• BaseMetadataTag
• MetadataArg

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!

Swiz 1.0.0 alpha source code
Swiz 1.0.0 alpha example projects (SwizDemoApp & SwizDemoAppAS3)
Live Demo App – Flex 3
Live Demo App – AS3

(The examples are heavily commented so view the source!)

Swiz 1.0.0-alpha represents the current state of a clean slate rewrite of the Swiz Framework. While discussing and planning new features and refactorings a few months ago, we decided we’d rather start fresh. Accommodating things like modularity and pure AS3 projects, as well as some ideas we had in mind were more easily accomplished (and let’s face it, more fun to do) by starting with a blank slate and building only what was necessary, in the cleanest way possible That being said, this release definitely lives up to its alpha name, and will not allow you to simply drop the SWC into an existing Swiz project. (I mean you can, but nothing will work.) So let’s talk about some changes.

Quick disclaimer: I am *positive* there are features and/or changes I am forgetting to mention here. Generally speaking, if something is missing from the framework it most likely has just not been implemented in the new code base yet. Please direct all questions, concerns and suggestions to the mailing list.

Autowiring

Autowiring has been greatly improved. A good way to think about autowiring now is that it is similar to the <mx:Binding> tag in Flex. The bean attribute has been “renamed” to source, but bean will still work in order to ease migration. Eventually, you will start getting deprecation warnings if you use bean. We have also added support for default attributes, so [Autowire( "someModel" )] is equivalent to [Autowire( source="someModel" )].

destination

There is an optional destination attribute. The destination attribute allows you to create a class-level [Autowire] tag, and tell it where to assign the autowired value. We did this because it was pointed out that users were commonly creating public, bindable properties that served no purpose other than being an autowire destination and a binding source. You can use this format to do things like this:

Dot notation

As you may have noticed in the above sample, the source and destination attributes both support dot notation. This was a highly requested feature, and also vital to supporting the destination syntax. There is no limit to the number of levels you can drill down, but it should generally only be used as necessary. We have also removed support for the property attribute, since it is negated by the dot notation support.

Setter injection

Swiz now supports single argument setter injection as well. The only reason it is limited to single argument methods is that we would like to get community feedback before implementing further support. Should support be added for additional argument methods? Usage is as follows.

Planned future improvements

In addition to the twoWay and view attributes that exist today, we also plan to add two new attributes in coming releases. First is a bind attribute that, if set to false will cause Swiz to perform a one time value assignment with no bindings created. The default value is/will be true. Second will be a lazy attribute, which will also default to true. Now that Swiz is modular, one of the biggest remaining things to implement is inter-instance communication. We will be creating a system that allows Swiz instances to share and inherit beans, as well as some other potential communication mechanisms. The lazy attribute is related to that system in that, if set to false it will cause Swiz to throw an error if that particular dependency is not available when the tag is processed. The default behavior is that Swiz simply makes note of that unfulfilled dependency, and as new objects are added to the system they are checked against the missing dependencies. This allows you to define beans/dependencies in any order and not worry about precedence.

Custom metadata processors

This, in my opinion, is the coolest thing in Swiz 1.0.0. What we have done is to open up the exact mechanism Swiz uses to implement tags like [Autowire], [Mediate] and [VirtualBean] so that you can create and process your own custom metadata tags. There will need to be a future post dedicated to this topic and the reflection system it relies on, but for now be sure to check out the examples. There are two custom processors in the example apps that show how easy it is to create these powerful framework extensions. When creating your own though, don’t forget you have to add compiler args in order for mxmlc to retain your custom metadata tags.

VirtualBean

If you were paying attention in the previous paragraph you may have noticed mention of a new built in tag, [VirtualBean]. As I alluded to above, it is not ideal to reference bean properties in [Autowire] tags. Not only does it create a reliance on that specific object structure which will break if somebody changes it, it is also usually not appropriate for a view or other destination to have that implementation knowledge in the first place. Enter the VirtualBean tag. When placed on a public property of an existing bean it transforms that property into an “independent” bean of its own, removing the need for dot notation and the associated concerns that go along with it. If your view only needs a collection or two from your model there is no longer any reason to wire in the whole model or to include a property name reference in your [Autowire] tag. Usage is as follows.

Instantiation and configuration

Lastly, you will notice that instantiation and configuration of the framework look quite different in the demo apps. This is explained a bit in the comments of the apps but I will repeat it here: these aspects will likely change a bit before the final release. We have not yet implemented SwizConfig at all in this release, but that will be a part of the final release. Other minor details may change as well, but creating an instance of the framework will remain as dead simple as shown in these demos.

Check it out!

So that is it for now. Take a look at the heavily commented demo apps. Browse, download, clone and otherwise examine the framework code. We are eager to get your thoughts, feedback, submissions, patches etc. so don’t be shy! The team’s immediate tasks are to further clean up the code you see today and smother it in unit test coverage, so there is still time to influence the API! Give it a spin and tell us what you think!

Enjoy!