« Getting Started with the PureMVC Startup Manager - Part 1
Getting Started with the PureMVC Startup Manager - Part 3 »

Getting Started with the PureMVC Startup Manager - Part 2

The StartupMonitorProxy

A PureMVC-based application typically has a startup command that instantiates some basic proxies and mediators. In our sample project we want to load a CSS stylesheet and an XML file with content before allowing any user interaction (see part 1). The important thing here is to make sure that everything gets loaded in the proper order and is fully loaded before it is accessed. Here is where the StartupMonitorProxy steps in. This class is at the core of the Startup Manager utility.

The StartupMonitorProxy takes care of how the resource loading should be sequenced so that dependent resources are loaded in correct order. It also keeps track of the progress of the resource loading, and it knows when the resource loading is complete. The way you use the StartupMonitorProxy is pretty straightforward:

  1. A single instance of the StartupMonitorProxy is registered which is usually referred to as the monitor.
  2. Each startup resource is registered with the monitor, using the addResource() method.
  3. The loading process is started by calling the monitor’s loadResources() method.

(For a more detailed description please refer to the excellent API documentation.)

Now let’s take a quick look at the other actors that are needed to make the startup utility work.

The StartupResourceProxy

For each startup resource the application must instantiate a StartupResourceProxy object. These objects are required only by the utility and must not be confused with the normal resource proxies that represent the data carrier objects of the model. The regular proxies are instantiated and registered with the application first. After that the StartupResourceProxy objects are instantiated, receiving the resource proxy instance and a separate startup resource name. The two proxy types are like twins, but they live in different worlds. We will shortly see what this looks like in code.

“Loaded” and “Failed” Notifications

In order to inform the monitor that a resource has been loaded successfully or that the resource load has failed, the application must register the utility commands StartupResourceLoadedCommand and StartupResourceFailedCommand. These commands are responsible for sending “Loaded” and “Failed” notifications to the monitor whereby the notification body identifies the particular resource.

Updating the Project Space

Before we continue with the actual ActionScript code, let’s create some more class files in our project space.

  1. Create a file with the name StartupCommand.as in the controller folder.
  2. Create three new files in the model folder and name them EntityProxy.as, SiteDataProxy.as, StyleSheetProxy.as.
  3. Create a new folder vo under the model folder.
  4. Create a file with the name SectionVO in the vo folder.

Your project panel should look like this now:

Project Space

The ApplicationFacade

We are starting with the ApplicationFacade class (if you followed part 1 of this tutorial you can paste the code below into the already existing empty ApplicationFacade.as file). It pretty much looks like a typical PureMVC facade:

  1. package com.log2e.puremvcdemo
  2. {
  3.    import org.puremvc.as3.interfaces.IFacade;
  4.    import org.puremvc.as3.patterns.facade.Facade;
  5.    import org.puremvc.as3.utilities.startupmanager.controller.StartupResourceLoadedCommand;
  6.    import org.puremvc.as3.utilities.startupmanager.controller.StartupResourceFailedCommand;
  7.    import com.log2e.puremvcdemo.controller.StartupCommand;
  8.  
  9.    public class ApplicationFacade extends Facade implements IFacade
  10.    {
  11.       public static const STARTUP:String = "startup";
  12.       public static const STYLE_SHEET_LOADING:String = "styleSheetLoading";
  13.       public static const STYLE_SHEET_LOADED:String = "styleSheetLoaded";
  14.       public static const STYLE_SHEET_FAILED:String = "styleSheetFailed";
  15.       public static const SITE_DATA_LOADING:String = "siteDataLoading";
  16.       public static const SITE_DATA_LOADED:String = "siteDataLoaded";
  17.       public static const SITE_DATA_FAILED:String = "siteDataFailed";  
  18.  
  19.       public static function getInstance(): ApplicationFacade
  20.       {
  21.          if (instance == null)
  22.          {
  23.             instance = new ApplicationFacade();
  24.          }
  25.          return instance as ApplicationFacade;
  26.       }
  27.  
  28.       override protected function initializeController():void
  29.       {
  30.          super.initializeController();
  31.          registerCommand( STARTUP, StartupCommand );  
  32.  
  33.          registerCommand( STYLE_SHEET_LOADED, StartupResourceLoadedCommand );
  34.          registerCommand( SITE_DATA_LOADED, StartupResourceLoadedCommand );
  35.  
  36.          registerCommand( STYLE_SHEET_FAILED, StartupResourceFailedCommand );
  37.          registerCommand( SITE_DATA_FAILED, StartupResourceFailedCommand );
  38.       }
  39.  
  40.       public function startup( stage:Object ):void
  41.       {
  42.          sendNotification( STARTUP, stage );
  43.       }
  44.  
  45.    }
  46. }

