Steve,

Sorry, I corrected the post. I'd linked to the document name, which changed. Not a good thing.

The latest version of the Best Practices doc is at:

PureMVC.org -> Docs -> Best Practices

The short answer is Commands aren't the ones doing service calls in PureMVC, its the Proxies doing that. Commands are generally executing synchronous business logic within the client.When a Proxy hears back from a service it will generally send a Notification you can respond to with a Command.

The execute method of MacroCommand is final to prevent its  being inadvertently overridden in a subclass, as you would with a SimpleCommand.

Sean,

Mediators should play a fairly simple and mechanical role in the architecture:

• Receive Event information from their View Components, gather information from the View Component and/or custom Event and send it off in a Notification.
• Receive Notifications, extract the data mostly from the Notification, and update the View Component.

Similar to a switchboard operator. Who are you calling, sir? Ok, I'll route you through.

Although you can do most anything in a Mediator, limiting it to this role and pushing more complicated stuff, (the sort of stuff you might actually want to reuse) into a Command is a better idea. This keeps the Mediator simple and lightweight, doing only the minimum work necessary to adapt the View Component to the system.

For guidance about the Mediator's role, examine the three Mediators of the Architecture 101 demo, and how they adhere to this simple ambition. Note that a more complicated activity such as deleting a User (and their associated Roles) are done in a Command.

Because they are special case adapters for custom View Components, it is not expected that Mediators will be the most reusable aspect of a system. Due to the relatively simple role Mediators play, I sought the simplest way of 'plugging' them into the system.

But of course this doesn't change the way you feel about the particular implementation. This is why I did my best to make PureMVC a system where you could take or leave as much as you want. If you're down with the out of box way of doing things, great. If not, there are plenty of ways to customize it to your like.

So as to how you might override this Mediator Notification behavior:

When the the View class's registerMediator method is called, it interrogates the Mediator for a list of Notification interests, by calling its listNotificationInterests method. The View maps each Notification name returned to an Observer object that points the Mediator instance and a predetermined callback method - handleNotification.

Examine the View.registerMediator method to see how this happens.

Inside View.registerMediator, when an Observer object is created, it is registered with the View's Observer Map through a call to the public method registerObserver. We typically don't create Observers, they're usually used internally by the Core actors to map Commands and Mediators to Notifications.

Consequently, the Facade does not have a registerObserver method, and it is not required by IFacade, which exposes the Core actor methods that are expected to be in typical use, and not actually the full IView, IModel and IController interfaces.

Your first step is to simply not return anything from listNotificationInterests in your Mediator. This way the View simply registers the Mediator in its Mediator Map and goes on about its business.

Then you want to add a registerObserver method to your concrete ApplicationFacade. This method should in turn call registerObserver on the View. It is not governed by an interface, so its signature can be different from that of the View. This means it can save the Mediator the work of constructing the Observer object, as sendNotification does for INotifiers.

Have your registerObserver method accept the Notification name, a reference to the Mediator instance, and a reference to the callback function. Then it would construct an appropriate Observer instance and call view.registerObserver. (the Facade has a local protected reference to the View Singleton called 'view')

Next, in your Mediator constructor, for each Notification you want to be notified of, do this:

facade.registerObserver( ApplicationFacade.SOME_NOTIFICATION_NAME, this, handleSomeNotification );

That should get you where you're wanting to go.

If I get a chance I'll work this into the courseware. I'm coming up on the section about Mediators, and clarifying this subject with hands on examples would probably be good. This is one of those areas, where the out of box way is simple and will cover most cases, but if you want a different flavor of behavior, you can get to it quickly.

Thanks for bringing this up.

Hi Carl,

In the sense that the Model/ModelLocator is like a Christmas tree and we adorn it with all our cheery holiday data objects, yes the PureMVC Model is similar to the ModelLocator.

However it differs quite a bit in terms of how we actually access to the data.

In Cairngorm, typically you:

• Define the ModelLocator class as a Singleton.
• Add properties to it.
• Fetch the ModelLocator Singleton at various places in the View by calling its getInstance method.
• Bind to its properties.

Binding is something else that is very Flex/Flash-centric that was verboten to rely upon for the PureMVC implementation. In an environment that doesn't have the Flex and Flash classes, events and binding can't be counted upon being there there for you. At least not with the Flash/Flex implementations. (Think Mozilla Tamarin, or even J2ME, or maybe curl).

In PureMVC, you:

