The session is entitled, "Building Matrix – Scaling Flex for a Large Trading Application" and it will cover our experiences as we worked on the client-side architecture of Matrix, together with a large team of developers. We will discuss the patterns and practices that made the delivery possible — modularization, dependency management, performance tuning, inversion-of-control, etc. — and the challenges we faced along the way, providing guidance for other large-scale enterprise Flex projects.

For more information, put on your headphones and check out the Morgan Stanley Matrix micro-site. Some other resources are listed below. Hope to see you there!

• Morgan Stanley raises the bar for rich Internet applications using Adobe Flash Platform technologies
• Morgan Stanley's Matrix: An App From the Future
• Morgan Stanley taps Adobe Flex framework for new trading platform

<popup:PopUpWrapper open="{model.openPopUp}">
   <mx:Label text="Hello World"/>
</popup:PopUpWrapper>

The PopUpWrapper tag is a non-visual component that manages opening and closing the popup. When its open property is set to true, a popup is opened containing the component wrapped by the tag; in this case a Label. When the open property is set back to false, the popup closes again. Alternatively, the component may dispatch an Event.CLOSE event, which will be handled by the PopUpWrapper itself.

This approach helps to keep MXML views components clean and free from ActionScript logic, whilst removing duplicated code wherever the PopUpManager is needed. The opening and closure can be controlled conveniently through bindings, as above, which plays nicely with presentation models. There are also simple ways to control the life-cycle of the popup and to apply special behaviors, such as effects that play while it opens and closes.

The remainder of this post covers the two components available -- PopUpWrapper and PopUpFactory -- explaining the differences between them. The library, source code, unit tests and a sample application are available for download here:

• FlexPopUpWrapper.swc - the SWC library compiled with Flex 3.3.
• FlexPopUpWrapper - a Flex library project containing the source for the two components.
• FlexPopUpWrapperExample - a Flex application project containing a sample application.
• FlexPopUpWrapperUnitTests - a Flex application project containing the unit test runner for the FlexPopUpWrapper library.

There are two components with slightly different capabilities:

• PopUpWrapper - this is the simplest tag. It defers the creation of the popup view until the first time the popup is opened, then reuses the same view every subsequent time. There is no mechanism for releasing that view to be garbage collected.
• PopUpFactory - this is the more flexible but less simple tag. It also defers creation of the popup view, but gives control over whether or not the view should be reused when the popup is next opened. If reuse is disabled, the view is made eligible for garbage collection upon closure.

Some examples of each are now provided.

The PopUpWrapper Component

Here's a more detailed version of the "Hello World", this time showing all of the properties and events available:

<popup:PopUpWrapper
    open="{model.openPopUp}"
    center="true"
    modal="false"
    childList="{PopUpManagerChildList.POPUP}"
    opening="openingHandler()"
    opened="openedHandler()"
    closing="closingHandler()"
    closed="closedHandler()">
    <mx:Label text="Hello World!"/>
<popup:PopUpWrapper>

The properties provide the same control over the popup as the PopUpManager. The events are dispatched at various points during the life-cycle of a popup:

• PopUpEvent.OPENING is dispatched after the popup view has been created but just before it has actually been added to the display list.
• PopUpEvent.OPENED is dispatched just after the popup view has been added to the display list.
• PopUpEvent.CLOSING is dispatched just before the popup view is removed from the display list.
• PopUpEvent.CLOSED is dispatched just after the popup view has been removed from the display list.

Here's another example where the popup is opened or closed using buttons instead of binding. The view used for the actual popup is a custom component.

<popup:PopUpWrapper id="popup">
    <mypopup:MyPopupView/>
</popup:PopUpWrapper>

<mx:Button label="Open" click="popup.open = true"/>
<mx:Button label="Close" click="popup.open = false"/>

The popup view itself can also instruct the closure of the popup by dispatching an Event.CLOSE event. For example:

<mypopup:VBox ... >
    <mx:Label text="My Popup!"/>
    <Button 
        label="Close" 
        click="dispatchEvent(new Event(Event.CLOSE))"/>
</mypopup:VBox>    

The PopUpFactory Component

The PopUpFactory tag uses a different mechanism for specifying the popup view. It is in fact the same approach that list-based controls use for their item renderers. The factory property can either be set to the class name for the popup view, or else an in-line component can be declared.

Here is a simples use case, specifying the popup view class name:

<popup:PopUpFactory 
    open="{model.openPopUp}"
    factory="my.package.MyPopupView"
    reuse="false"/>

