When you put a readme file into a folder that file is formatted and presented nicely through GitHub’s file browser. For example:

https://github.com/visionmedia/uikit

Scrolling down a little we can see a nicely formatted readme file.

GitHub strongly recommends adding a readme file to the root of your repository, but what I didn’t realise until recently was that it works for any folder in your repo. GitHub already has the best online file browser out there, but this specific feature can turn your source tree into your documentation.

For Robotlegs 2 I decided to try it out:

Async
MessageDispatcher
Extensions

Almost every package in the entire repo has a readme file. The best way to learn about Robotlegs 2 is to browse the source and readme files on GitHub.

Timing

To extend any framework you need to be able to hook into that framework’s initialization process.

That Damned Context

The Robotlegs 1 context class was, to be frank, rubbish – it set defaults, configured dependencies and controlled initialization. Worse, to hook into the initialization process or change the defaults, users had to extend the class itself resulting in the proliferation of funny looking words like SignalDrivenCovariantlyMediatedModularShellContext.

How Could You Let That Happen?

Extending the context was a silly idea – and I knew it at the time. It made me sad, deep down inside, but I knew that if I waited for a better solution to emerge the framework might never ship.

Also, my goals for Robotlegs 1 were:

1. Make it small
2. Make it fast
3. Release it

A ton of compromises were made to keep the number of classes down to an absolute minimum. That’s not how I usually write code. Besides…

Small Only Goes So Far

I always start by doing the simplest thing possible – it’s a good way to feel out a problem space. “What am I trying to do?”. The “how” doesn’t matter yet, but becomes important much later when I ask “How would I like to do this?”.

When writing actual code, however, I’m constantly faced with this annoying question: “Should I break this out?”. When doing the simplest thing possible I often decide against extraction: I’ve got a specific task to complete (like getting a test to pass) and I can refactor later if the idea proves itself to be worthwhile. Also, I know that extraction inevitably leads to a new set of design decisions. And I’ll have to start with a test – for something whose purpose I am only just discovering. And it ups the class count.

Keeping class count down for it’s own sake is almost always a bad idea. However, I don’t think Robotlegs 1 would have experienced the same adoption if it had had hundreds of classes instead of the quite digestible 15 presently in its belly. OK, 24 total if you add the interfaces.

When browsing open source libraries I get happy feelings from projects with a limited number of source files – it gives me a sense that if I really wanted to I could read through the entire codebase and understand it.

But there’s a point where that simplicity inverts. Profit becomes debt. Without good abstractions in place every participant in the system ends up doing too much. At that point the question becomes: “Do I need to introduce a new layer of abstraction?”.

Now You Have Two Problems

The introduction of a system wide abstraction layer fueled by a mid feature code extraction will do one of two things: it will strengthen the system or it will weaken it. A bad abstraction might solve the immediate design issues (like duplication) just fine but end up adding complexity and reducing quality overall.

Extensions? Timing?

So anyway, I want Robotlegs to be extensible in a sensible way. Users should be able to install custom extensions easily. Those extensions need a way to hook into the context initialization process:

Some extensions may need to be configured before others. Some may need to pause the initialization process and wait for a resource to become available. Some might directly depend on others and may need to wait for those extensions to be fully configured before self initializing. Some may only come to life after the entire context has been initialized.

It’s clear that the initialization process needs to be asynchronous. But without a good abstraction in place for dealing with asynchronous processing the context will be burdened with co-ordinating a complex series of events. Event soup is not delicious.

Events, Signals, Tokens, Tasks, Promises, Futures, Callbacks

There are a number of patterns for dealing with asynchronous processes. They have wildly different properties.

Some are low level, like the callback pattern. Some are high level, like the promise pattern. Some are guaranteed to be asynchronous, while others have the potential to be synchronous. Some are only good for observing. Some can be terminated, while others can be suspended and resumed. Some can be composed and chained. Some necessitate the instantiation of throw-away objects and put stress on the garbage collector. Some put stress on the stack.

Take Your Pick

I wanted something fairly low level that enabled asynchronous processing without adding unnecessary overhead in the cases where things could be synchronous (or skipped entirely).

I tried a number of things. For the most part: floppy, verbose and annoying implementations that moved the core problems around in less-than-useful ways.

Dispatch

Slowly it dawned on me. In this case all I wanted was an asynchronous message dispatcher. With a well defined set of callback conventions I could write something resembling an Event Dispatcher but without the overhead of creating throw-away objects (events) and with the ability to suspend and resume the dispatch when desired:

Some Async Conventions

The Message Dispatcher

Initialization, Extension, Please Continue

Very well. Suppose that context initialization comprises 3 steps: preInitialize, selfInitialize and postInitialize. When told to initialize the context moves through those steps in sequence. Anyone can listen in and halt the process as required at any point. What we end up with is in essence just a simple state machine where the observers have the potential to be guards.

The End

Well, that’s where the re-write started anyway.

Robotlegs 2

p.s. I dropped a bunch of stuff from the version2 branch. I’ll be going back to pull out any functionality that might have been lost shortly. If you come across anything that’s missing feel free to adapt it to the new codebase and send a pull request. Or drop an issue on the tracker. For quick reference, here’s the old version2 branch: version2-old

http://oreilly.com/catalog/0636920021216

Written by the amazing @stray_and_ruby and @jhooks