• Define proxies to hold the data
• Register them with the Model, typically via the Facade
• Retrieve the Proxies elsewhere with Commands or Mediators
• Set the data on the View Components with Mediators

Of course there's nothing to stop you from fetching the Proxies inside your View Components, and binding to their data. But that makes the View Components less portable since they now have this inherent PureMVC stuff in them.

Look at the Architecture 101 demos. All custom components have no knowledge of the PureMVC system or where their data comes from at all. This means you could carry them away and make a Cairngorm demo around them without having to remove any PureMVC framework stuff at all. Instead they expose an API to that their Mediators use to communicate with them, using public properties and Events. Internally they use binding all they wish to move data around and change their behavior based on the current data in the controls.

This is the path to reusability in View Components.

Although you may not be intending to build an AIR app here, it would be worth your time to:

• Install the AIR Runtime and the CodePeek Demo from here: http://codepeek.futurescale.com/download.html
• Run Codepeek
• Study the code here: http://codepeek.futurescale.com/source.html

CodePeek does exactly what you are describing. The application:

• Is not visible to start with (nor is its NativeWindow, so you can't even see it at all yet.) In Flex, you'd have something like a ViewStack with a splash screen as your first child.
• Instantiates the ApplicationFacade
• Application creationComplete handler sends APP_STARTUP Notification
• Controller executes ApplicationStartupCommand
• ApplicationStartupCommand calls ModelPrepCommand
• ModelPrepCommand registers Proxies
• Two of those Proxies read XML files (from the disk with AIR, you'd call a service with Flex)
• One of those XML files is the Preferences XML db, which has the WindowMetrics data for positioning the window on the desktop. The CodePeekPrefsProxy creates and registers a WindowMetricsProxy to handle that entity in the Prefs file.
• ApplicationStartupCommand calls ViewPrepCommand
• ViewPrepCommand gets the WindowMetricsProxy, and sends an appropriate Notification
• The StageMediator listens for the various notifications for affecting the desktop window position and display state
• Once the window position has been restored, the StageMediator will detect a DISPLAY_STATE_CHANGE, MOVE and/or RESIZE events and will issue the VIEW_SHOW_WINDOW notification.
• The StageMediator listens for this Notification (yes, its perfectly fine for a Mediator to Notify itself), and will make the Window visible.
• The ApplicationMediator is also listening for VIEW_SHOW_WINDOW, and sets the Application's showControls property to true
• The Application has its visible property bound to showControls, so it shows itself (within the Window which is now visible as well). There is an associated effect that causes the whole app to slide in at this point.

You wouldn't need the StageMediator or WindowMetrics stuff in your Flex app but much of this is the same. Essentially we don't show the goods till everything is on the shelves and we're ready open the doors to the public. You'll want to prep your Model followed by the View. so the startup sequence is the same.

However, the XML database Proxy creation and registration is synchronous in CodePeek. That is to say, when we register those Proxies, they read the stuff off disk in a blocking fashion and our code follows along. When the Proxy is created, the data is there. If you examine the CodePeekSearchProxy, you'll see how you might work your async service stuff. The CodeSearchProxy doesn't get called at startup, but it shows how to do an asyncrhonous RemoteProxy.

Some of your Proxies will send off requests to remote services when they are created. You'll create and register them just the same. However, when their services return, they will send Notifications that either a Command and or various Mediators will respond to, and eventually 'turn on' the UI by doing something like sending a Notification that the ApplicationMediator responds to by setting a value on the Application that causes the ViewStack selectedIndex to change, for instance.

You might have a complex startup situation where the creation of Proxies send off multiple requests for data and you want to turn on the UI only after ALL the services have returned and been properly responded to.

In this case, I suggest having a StartupMonitorProxy created and registered that holds a simple count of the number of startup services which must return before turning on the View.

Have each of the services called at startup send a STARTUP_RESULT notification when the data comes in, which is listened for by a StartupMonitorCommand.

The StartupMonitorCommand will, each time it is executed, get the StartupMonitorProxy and call a decrement method.

After calling the decrement method, the StartupMonitorCommand will ask the StartupMonitorProxy for the count and if the count has reached zero then we know all the services have returned, and so it will send a VIEW_SHOW_CONTROLS Notification, which will be responded to by one or more Mediators who 'turn on' the View by setting properties on their stewarded View Components.

Hope this helps!

This looks awesome!

Great! I'm glad to hear it won't be a problem. I think this makes things way easier now.

Hi Michael,

On another thread, you asked about pushing the functionality of AbstractMediator and AbstractProxy back into the framework, and as you've probably read by now, I did. And I updated the PureMVC website, CodePeek, and the CafeTownsend demos accordingly. I'm working on updating the Implementation Idioms document as well.

I'm wondering how this affects your Flash Develop template.

-=Cliff>

Hey, folks guess what?

Although I'd already been to this pass before, I took another long hard look at this problem and some testing showed an amazingly cool thing:

Turns out the Proxy and Mediator framework classes can just have facade:IFacade properties, initialized to Facade.getInstance().

As long as the concrete Facade has been instantiated first, (and certainly should be) then the Framework Facade will actually return the concrete Facade instance when Facade.getInstance is called.

The only other reason for these two abstracts was to add a sendNotification convenience method to all Mediators and Proxies to keep from having to construct new Notifications all the time. This relied upon the Facade reference being available, and it is now, so this method was given to both Mediator and Proxy.

So, I've made the first functional enhancement to the framework.Version 1.3
(1.1 and 1.2 were adding a top level folder, and including the asdoc):

Mediator and Proxy both get a facade:IFacade properties and sendNotification methods.
No need to implement AbstractMediator and AbstractProxy in your apps.

If you have already built an app using AbstractMediator and AbstractProxy, simply remove them and make all Mediators and Proxies extend the framework classes instead. And of course, download and replace the PureMVC.swc.

I really thought long and hard about this. One of the major things I want is a stable framework that isn't a moving target, with
upgrades all the time. And that is still the goal.

However this is clearly:
     A) Early enough in the lifetime of the framework, and
     B) A significant improvement in requiring less of the developer and giving them more.