Lines 12-17: Three notification names are defined for each of both resources, the stylesheet (STYLE_SHEET_LOADING, STYLE_SHEET_LOADED, STYLE_SHEET_FAILED) and the site data (SITE_DATA_LOADING, SITE_DATA_LOADED, SITE_DATA_FAILED). Please note that the ..._LOADING notifications are not necessarily required by the Startup Manager utility, they are just sent as additional information, using the regular PureMVC sendNotification() method every time a load attempt is made.

Lines 33-37: The before mentioned utility commands are registered. It’s important that the commands are registered separately with the “Loaded” and “Failed” notification names for every single startup resource.

The StartupCommand

The StartupCommand is the place where we define the proxies and instantiate the StartupMonitorProxy object:

  1. package com.log2e.puremvcdemo.controller
  2. {
  3.    import com.log2e.puremvcdemo.model.SiteDataProxy;
  4.    import flash.display.Stage;
  5.    import org.puremvc.as3.interfaces.ICommand;
  6.    import org.puremvc.as3.interfaces.INotification;
  7.    import org.puremvc.as3.patterns.command.SimpleCommand;
  8.    import org.puremvc.as3.utilities.startupmanager.model.StartupResourceProxy;
  9.    import org.puremvc.as3.utilities.startupmanager.model.StartupMonitorProxy;
  10.    import org.puremvc.as3.utilities.startupmanager.interfaces.IStartupProxy;
  11.    import com.log2e.puremvcdemo.model.StyleSheetProxy;
  12.    import com.log2e.puremvcdemo.view.StageMediator;
  13.  
  14.    public class StartupCommand extends SimpleCommand implements ICommand
  15.    {
  16.       private var _monitor:StartupMonitorProxy;
  17.  
  18.       override public function execute( note:INotification ):void    
  19.       {
  20.          var stage:Stage = note.getBody() as Stage;
  21.          facade.registerMediator( new StageMediator( stage ) );
  22.    
  23.          facade.registerProxy( new StartupMonitorProxy() );
  24.          _monitor = facade.retrieveProxy( StartupMonitorProxy.NAME ) as StartupMonitorProxy;
  25.          _monitor.defaultTimeout = 30;
  26.    
  27.          var styleSheetProxy:IStartupProxy = new StyleSheetProxy();
  28.          var siteDataProxy:IStartupProxy = new SiteDataProxy();
  29.  
  30.          facade.registerProxy( styleSheetProxy );
  31.          facade.registerProxy( siteDataProxy );
  32.    
  33.          var rStyleSheetProxy:StartupResourceProxy = makeAndRegisterStartupResource( StyleSheetProxy.SRNAME, styleSheetProxy );
  34.          var rSiteDataProxy:StartupResourceProxy = makeAndRegisterStartupResource( SiteDataProxy.SRNAME, siteDataProxy );
  35.    
  36.          rSiteDataProxy.requires = [ rStyleSheetProxy ];
  37.    
  38.          _monitor.loadResources();
  39.       }
  40.  
  41.       private function makeAndRegisterStartupResource( proxyName:String, appResourceProxy:IStartupProxy ):StartupResourceProxy
  42.       {
  43.          var r:StartupResourceProxy = new StartupResourceProxy( proxyName, appResourceProxy );
  44.          facade.registerProxy( r );
  45.          _monitor.addResource( r );
  46.          return r;
  47.       }
  48.  
  49.    }
  50. }

Lines 23-24: An instance of the StartupMonitorProxy class is created and registered with the application. The proxy is assigned to the private property _monitor.

Line 25: A default timeout is set. You can set individual timeout values for each startup resource. If you do not set timeouts on the resource level the monitor’s default timeout is used. (For more information on the use of timeouts take a look at the StartupResourceProxy API documentation.)

Lines 27-28: The proxies for the stylesheet and the site data are instantiated. Please note that they are typed as IStartupProxy because the proxies are supposed to implement the IStartupProxy interface in addition to the usual PureMVC IProxy interface. We will return to this topic when we look at the implementation of the proxies.

Lines 30-31: Like any other PureMVC proxy the styleSheetProxy and the siteDataProxy are registered with the application.

Lines 33-34: Whereas instances of the StyleSheetProxy and the SiteDataProxy are supposed to be used throughout the whole application, the rStyleSheetProxy and the rSiteDataProxy objects are only needed in the context of the startup utility.

Line 36: The dependency between the two resources is specified. The site data requires that the stylesheet must be loaded first.

Line 38: Calling loadResources() on the monitor instance triggers the loading of all startup resources.

Lines 41-47: This is a helper function that I borrowed from the Startup As Ordered demo. It creates and registers a StartupResourceProxy object and adds it to the monitor’s list of resources.

The Resource Proxies