Some things that these framework experiments will probably have in common:

Support for the Mediator pattern
Support for the Command pattern
Display-list processing (auto-wire)
Dependency Injection through Swiftsuspenders

The first of these is Boiler by Rasheed Abdul-Aziz (@squeedee): http://devblog.vworkapp.com/post/8538689880/r

Please have a look and give Squeedee some feedback. Some things that I like: convention over configuration, avoiding inheritance, the name!

Injection Everywhere

Automated Dependency Injection is a handy way to wire the component parts of a system together. But systems are comprised of components at varying levels of abstraction. Some are high-level, domain specific abstractions, whilst others are low-level implementation details.

If every object in a system is given the same level of importance, thrown into a DI container, and made available to every other object, the layers of abstraction become very hard to see. The container becomes a mixed bag of configuration details, value objects, sub-systems and goodness-knows-what-else.

Does a URL (a very specific, low-level configuration detail) really deserve to be sitting in a flat container right alongside a high-level, domain specific model? Certainly not!

It can be difficult to determine what is and what isn’t appropriate for automated Dependency Injection. It depends on the system you are building, and is something that comes with time and experience. I’m certainly still struggling with it on a daily basis.

Here’s a related post on the matter:

http://www.higherorderlogic.com/blog/2011/07/30/is-dependency-injection-like-facebook/

Interfaces Everywhere

Program to interfaces, not implementations. Interfaces decouple us from implementations, they are good, but, as always, there are some subtleties worth considering.

Many languages support explicit interfaces: contracts with absolutely no implementation details. But every object also has an implicit interface – the public methods and properties exposed by that object.

Creating an explicit interface for an object that will only ever have a single implementation is a violation of the DRY principle as the explicit interface duplicates the implicit one.

This happens most often when the interface is large and acts as a “stand-in” describing a class rather than a piece of behaviour. Sure, you *could* swap out the implementation at some point, but honestly, so much of the implementation has already leaked out into the interface that there is very little point in doing so.

Program to interfaces, but remember that sometimes a small implicit interface is better than a large explicit one.

Another related post:

http://lostechies.com/derickbailey/2008/10/20/dependency-inversion-abstraction-does-not-mean-interface/

We decided to keep the initial meetup small and focused, but development of the framework itself is completely open and anyone is free to contribute once we’ve nailed down some core priorities.

More info over on the Robotlegs forums:

http://knowledge.robotlegs.org/discussions/feedback/20-robotlegs-20-how-to-get-involved

Moreover they can all perform automatic DI by parsing class metadata. It would be grand if the common DI related metadata tags could be standardised. That way we really could write code that is decoupled from any particular framework.

I’ve started a little document over at GitHub:

http://github.com/darscan/AS3-DI-Metadata

I don’t know the libraries well enough to fill in all the details, so if you could fork the repo and edit the doc that would be great! Also, the format/layout could be better, so if you have any ideas on that front.. edit away.

robotlegs/robotlegs-framework/blob/master/src/org/robotlegs/core/IContextProvider.as#L16

Don’t do that you naughty sausage! Your codebase will evolve (if all goes well), and line 16 will be replaced by a newer, shinier string of characters. Or, in this case, it’ll point to something that no longer exists.

This, on the other hand, is more likely to stick around to haunt its author (me):

robotlegs/robotlegs-framework/blob/v1.1.2/src/org/robotlegs/core/IContextProvider.as#L16

Select a tag before you link to your fancy code (“Switch Tags” under GitHub‘s “Source” menu).

Automatic Mediation

In order to determine the scope of a view component, Robotlegs listens to the contextView for bubbling capture-phase ADDED_TO_STAGE events:

MediatorMap.as#L233
MediatorMap.as#L260

Every display object that lands on the stage inside the contextView is checked against a mapping dictionary. This can be quite expensive for complex display object hierarchies where there is a lot of re-parenting. It’s also the only option available if you want to keep your view components completely framework-unaware. If, however, you’re prepared to modify your components slightly (it’s a one-liner) then you can try out this utility:

http://github.com/eidiot/robotlegs-utilities-LazyMediator

Instead of listening for ADDED_TO_STAGE events emitted by every component, we listen only for custom events dispatched by view components that explicitly require mediation.

Note: This utility currently only supports the MediatorMap and needs to be expanded to support the ViewMap. Fork and improve!

Default Injection Points

The actors in the MVCS package have a number of pre-configured injection points (dependencies). When you extend mvcs.Command all you are really doing is inheriting some dependencies:

mvcs/Command.as#L23

Whilst handy, it is quite seldom that we actually use all of those in a given Command.

A much cleaner, and ever-so-slightly cheaper approach is to declare only the dependencies that you actually need. Instead of extending Actor or Command (this doesn’t work so well for the Mediator class), just create a vanilla class and declare your dependencies manually:

public class MyCommand
{
	[Inject]
	public var injector:IInjector;

	public function execute():void
	{
		injector.mapClass( Vehicle, Car );
	}
}

Remember, the Robotlegs apparatus is already mapped for you if you need anything:

mvcs/Context.as#L190

Notice that the IEventMap is not mapped as a value or singleton – you’ll get a new IEventMap instance whenever you ask for one.

That’s it for now!

A huge big “Thank You” to everyone involved. Let the “utility building” begin!

Robotlegs is an automated dependency injection framework for Flash, Flex and AIR.