So, if you download the PureMVC framework zip from the site now, or view the source code, you'll see that these changes have been implemented. The CodePeek demo has also been updated, and I'll be revisiting the CafeTownsend demo shortly.

And of course Implementation Idioms is being updated as well.

Good point, Carl.

Most times, your Proxies will only have one instance created, though we won't go to the trouble to make them Singletons. So having a NAME constant to register and retrieve the Proxy with makes sense most of the time.

But lets imagine you have a particle system, where a Proxy is responsible for holding a single particle and you have thousands of particles. The ParticleProxy holds the physics implementation; the math for affecting the particle state. Its Data Object is a ParticleVO that holds the properties for a single particle.

You probably have a ParticleFactoryProxy that dynamically creates and registers these ParticleProxies, giving them unique names and properties at creation time.

The only thing that changes since we have multiple instances registered is the fact that we can't predetermine the name assign it to a constant and refer to with a singular idiom.

The ParticleFactoryProxy will only have a single instance created, so to retrieve it:

var facade:ApplicationFacade = ApplicationFacade.getInstance();
var pfProxy:ParticleFactoryProxy = facade.retrieveProxy(ParticleFactoryProxy.NAME) as ParticleFactoryProxy;

However since we have more than one instance of ParticleProxy, we'll have to have a different way of getting the name of the one we want. We'll probably have the ParticleFactoryProxy keep a list of all the names of the particles it has generated. Then to access them, perhaps from a command, we might do something like this:

var particleNames:Array = pfProxy.getParticleNames();
for (var k:int = 0; k<particleNames.length; k++) {
    var particleProxy:ParticleProxy = facade.retrieveProxy(particleNames[k]) as ParticleProxy;
    particleProxy.updateVector();
}

That's awesome! Flash Develop looks pretty cool and it's just the sort of place this middleware could come in handy to automate project setup.

BTW, they could redistribute the PureMVC.swc with their package if need be for your template dohicky to work, they just need to attribute the source somewhere so that people who are using it can get back to the support site to figure out how to use it

Hello All,

I'm currently working on a PureMVC Architecture 101 Course, and will soon be looking for interested participants in the process of testing and evaluating the overall courseware structure and effectiveness.

I've delivered extemporaneous multi-day training on Cairngorm, and I've been teaching Flex as an Adobe/Macromedia Certified Instructor since 1.5, and have had a lot of time to observe and think about courseware content, layout and delivery.

I've also felt that the thing that is missing after teaching a week of F2RCA ( http://www.adobe.com/support/training/instructor_led_curriculum/flex2_rca.html ) and F2DC ( http://www.adobe.com/support/training/instructor_led_curriculum/flex2_data_com.html ) or F2BDA ( http://www.adobe.com/support/training/instructor_led_curriculum/flex2_dashboard.html ) is Architecture.