Generally speaking, a proxy in a PureMVC-based application manages a piece of the data model. The same proxy might also be responsible for retrieving its data from a remote location during startup. The PureMVC Startup Manager utility supports this pattern by providing the IStartupProxy interface which strictly requires the implementation of a load() method. Any resource proxy that is part of the initial loading process monitored by the utility must implement this interface.

On the other hand, the proxies must work in the usual PureMVC environment where they are supposed to extend the framework’s Proxy class and to implement the IProxy interface. To make the resource proxies work in both contexts, the utitliy author uses an abstract class that facilitates the cooperation between the Startup Manager and the application. You can find this class in the Startup As Ordered demo, the class name is EntityProxy. It extends Proxy and implements IProxy like a normal PureMVC proxy. But this proxy class isn’t instantiated and registered with the application itself, it only serves as a helper class for the actual resource proxies. The resource proxies extend EntityProxy and implement IStartupProxy. This way they become part of both contexts.

Here’s the code of the EntityProxy class:

  1. package com.log2e.puremvcdemo.model
  2. {
  3.    import org.puremvc.as3.interfaces.IProxy;
  4.    import org.puremvc.as3.patterns.proxy.Proxy;
  5.    import org.puremvc.as3.utilities.startupmanager.model.StartupResourceProxy;
  6.    import com.log2e.puremvcdemo.ApplicationFacade;
  7.  
  8.    public class EntityProxy extends Proxy implements IProxy
  9.    {
  10.       public function EntityProxy( name :String )
  11.       {
  12.          super( name );
  13.       }
  14.  
  15.       protected function sendLoadedNotification( noteName:String, noteBody:String, srName:String ):void
  16.       {
  17.          var srProxy:StartupResourceProxy = facade.retrieveProxy( srName ) as StartupResourceProxy;
  18.          if ( ! srProxy.isTimedOut() )
  19.          {
  20.             sendNotification( noteName, noteBody );
  21.          }
  22.       }
  23.  
  24.    }
  25. }

Lines 15-22: The sendLoadedNotification() method is a helper function that is used by the actual resource proxies to send “Loaded” or “Failed” notifications. These notifications are only sent if the Startup Manager hasn’t timed out the resource. In order to get the timeout information, the resource proxy’s “twin object” (srProxy) is retrieved. By the way, accessing this state information is the only reason why the StartupResourceProxy objects have been registered with the application in the StartupCommand class (see above, line 44: facade.registerProxy( r );). The utility itself does not require that they are registered with the PureMVC model.

The resource proxies finally implement the actual loading mechanisms. I hope you remember that the proxies in our sample project are responsible for loading an external CSS stylesheet and an XML file. Here’s the code of the two proxies.

StyleSheetProxy

  1. package com.log2e.puremvcdemo.model
  2. {
  3.    import flash.events.*;
  4.    import flash.net.URLLoader;
  5.    import flash.net.URLRequest;
  6.    import flash.text.StyleSheet;
  7.    import org.puremvc.as3.interfaces.IProxy;
  8.    import org.puremvc.as3.patterns.proxy.Proxy;
  9.    import org.puremvc.as3.utilities.startupmanager.interfaces.IStartupProxy;
  10.    import com.log2e.puremvcdemo.ApplicationFacade;
  11.    import com.log2e.puremvcdemo.model.EntityProxy;
  12.  
  13.    public class StyleSheetProxy extends EntityProxy implements IStartupProxy
  14.    {
  15.       public static const NAME:String = "StyleSheetProxy";
  16.       public static const SRNAME:String = "StyleSheetSRProxy";
  17.  
  18.       public function StyleSheetProxy()
  19.       {
  20.          super( NAME );
  21.       }
  22.  
  23.       public function load() :void
  24.       {
  25.          sendNotification( ApplicationFacade.STYLE_SHEET_LOADING );
  26.  
  27.          var request:URLRequest = new URLRequest("styles.css");
  28.          var loader:URLLoader = new URLLoader();
  29.    
  30.          loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
  31.          loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
  32.    
  33.          loader.load(request);
  34.       }
  35.  
  36.       private function loaderCompleteHandler(event:Event):void
  37.       {
  38.          data = new StyleSheet();
  39.          data.parseCSS( URLLoader(event.target).data );
  40.          sendLoadedNotification( ApplicationFacade.STYLE_SHEET_LOADED, NAME, SRNAME );
  41.       }
  42.  
  43.       private function errorHandler(e:IOErrorEvent):void
  44.       {
  45.          sendLoadedNotification( ApplicationFacade.STYLE_SHEET_FAILED, NAME, SRNAME );
  46.       }
  47.  
  48.       public function get css():StyleSheet
  49.       {
  50.          return data as StyleSheet;
  51.       }
  52.  
  53.    }
  54. }

Line 16: The SRNAME constant holds the name of the StartupResourceProxy twin.

Line 40, line 45: The helper method in the parent EntityProxy class is called to send “Loaded”/”Failed” notifications.