Notice that the PopUpFactory includes a reuse property. This gives control over whether or not the popup view is reused, in contrast to the PopUpWrapper tag which always reuses the view and never makes it eligible for garbage collection.

When working with the PopUpManager directly it is common to make popups eligible for garbage collection once they have been removed. However there are good use cases for both approaches. If an application shows a large popup at start-up and then never again, it is wasteful of resources to keep it in memory. Alternatively, if a popup is repeatedly shown and hidden, such as a context menu, it is more efficient to reuses a single instance. As with all Flex development, the Flex Profiler should be used to ensure popup views are successfully garbage collected, since they can be a source of memory leaks.

Here is another example where the popup view is declared as an in-line component, in a similar manner to an item renderer on a list-based control.

<popup:PopUpFactory 
    open="{model.openPopUp}"
    reuse="false">
    <mx:Component>
        <mypopup:MyPopupView
            title="{outerDocument.model.popUpTitle}"/>
    </mx:Component>
</popup:PopUpFactory>

The PopUpFactory tag also provides the same properties as the PopUpWrapper tag, since they both inherit from a common base class.

Popup Behaviors

When we first introduced a declarative approach for popups to our projects, we noticed developers customizing the classes with more and more specific behavior. In one situation, a popup needed to play a transition while opening; in another the popup had to remain centered whenever its contents resized. Soon the popup tags became bloated with code for handling all of these special requirements, each applicable only to one or two popups.

The IPopUpBehavior interface was introduced to extract these specialities into their own classes. In this way, a set of behaviors can be created, independent of one another, and the appropriate behaviors can be applied for a given situation. This design creates a nice extensibility point, allowing developers to write their own behaviors without needing to customize the declarative tags at all.

Here is an example of a popup with a number of behaviors applied.

<popup:PopUpFactory
    open="{model.showPopUp}"
    factory="my.package.MyPopUpView">
    <popup:behaviors>
        <mx:Array>
            <popup:ZoomAndFadePopUpBehavior/>
            <popup:KeepCenteredPopUpBehavior/>
        </mx:Array>
    <popup:behaviors>
</popup:PopUpFactory>

In this case, two custom popup behaviors are being applied. The first plays a zoom and fade effect upon opening and closure, while the second ensures that the popup remains centered whenever its contents is resized. The declarative approach makes it simple to configure these behaviors.

To write your own popup behavior, just implement the IPopUpBehavior interface:

public interface IPopUpBehavior
{
    function apply(opener:PopUpBase):void;
}

A reference to the popup component is passed through the apply() method to each behavior. The behavior can then attach event handlers in order to control the behavior of the actual popup while it is opened or closed. Some examples are provided in the sample project (download above). A behavior can also suspend and resume closure by calling the suspendClosure() and resumeClosure() methods of the PopUpEvent class. This allows something asynchronous, such as the playing of an effect, to take place during closure, before the popup is actually removed from the display list.

How Does It Work?

The design for the popup tags is relatively simple. There's a common base class -- PopUpBase -- that is extended by the two tags: PopUpWrapper and PopUpFactory. The base class contains the common properties -- open, center, modal -- and also holds an array of behaviors, applying them during opening and closure. The two concrete tags implement different creation and destruction policies using the standard mechanisms for deferred instantiation and object factories: IDeferredInstance and IFactory. The Flex compiler takes care of the rest, converting the declared popup view into an appropriately configured DeferredInstanceFromFunction/Class or ClassFactory object. See the Flex Language Reference for more details.

Conclusion

We've been using versions of these tags on our projects for several years now. They help us to separate concerns, keeping our views as simple declarations of components, free from script block logic that would make them harder to understand and more difficult to unit test.

It's worth noting that Flex 4 includes its own declarative tag -- PopUpAnchor -- which also takes advantage of MXML and deferred creation, but it is designed for drop-down menu scenarios. There are some similarities, but the PopUpWrapper and PopUpFactory components are designed for more general popup handling. Perhaps a future version of the SDK will include declarative tags that make it simple to manage the life-cycle of popups and apply different behaviors, but in the meantime we hope you enjoy using these components.

Introduction

So it is clearly important to ensure event dispatching logic is correct. To promote the best-practice of unit testing the dispatch of events, I have written a small extension to the FlexUnit TestCase class that makes it easy: EventfulTestCase. This is a new base class for any tests that involve the dispatch of events. It supports both standard Flash events and also Cairngorm events.

The following ActionScript source files accompany this post:

• EventfulTestCase.as - the FlexUnit TestCase extension.
• EventListener.as - a helper class required by EventfulTestCase.as
• CairngormEventSource.as - optional class only needed for testing Cairngorm event dispatching

Writing Eventful Test Cases

The process of writing an eventful test case involves first recording the expected events, then performing the action under test, and finally asserting that the expected events occurred. EventfulTestCase defines three kinds of functions to help with this:

1. expect functions - used to record the events that are expected to occur during the test case.
2. assert functions - used to assert that the expected events actually occurred.
3. actual event getters - used to access the actual events that were heard so that more specific assertions can be carried out.

Example 1: testing the dispatch of normal events

Shown below is a simple example which asserts that the temperatureChanges event is dispatched when the addPlutonium() function is called.

public function testAddPlutonium() : void
{
   // record the expected event
   expectEvent( reactor, TemperatureChangeEvent.TEMPERATURE_CHANGE );
         
   // perform the action that is being tested
   reactor.addPlutonium( plutonium );
         
   // assert that the expected events occurred
   assertExpectedEventsOccurred( 
      "The temperature change event was not dispatched." );
}

If the expected event is not dispatched, the test case will fail and the developer will be presented with a failure message to assist in debugging. In this case, the message might look like: "The temperature change event was not dispatched. Expected events <temperatureChangedEvent> but heard events <reactorStoppedEvent>". Now the developer knows that the addPlutonium() function contains a logical error which causes the wrong event to be dispatched.

Example 2: testing the dispatch of Cairngorm events

The next example is a little more complex and asserts that two Cairngorm events have occurred. Since Cairngorm events are dispatched through the CairngormEventDispatcher singleton instead of a regular Flex EventDispatcher, the CairngormEventSource adapter class must be used as the event source.

public function testRefreshPlutoniumStocks() : void
{
   // record the expected events
   expectEvents( 
      CairngormEventSource.instance, // adapter for Cairngorm events
      GetLocalPlutoniumStocksEvent.EVENT_NAME,
      GetNationalPlutoniumStocksEvent.EVENT_NAME );
    
   // perform the action that is being tested
   reactor.refreshPlutoniumStocks();
 
   // assert that the expected events occurred
   assertExpectedEventsOccurred(
      "The Cairngorm events to fetch local and national " +
      "plutonium stocks were not dispatched." );
}

Example 3: performing more detailed assertions

The final example builds on the first, demonstrating how to use the actual event getters for performing more detailed assertions.

public function testAddPlutonium() : void
{
   // record the expected event
   expectEvent( reactor, TemperatureChangeEvent.TEMPERATURE_CHANGE );
         
   // perform the action that is being tested
   reactor.addPlutonium( plutonium );
         
   // assert that the expected events occurred
   assertExpectedEventsOccurred( 
      "The temperature change event was not dispatched." );

   // assert on the details of the actual event
   var temperatureChangeEvent : TemperatureChangeEvent = 
      TemperatureChangeEvent( lastActualEvent );
      
   var expectedTemperature : Number = 550;
      
   assertEquals(
      "The expected temperature change did not occur.",
      expectedTemperature,
      temperatureChangeEvent.temperature );
}

Known Limitations

EventfulTestCase only listens for the expected events and cannot hear unexpected events. The consequence of this is limited detail in the test failure messages. Only the expected events that actually occurred can be reported. The reason for this limitation is that the Flex framework does not enable us to listen to unspecified event types. In other words, we need to register listeners explicitly for each type of event that we want to listen to. One work-around would be to override the dispatchEvent() function of the EventListener framework class, but that would be overly intrusive. This limitation is not severe since the failure messages that can be provided are still reasonably useful.

It should also be noted that EventfulTestCase relies on the fact that most event dispatching takes place synchronously in Flex. When a function dispatches an event, we can be sure that any registered listeners will hear that event synchronously before the function continues and returns. In Flex applications, asynchronicity is typically confined to the I/O operations performed by the Flash Player, and these sit outside the normal realm of unit testing. It is usually possible to mock genuinely asynchronous behaviour, so that the class in question can be tested synchronously. When this is not the case, or for integration testing purposes, a more sophisticated solution is required.

Conclusion

The bugs and design flaws associated with event dispatching often slip the net when unit testing, allowing them to lurk in the deep and strike later. The EventfulTestCase extension helps to prevent this by making it quick and easy to test event dispatching. The process involves three stages: recording expectations, performing actions and asserting that the events occurred. As we attempt to build bigger and better Flex applications, we must test more thoroughly to ensure our success, and this must include testing events.