Students come out of these classes, very well aquainted what Flex can do, and ready to build, but without a lot of direction in terms of architecture. I usually point people to the best design pattern books and sites that I know and offer to help with architecture if they need it.

But I think they'd be better served to have their top folks on the project sit through at least a 2 or 3 day structured architecture course in addition to the more development focused courses.

Recently while pondering next steps with PureMVC, I realized that courseware was the best way to proceed. I feel we need simpler examples, and a bunch of 'Hello World's are great for bitesized granularity, but won't really give you the big picture unless they fall within some ordered context.

Fortunately, Implementation Idioms had already layed out a logical way of unfolding the PureMVC design, but was entirely narrative.

With Architecture 101 the overall structure is similar, except there is much less narrative and much more hands on. Units cover the major actors in the applications you will write. There is some preamble to frame the Unit, but quickly it moves to the Labs, each of which has several learning points to be taken away and we set about absorbing them in the Steps for the Lab.

The courseware has a Lab project which you are modifying and a Solution project that you can refer to if you get stuck, though the Student Manual summarizes changes clearly and often.

If this sounds to you like a good way to learn PureMVC, and you'd like to get a first look at it when it is ready for testing, email me at cliff at puremvc dot org.

For businesses, FutureScale will also be offering PureMVC Architecture 101 as onsite instructor-led training in addition to the already available Adobe Flex training.

Michael,

A good and logical question. There is only one problem with that; the framework doesn't know your Facade name or package.

The issue (for those just tuning in) is we often want our Mediators and Proxies to have a local reference to the Singleton instance of our concrete Facade. (See for instance pages 20 and 29 of Implementation Idioms: http://puremvc.org/docs/praxis/PureMVC_Best_Practices-1.0.swf)

This keeps us from having to call ApplicationFacade.getInstance() everytime our Mediator or Proxy needs to talk to the concrete Facade.

It would be nice if the Mediator or Proxy had this from birth, so to speak.

So the idiom is to create AbstractMediator and AbstractProxy classes for our application that extend the PureMVC implementations and that fetch and cache a reference to our concrete Facade in its constructor. Then we have all our Mediators and Proxies extend these abstracts rather than the framework classes.

It's also a helpful place to imbue our Mediator or Proxy instance with any other inheritable features we'd like all Mediators or Proxies to have.

Although we don't have to create an AbstractMediator or AbstractProxy, it's one of those things that makes sense at implementation time. And it can't be put into the framework because only in our application will we know the package and name of our custom concrete Facade class.

As with EJB and plenty of other technologies, sometimes this is the sort of thing is best relegated to middleware. (Code generation and notification traffic analysis tools are on the drawing boards, but I'm busy creating PureMVC Architecture 101 Courseware at the moment).

But again, it isn't necessary to create AbstractMediator and AbstractProxy classes, its just a logical implementation time decision that is easy to do and provides a lot of benefit in terms of fewer calls to get the Singleton at runtime.

Stephan,

I have been researching screencasting tools, and found one I think will do the job.

A series of screencasts are in order I think. Setting up a project, both with and without Flex Builder. Debugging in Flex Builder.

And of course more and simpler hello worlds. All on the way.

Dale,

You got it. Inserting your [app domain] between the app name and the MVC branches is definitely the right place in the package structure to make that break.

The original post sidestepped the whole issue of the slicing of your app into discrete functional areas. It really focused on the factors leading to the sole decision of how to make the split when you come to the tiers, ie: MVC (model, view and controller) or BMVCV (business, model, view, controller, vo).

The further question the reader was left with, (the one you answered perfectly) was:

When we slice the app into functional areas to manage the inevitable explosion of classes as an app becomes less trivial, do we make that split before the MVC (or BMVCV, or whatever) branching or after it, replicated inside each of the branches.

Clearly making that branch immediately after application name will lead to a more sensible and manageable package structure.

However if you found that you created a thousand branches at that 'com.myco.myapp.subsystem' level, it would be prudent to create some grouping for them putting them at a level one deeper like:

com.myco.myapp.subsysgroup.subsystem.model.*
com.myco.myapp.subsysgroup.subsystem.view.*
com.myco.myapp.subsysgroup.subsystem.controller.*

But the point, folks is let the major application domain related branches come *before* the pacakge structure branches made for the sake of MVC framework affinity.

Thanks for bringing this up, Dale. It adds a valuable dimension to the thread.