Developer's Blog

No, let’s continue our discussion about principles, Cairngorm principles. As a general advice for studying somebody’s else code, you should always start with looking at the events. But first, let’s discuss the package names (which will be the same for your application skeleton) : business – contains service classes , commands - contains the application commands , control - contains the events , event dispatcher and the application controller , model - contains the application’s data, view - will get filled with GUI components , vo – will be filled with value objects for the business engine.

Let’s open the CairngormEvent.as to take a look inside : as I’ve said in the previous post, a CairngormEvent has the ability to dispatch itself – the public method dispatch calls for the CairngormEventDispatcher (which is Singleton) and do it – between us, doing so assures that the event in not a volatile object, eaten away by the Garbage Collection (I’ve seen some nasty bugs related to this). There is something even more interesting (for those of you who never thought that you can do so) in the CairngormEvent class – the public property data, which allows you to pass the reference to an object with the event – the data passed can be used by other listeners, but there is a catch : the listeners will have to know that object’s type.

So, we can make some corrections to this class, in order to make it more OOP principles compliant : first, we could add to the constructor another parameter (by default null) to declare the carried object. Secondly, we could use a setter getter for the data property – thus respecting the encapsulation. We can also define a cast property, making the data getter return data as cast (the lazy way to avoid writing every time this inside some other class).

Paying a visit to the CairngormEventDispatcher.as will bring to our attention the following : first, it is a Singleton which makes use of an instance of EventDispatcher (through it’s interface IEventDispatcher) which will do all the dispatcher work. You can notice that this class could declare it’s implementation to IEventDispatcher, since all the required methods are declared.

FrontController is the class which you will need to extend to create your application controller – it will basically associate an event to a command – when that event occurs (usually as a result as a user interaction with a GUI component) the associated command will get triggered – which will affect either the model, either will create a delegate which will make a service call and return the result to that command (which will modify the model, of course).

Using a Dictionary of commands, the FrontController doesn’t need to iterate through an array when it needs to execute that command. Adding a command (registering it) creates a dictionary entry with the name of the event associated with the reference to the command class which is associated to it – looking first for the uniqueness of that event name. I’m advising you to take a good look of this technique – you might find it very useful and applicable somewhere else, for example a large collection of value objects which has the constrain to identify unique objects very fast.

The above classes represents the main event engine behind Cairngorm – simple, yet very efficient.

The Command class will get extended for each and every command your application needs – as previously explained. As you saw inside the FrontController, every event will create a new instance of the associated command and a call to the execute method will be made. The SequenceCommand class will be extended when you need to execute a chain of commands as a consequence of a single event – which is pretty useful when your application needs to load or alter relational data.

There is not much to say at this moment about ModelLocator and its interface IModelLocator , because you will organize your application’s model after its needs – the most important principle is that the GUI elements will bind to the declared properties (and don’t be afraid to use complex properties like extensions of ArrayCollections – but never ever dispatch events as seen in many applications). The ValueObject class is deprecated since version 2.1 of Cairngorm – so don’t bother to look at it. If you need to improve your code readability you can use the interface IValueObject – meaning that you can point out a generic value object where needed (assuming that that value object will evolve and you don’t need each and every single property of it).

Getting to the view related classes, ViewLocator will be used to register GUI components since ViewHelper is deprecated. As you can see, the same technique is used for registering GUIs to this Singleton class as in FrontController’s case. Commands which will interfere with the GUIs does not need to know the name of it, but it will use the ViewLocator which will return the instance of that class – so it will can manipulate it. You will see in some other MVC frameworks like pureMVC that a mediator is used to control a GUI element, but Cairngorm has no notion of it.

After you’ll get some experience in getting yourself organized after the Cairngorm principles, I’m convinced that you will find your way of adding more patterns to it – in order to become your pattern. For now, it is important that you, as a “young padawan” to concentrate over respecting basic principles, to make use of data binding and change watchers (knowing exactly what you do – recommended reading is about propertyChange events dispatched). Don’t listen to people which says “data binding is bad” and be careful what you learn – think how easy it is to learn something the wrong way, but how hard it is to forget it afterward.With patience and a strong will for experimenting (let’s say you will decide to refactor one of your projects to Cairngorm) you will get to the point where you’ll have a lot of alternatives and solutions by your side.