Lines 48-51: The getter method returns the internal data property as a typed StyleSheet object.

The SiteDataProxy class works in a similar fashion:

  1. package com.log2e.puremvcdemo.model
  2. {
  3.    import flash.events.*;
  4.    import flash.net.URLLoader;
  5.    import flash.net.URLRequest;
  6.    import org.puremvc.as3.interfaces.IProxy;
  7.    import org.puremvc.as3.patterns.proxy.Proxy;
  8.    import org.puremvc.as3.utilities.startupmanager.interfaces.IStartupProxy;
  9.    import com.log2e.puremvcdemo.ApplicationFacade;
  10.    import com.log2e.puremvcdemo.model.EntityProxy;
  11.    iimport com.log2e.puremvcdemo.model.vo.SectionVO;
  12.  
  13.    public class SiteDataProxy extends EntityProxy implements IStartupProxy
  14.    {
  15.       public static const NAME:String = "SiteDataProxy";
  16.       public static const SRNAME:String = "SiteDataSRProxy";
  17.  
  18.       public function SiteDataProxy()
  19.       {
  20.          super( NAME );
  21.       }
  22.  
  23.       public function load() :void
  24.       {
  25.          sendNotification( ApplicationFacade.SITE_DATA_LOADING );
  26.    
  27.          var request:URLRequest = new URLRequest("data.xml");
  28.          var loader:URLLoader = new URLLoader();
  29.    
  30.          loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
  31.          loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
  32.    
  33.          loader.load(request);
  34.       }
  35.  
  36.       private function loaderCompleteHandler(event:Event):void
  37.       {  
  38.          var xml:XML = new XML( event.target.data );
  39.          xml.ignoreWhitespace = true;
  40.    
  41.          var title:String = xml.title.children().toXMLString();
  42.          var sections:Array = new Array();
  43.          var sectionsXMLList:XMLList = xml.sections.section;
  44.    
  45.          for ( var i:uint=0; i<sectionsXMLList.length(); i++ )
  46.          {
  47.             var section:XML = sectionsXMLList[i];
  48.             var id:uint = section.@id;
  49.             var sectionVO:SectionVO = new SectionVO( id, section.@label, section.content );
  50.             sections.push( sectionVO );
  51.          }
  52.    
  53.          data = new Object();
  54.          data.title = title;
  55.          data.sections = sections;
  56.    
  57.          sendLoadedNotification( ApplicationFacade.SITE_DATA_LOADED, NAME, SRNAME );
  58.       }
  59.  
  60.       private function errorHandler(e:IOErrorEvent):void
  61.       {
  62.          sendLoadedNotification( ApplicationFacade.SITE_DATA_FAILED, NAME, SRNAME );
  63.       }
  64.  
  65.       public function get title():String
  66.       {
  67.          return data.title as String;
  68.       }
  69.  
  70.       public function get sections():Array
  71.       {
  72.          return data.sections as Array;
  73.       }
  74.  
  75.    }
  76. }

Lines 38-51: Please refer to the data.xml file described in part 1 of this tutorial.

Line 49: The SiteDataProxy class makes use of a simple value object class (SectionVO):

  1. package com.log2e.puremvcdemo.model.vo
  2. {
  3.    
  4.    public class SectionVO
  5.    {
  6.       private var _id:uint;
  7.       private var _label:String;
  8.       private var _content:String;
  9.  
  10.       public function SectionVO( id:uint, label:String, content:String )
  11.       {
  12.          _id = id;
  13.          _label = label;
  14.          _content = content;
  15.       }
  16.  
  17.       public function get id():uint
  18.       {
  19.          return _id;
  20.       }
  21.  
  22.       public function get label():String
  23.       {
  24.          return _label;
  25.       }
  26.  
  27.       public function get content():String
  28.       {
  29.          return _content;
  30.       }
  31.  
  32.    }
  33. }

In the third and last part of this tutorial we will be creating a rudimentary view to test our efforts.

You can download the sample files from here (the ZIP archive includes a FlashDevelop project file). If you want to comment on this tutorial please post in the comments section at the end of the introductory post.

Tags: , , , ,

This entry was posted on Saturday, May 17th, 2008 at 12:27 pm and is filed under ActionScript, Flash, FlashDevelop, Flex, PureMVC. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.

One Response to “Getting Started with the PureMVC Startup Manager - Part 2”

  1. Bildschirmsport » Blog Archive » Asynchrones Laden in PureMVC Says:
    July 4th, 2008 at 12:18 am

    [...] den StartupManager empfehle ich die 3-teilige Anleitung aus Stefan Schmalhaus’ log2e Blog: Teil 1, Teil 2 und Teil 3. Obwohl er laut Blog aus Krefeld kommt, sind diese Anleitungen allerdings in [...]