I will continue “the Way I See It” series with the last part of Cairngorm, trying to point out some of the improvements that other developers created for it.

I’ve created a repository for the some extension components which I consider necessary for Spark. The first one is AutoComplete component , version 0.1 – in the repository you can find the source code of the test here. I’m very happy with the way Gumbo have evolved – the initial build of AutoComplete component didn’t took too much developing effort.

Enjoy!

From the beginning, I have to remind you that this is not a tutorial – the web is filled with tutorials about Cairngorm which awaits for you to read if that is what you were looking for. It’s a discussion about principles, because principles are the base of developing for excellency : the level of abstraction of a principle it’s the highest level you will ever achieve. There are voices out there which complains about couching design patterns or OOP, while an simple example code should actually do it. In the beginning of my journey – when I’ve started couching developers – I was providing such examples and explained them too, but the result was not so good. I do not really know the essence of my faults, but I suspect that they kept expecting me to provide examples and never got where I was really pointing – to start learning and experimenting. Let’s face it, you’ll have to be either a famous guru or a developer who stopped learning, in order to provide some final examples (which doesn’t have an evolution). I’m evolving too, you know ?

Now, what is Cairngorm ? Well, it’s a collection of principles, a commonly used methodology, a set of standards. As I’ve previously said, this happens when a team is working on a project – they need a set of rules to help them keep organized, to know what’s where – mostly if happens to change places. Once you’ve absorbed the principles, you have a guarantee to quickly start working on an existing application, to fix bugs, or whatever necessary – because you know where to look for all the pieces of the puzzle which makes that application.

Basically, the principles behind Cairngorm where defined by the application planning, so let’s go a bit deeper into this subject. When you receive (or create) the basic specifications on a project, you as a developer, do the following steps immediately – without thinking about the consequences : identify what you don’t know how to implement, go search the web for alike solution, do some tests on your own (as close to prototyping as you can get), take care of the rest of the details. Well, I’m not going to say that this is wrong as long as it works. I’m just going to point out an alternative for you, which happens to be the principle behind Cairngorm.

So, once you have your basic specification you will sharpen your pencil and make the following :

• if you have some application mockups, do a list of GUI components which have to be created. Be very careful to take into consideration the re-use of some parts (example : you have a register form – most of their fields can be reused on client information update, right?);
• if you have specifications regarding your data (let’s say that your services are already defined) you can describe the classes which will get filled with data and exchanged with the server;
• for every GUI component you can think of, try to determine the states needed and the dependency from the outside world. The dependency is usually carried out by an event to a listener – thus, not having to directly introduce components to each other;
• for every GUI component, note down your set of constrains – might lead to more needs which were not described in the previous step (let’s say you’ll have to check an username against the server for uniqueness);
• for the entire application, try to determine the shared variables

For sure, there are things missing – you’ll know what to do when the time comes, don’t worry.

What we’ve accomplished by doing the lists above ? We’ve prepared the organizing and partitioning of code, packages and component functionality and roles – exactly the declared purpose of Cairngorm. I’ll go deep into explaining Cairngorm classes later. For now, I really have to use some of the fancy terms to describe what’s happening.

Cairngorm puts at your disposal, the following actors (classes which you will extend and / or use as needed) : ModelLocator - a Singleton typed class which will hold all the application data. The GUI components will access this data using binding, so every time data changes, it will be updated in the client’s view. The GUI generates events as a result of user interaction with it (if you went for the right dependency from the outside world you will have the following classification : internal because is needed only by the component, external because it need to be passed to the world). An external event will be broadcast to the world by transforming it into a CairngormEvent – you’ll see the beauty of it, because it can dispatch itself via CairngormEventDispatcher (Singleton typed, of course). Events are heard by FrontController , actually by your class which extends it and registers associations between events and commands. As a result of an event a Command is triggered – for each and every “global” application event you will have a registered command. Commands contains the logic to delegate their work to an extension of a Delegate class – which will perform the needed action and return a result back to its Command. Delegates usually calls Services and upon result, the Command which receives it will alter data in the ModelLocator so it will be represented back in the GUI which needs it.

I’m sure that this is not such a complicated story to digest and represents the details of the principle behind Cairngorm.

In my next post I will go deeply into Cairngorm classes.