From the code depot you can download a compiled SWC or a ZIP file that contains all the source and ASDoc generated files. We have posted the ADoc files on-line so that you can easily access them if you do not download them. Currently, we have 219 unit tests running and passing for the library, which are all available from the source tree if you wish to access them.

The current release of Core contains the following functionality. We have marked new and updated features that have been changed from the Vivisecting Media Library to the new Core Library:

• Task Management System new! – The Task system is a priority queuing system that enables an application to execute specific bundles of business and/or server logic in a specific order leveraging priority and the ability to override previously queued bundles. These bundles are encapsulated inside of Task objects, which can be then bundled Task Group objects. Tasks and task groups have the ability to take priority over other Tasks or Task Groups inside of the queue, as well as replace existing tasks in the queue based on a set of overrides an individual task can define.
• Command Action Delegation System (CAD) new! – Provides a pre-built solution for implementing the Command Pattern within ActionScript/Flex/AIR applications. The command / action system allows for commands to be dispatched to the ActionDelegate which then executes any assigned functionality via an Action.
• Selection Management System updated! – The Selection Management system enables any kind of object to become selectable and treated as part of a Selection group. In most cases this would be a UI Component that should behave similarly to a radio button group, where only one item can be selected at one time. This system also allows for multi-select and deselection of items that are members of a selection group.
• Local Connection Management updated! – The Local Connection manager is a helper class to quickly establish and manage local connection instances within an application. The Local Connection manager also supports the ability to maintain strong class types when the data object is passed over the local connection instance.
• Event Broker Utility – The Event Broker is a utility class that acts as a router for specified events. The Event Broker is a single point of contact that any object can broadcast to or subscribe to. This functionality is intended to be the focal point for implementing the mediator pattern within the application.
• Instance Factory Utility new! – The Instance Factory allows for the ability to make sure there is only one instance of a specified class within the instance of the factory. This is useful for using in Locators that handle generating a new instance on the first request but then making sure the original instance of the requested item is returned on subsequent requests.
• Singleton Factory Utility new! – Similar to the Instance Factory, the Singleton Factory verifies that there is only one instance of a requested item, but instead of being limited to the instance of the factory, the Singleton Factory verifies there is only one instance of the requested item in the entire application.
• Adjustable Date Utility new! – The adjustable date wraps a Flash Date object and provides a series of helper methods to adjust time and dates quickly and easily. Example uses included the ability to adjust a date by a specific number of days forward or backwards, making sure that the number of days in the month and Leap Years are respected during the adjustment.
• Queue Data Structures updated! – The Queue system allows for items to be stored in either a LIFO or FIFO based queue order or in a priority queue order and then retrieved from the data structure depending on how the items are ordered.
• Hash Table Data Structure – The Hash Table is key/value that allows any value or object to be used as a reference key to another value or object item. The Hash Table is similar to Flex’s ArrayCollection in how items can be referenced but unlike the collection, this is ActionScript independent, is not intended for data pagination and is focused on performance for larger data sets.
• Browser Location Utility new! – Utility class used to query the current url in the application. The class provides static properties for each piece of the application url.

Adobe MAX 2008: The Future of Flex Builder (Part One)

In this post I will be delving deeper into the new/updated feature set that focuses on the aspect of the “Test & Tune” workflow. Test & tune is the day-to-day development workflow that we are all used to: Navigating our projects, creating new code, documenting, re-factoring, debugging and testing. A lot of these features may seem small but they provide a lot of power and can drastically improve development time and ease frustration that we experience during the development cycle.

Package Explorer

The first test & tune feature I want to examine is the new Package Explorer. Some of you may be thinking to yourself that Flex Builder already has a Package Explorer and wondering why this is a new feature. Well, to be exact, Flex Builder 3 does not have a true Package Explorer, what it has is the “Flex Navigator” which is really just a folder browser. When we use the Flex Navigator we often treat it like a package explorer since ActionScript packages are just folder hierarchies and this is what is represented within the Flex Navigator. The new Package Explorer merges the functionality of the Flex Code Outline panel and the Flex Navigator into one view.

Take a look at the screen cap, first you will notice that the MXML root file is now in a (default package) node within the explorer. From there you can then expand the MXML file data to look at the Classes contained and the properties of the class. Next, you can see that the default view makes the hierarchy a flat layout. For example, the package “com.developmentarc.test” is listed all in one line which means you don’t have to expand to view the structure to access a deep package like you would in the Flex Navigator. If you don’t like the flat layout you can change the settings of the Package Explorer to create the more traditional parent/child structure.

Finally, look at the Flex 4 SWC package in the screen cap. The Flex SDK version for the project is now shown in the Package Explorer. Not only is it shown but you can expand the SWCs to see the content structure, classes and properties contained within. In the screen cap I am exploring the Array in the playerglobal.swc file. This SWC exploration also works with 3rd party SWCs, not just the Flex 4 SDK. These all may seem like small changes, but it makes exploration, creation and modification of existing projects much easier. This also allows for Java Eclipse users to experience a much more familiar view when developing Flex Applications. Good stuff.

Event Auto-generation

During development, creating event bindings and method handlers such as the Mouse click event, is a common task. The event auto-generation is a short cut feature in Design View that allows a developer to quickly generate an event handler for a component. The example they used in the session was adding an event handler for a Button’s click event. From design view the developer would click on the generate handler button next to the on click event field:

When the user clicks this button, the handler function is generated in an <Script> block within the MXML file and the method is then assigned to the Button’s click property. My personal feelings about this feature is that it is helpful for initial development and/or learning of the Flex event handling model, but for complex development I am hesitant to see this as a go to feature. For one, the feature automatically adds the script to the current MXML file. On larger projects I typically avoid having scripts in MXML, this is especially true when following the code-behind pattern. I also feel this is going against the proposed workflow model that Adobe is pushing for Flash Catalyst and Flex Builder integration since your MXML is becoming more layout-centric with Classes for logic.

Overall, its a helpful feature and it makes prototyping, initial development and demoing a lot easier. We will see how this feature matures and how it is adopted by developers in the future.

ASDoc

ASDoc-ing is the process of adding specially formatted comments to your code that enables the ASDoc tool to generate documentation from the code and formatted comments. ASDoc is just like JavaDoc and has been evolving and maturing the the first release of Flex. One feature that has been part of Eclipse’s Java development suite is the ability to see inline contextual JavaDoc notes for specific Classes, properties and/or methods. The next version of Flex Builder supports the same kind of in-context doc hinting for code that has been properly ASDoc-ed.

When a user hovers over a method, property or class in either ActionScript or MXML the ASDoc tooltip will display showing the contextual docs for the specified attribute. In the screenshot above, I am hovering over the “left” attribute of an <FxButton> tag. Notice that the displayed doc notes are only for the “left” property. If I rolled over <FxButton portion of the tag you would see the ASDoc content for just FxButton. Not only can you view content inline, there is now a ASDoc panel that can be added to you workspace layout. This panel automatically updates when you click on a property, method, class, tag or attribute. This way you can have the view up and accessing ASDoc content without having to wait for the rollover event.

The ASDoc feature also works within your own code. For example, if you are developing a custom Class and provide properly formatted ASDocs in the Class, the ASDoc window/tooltip will show your ASDoc notes whenever you reference your Class in the application. The Flex team is also working on a new SWC format nicknamed “Fat SWC”. This Fat SWC will now include all ASDoc notes that are provided in the source code for the SWC compilation. This means that when you use a “Fat SWC” in your project, you will get ASDoc hints for any of the Classes, properties, methods, tags or tag attributes that are contained within the SWC.

New Re-factoring Features

There are two new re-factoring features that were demonstrated during the session, both of which help automate tasks that developers do on a weekly, if not daily basis. The first feature is the ability to auto-generate a getter/setter pair from an existing property.

To use this feature you first select, or apply cursor focus, the property that you want to convert to a getter/setter pair. You can then either right click > source > Generate Getter Setter… or you can choose the Source > Generate Getter Setter… menu option. This brings up the above options dialog where you can decide if the existing property should become private, what the new name of the property should become (it defaults to a single underscore prefix), the name of the exposed get / set method, should it create both the get and set method, or just one or the other and finally where the new methods should be added.

This is one of those at first glance small yet super powerful features. During development there are many times where you need to convert a basic public property to a get/set pair and this helps write the code quickly and elegantly. One other cool thing to note about this feature is its ability to remember your preferred prefix. As I mentioned earlier, the default is a single underscore prefix for the private method. I personally prefer a double underscore prefix for my get/set value properties and when I added that additional underscore Flex Builder remembered this and kept the double underscore when I used the re-factor function again. Very, very cool.

The second re-factoring feature, isn’t really new, its just a lot more complete. When re-factoring the code-base, one of the biggest challenges is the process of moving Classes around to new packages. This may occur for all kinds of different reasons: better project organization, company name changes, project changes, etc. etc. Eclipse (which Flex Builder is built upon) supports the move option, yet in the current release this would just move the resource to the new folder and not update the Class’ package structure and linkage throughout the workspace. If you used the rename function, Flex Builder would handle all the updating for you, so it always felt as if the functionality was half-complete.

Well, now move is finally fully supported. This is great news for those of us that have had to spend five minutes moving resources and then the next hour fixing the compiler errors. Typically the process was move the resource, build the project, look for errors, updating bad references, re-build the project, looking for bad references, rinse and repeat. This can get really ugly when you have 800+ classes (which I have had in the past) and you are doing a massive project re-structure. Not fun, let me tell ya. When you choose to move an asset you get to choose what package to move it to and Flex Builder handles updating all the linkage references and package declarations.

One thing to note, in the current preview build of Flex Builder the package has to exist before you move the resource to it. If I recall, David Zuckerman mentioned that this will change in the future. Even if it doesn’t this is a great feature, one that I want NOW. It would have been soooo nice yesterday when I had to move a ton of MXML classes around and re-link them throughout the project, oh well.

Code Templates

Code templates are more or less self exactly what they sound like. A code template is similar to an email signature in that it provides the ability to auto-fill predefined content when a new MXML, ActionScript or CSS file is created. In a way, we have already been using Code Templates when we generate a new ActionScript class. The provided package structure, class declaration and constructor are all generated by the Code Template engine. The difference is that in the next version of Flex Builder this will all be exposed to you and fully modifiable.

Are you working on a MIT or other licensed project? You can now add the license block to the template code and any new file will have the proper structure. You can predefine code blocks, ASDoc blocks, code layout and preferred structures all within the code templates. You can also use variables that set time, file path, names, etc. into the template. On top of that you can export your created templates, pass them around and have others import the template into their Flex Builder. This is great if you work with multiple developers and want to create better coding standards or if you want to create company or open source project specific structures. Again, a simple yet very powerful feature that is being exposed to us.

Code Navigation

The last Test & Tune feature I am going to talk about in this post is code navigation. Code navigation shows a developer in code view what methods are overrides and implementations of interfaces. It also allows for quick navigation up to the parent reference when the triangle icon is clicked.

This is a nice feature because in the past you had to look at the Interface itself to determine what methods are implemented in the current class related. Overriding was generally easy to see at a glance because of the override keyword but getting to the parent method instance was not so easy. This feature enables both code readability and better navigation within the application.

Well, that is all for now. I have three more topics to write about, two more test & tune and then a look at the new Data service support. I will save those for the final post.

Aaron and I have a TON of notes and thoughts that are being worked on, all thanks to MAX North America. I am sure we will have even more coming from MAX EU. We will both be working on a ton of new posts over the coming few weeks and at the same time we are in the process of getting our DevelopmentArc site proper (don’t forget client work and other assorted projects we are working on too!). More to come on that later. So, for those of you in/from the States that celebrate T-day, enjoy! For those of you that don’t, no worries, you can laugh at us as we Americans stumble around in a triptiphane induced food coma.

Oh, and for those of you that read this blog for Flex/Flash/Technology info, read up on my newest obsession while I am away: Degrafa. Degrafa is short for “Declarative Graphics Framework” and it is a set of Classes that enable you to create simple to complex graphical content using MXML instead of having to write a bunch of ActionScript graphics calls. But that is just the tip of the iceberg, you can actually make component skins (states and all!) using their framework. Its rare for me to get this excited about a new framework, I am usually super hesitant about jumping in, but after a demo at the MAX Birds of a Feather, and now getting my hands dirty in it, I am super impressed. Good work guys!

I read a great analysis article by Grant Skinner, talking about the different Open Source licenses and how they can affect you and your client. I originally licensed the code library under the Mozilla Public License (MPL) due to its popularity, its freedom to allow developers to build on top of the code base for any purpose (free or for charge) and only requires code modification submission if the developer changed the original code in the library. My goal with VivMedia is to help developers build great applications, and the last thing I wanted to do is limit them, yet I do want to encourage people to submit changes and updates. That is why I went with MPL at first.

The issue with MPL (as Grant points out) is that when you use MPL code there are certain steps you need to take to release your project. In most cases this is not a big deal and it very rarely impacts the project but it may cause some developers or their clients a bit of grief. In all honesty, I just want to create a library that myself and others can use without having to jump through hoops with our clients. This lead me to change all the code license to MIT, which is very permissive of all forms of development. All you need to do is keep the MIT license headers in the source. You don’t have to submit changes (all thought I would be very happy if you did) and you don’t have to jump through any other legal hoops when deploying. So, if you are using the library already, update to the new version and know that the door is now wide open and you don’t have to fret about how you or your clients release the work.

The other addition to this version is the new Queue data structure. The Queue allows you to add and remove items is in a linear fashion. You can define the Queue as either Last in First Out (LIFO) or First in First Out (FIFO). What that means is when you add() item A and item B to the Queue and then call next(), the item returned is dependent if the queue is set to LIFO or FIFO. A LIFO Queue returns item B, since it was the last item added. A FIFO Queue returns item A since it was the first item added. As always, a full tutorial will be posted soon on how to use the Queue in your code.

The Queue is a building block for a lot of new functionality that I am starting to plan out. There will probably be variations of the Queue going forward too. For example a version that is designed to help solve Asynchronous issues in a Synchronous fashion, without you having to write a lot of logic around the actions. Right now, its all about what time permits… and as I said in the last post, vacation is nearly here! So, update/download the library, check out the ASDocs in the source (I always update them for each release) and let me know what you all think.

Overview
The SelectionController allows you to group items similarly to how a radio group works in both HTML and Flex. The general principle with a radio group is that when one radio button is selected, any of the other radio buttons in the group are then deselected. This kind of selection occurs in Lists, DataGrids, etc.

The challenge is that in a highly stylized Flash/Flex applications we often need to treat custom components as a group. One example is my Wordpress PhotoSlider. When a user selects a thumbnail, the selected thumbnail is highlighted and the previously highlighted thumbnail is deselected.

A typical solution is to make the parent container smart enough to understand when an item is selected and then let the parent change the highlight state. This approach can get tricky when you have items that are deeply nested and don’t share an easily accessible common parent or if you have complex selection/deselection requirements that may span across multiple containers or even have selected children that are currently off the display stack.

To solve the easiest issues to the most complex selection challenges I developed a SelectionController that is a Singleton instance that manages selection of content for you. Items first need to implement the ISelectable interface and then they can be added to a selection group. When you want to select or deselect a group you can either pass in the group ID or you can pass in one of the items in the group to handle selection.

Examples
First, lets look at our item that we want to be selectable and then we will look at how you can select/deselect the item.

package com.vivisectingmedia.tutorial
{
	import com.vivisectingmedia.framework.controllers.SelectionController;
	import com.vivisectingmedia.framework.controllers.interfaces.ISelectable;
 
	import flash.events.MouseEvent;
 
	import mx.controls.Button;
 
	public class MySelectionButton extends Button implements ISelectable
	{
		// constructor
		public function MySelectionButton()
		{
			super();
		}
 
		/**
		 * The default method for when a Button is clicked.
		 * We override this method so that when a user clicks
		 * on this Button we select this item and deselect
		 * all the other Buttons in the group.
		 * 
		 * @param event Click event.
		 * 
		 */
		override protected function clickHandler(event:MouseEvent):void
		{
			super.clickHandler(event);
 
			// this item is now selected
			SelectionController.selectItem(this);
		}
 
		/**
		 * This setter is called when the SeletionController
		 * changes the Button's selection state.  Technically,
		 * we do not have to override this method because the Button
		 * Class already supports the selected getter/setter signature
		 * required by the ISelectable interface.
		 *  
		 * @param value True is selected, false is deselected.
		 * 
		 */		
		override public function set selected(value:Boolean):void
		{
			// store the private reference
			super.selected = value;
		}
 
		override public function get selected():Boolean
		{
			return super.selected;
		}
 
	}
}

A couple of notes about the above code. As I mentioned in the comments, we don’t really need to override the get/set method for selected. The Button Class already meets the ISelectable interface requirement, but you will still need to extend the Button class to add the ISelectable interface so that it works with the SelectionController. I overrode the code just to show you how you would need to implement this in a component that does not already support selection states. What I really want you to focus on is implements ISelectable and the clickHandler() method.

In the clickHandler() call we pass up the super.clickHandler() and then we call the SelectionController.selectItem() passing the component instance reference in as the argument. What this is telling the SelectionController to do is first, see if the passed item is in a selection group, if so, select the item by setting selected to true, and then set selected value to false on any other item in the selection group. The SelectionController is friendly enough that if the item passed in is not in a selection group, then the item is still selected and nothing else happens.

So how do you leverage the selection object? Let’s look at some examples:

// create some selectable items
var buttonOne:MySelectionButton = new MySelectionButton();
var buttonTwo:MySelectionButton = new MySelectionButton();
var buttonThree:MySelectionButton = new MySelectionButton();
 
// generate an group id to assign them to
var groupOne:int = SelectionController.generateNewId();
 
// assign the items to the group
SelectionController.addItem(buttonOne, groupOne);
SelectionController.addItem(buttonTwo, groupOne);
SelectionController.addItem(buttonThree, groupOne);

This is the basic use case for grouping items. First, we use a helper method to generate a new group ID. The ID is an int and it must be unique for each group. The generateNewId() returns the next ID number not in use. Once you have an ID you can then add items to the SelectionController using the addItem() method. This stores the reference of the item and pairs it with the group.

Because the MySelectionButton is built with the SelectionController in mind we don’t have to do anything else if we want these three buttons to behave as a group. When a user clicks one of the buttons in the group, the clickHandler calls the SelectionController and the SelectionController will then select the clicked button and deselect the rest.

What happens when you want to programatically select one item, or all of the items in the group or deselect all the items in the group? The SelectionController provides methods to handle these tasks:

// select one item
SelectionController.selectItem(buttonTwo);
 
// select all the items, first get the group if
// you don't know it
var currentGroup:int = SelectionController.getItemGroup(buttonOne);
 
// now select the group
SelectionController.selectAll(currentGroup);
 
// or you can deselect them all
SelectionController.deselectAll(currentGroup);

Considerations and Gotchas
As with all my tutorials, lets talk about things you should consider/know about the SelectionController that may cause you some trouble if you attempt to do certain things.

One group to an item. Selectable items can not be members of multiple groups and when a new group is applied the item is removed from the original group. For example:

// create a new group
var groupTwo:int = SelectionController.generateNewId();
 
// apply the group to ButtonTwo
SelectionController.addItem(buttonTwo, groupTwo);

Doing the above would remove ButtonTwo from groupOne and when you call selectAll() on groupOne only buttonOne and buttonThree would be selected.

Items are Strong referenced. When an item is added to a group it is strong referenced in memory. This means that if you want to delete the item so that Garbage Collection can be applied you need to remove the item form the SelectionController by calling removeItem(). This removes the item from the SelectionController and Garbage Collection can be applied when the next pass occurs.

Multi-Select is supported by not built in by default. If you want to create a multi-selectable grouping you can use the SelectionController for this kind of functionality, but you will need to add more logic to you selectable items. For example, we want our MySelectionButton’s to be multi-selectable when a user has the Control/Command key down. To do this in our example you would modify the clickHandler() like so:

override protected function clickHandler(event:MouseEvent):void
{
	super.clickHandler(event);
 
	if(event.ctrlKey)
	{
		// do not select using the controller
		this.selected = true;
	} else {
		// do select using the controller
		SelectionController.selectItem(this);
	}
}

The above example determines if the user is multi-selecting by checking the ctrlKey value in the MouseEvent. The MouseEvent passes true if the key is down and false if the key is up. In the case when the key is down we want the object selected but we don’t want the Controller to deselect the rest of the items in the group. Otherwise, we do want the rest of the items to be deselected, so use then use the Controller.

That is the basics of the SelectionController, play around with it and let me know if you need more examples, find any issues or have any questions with the Controller.

One of the challenges of writing an article like this is first defining your audience and then determining how to cover the topic in the alloted text. The Edge sets a word count guideline and this limits how deep I could or in this case could not go. Personally, I fully support the word count guide because this both focuses the topic and generates more digestible articles. Yet, on a topic as broad and as deep as this one I had to focus more on an introductory guide to coding standards and adoption.

The second challenge is determining your audience. My goal was to create an article that worked for both readers who have never heard of coding standards, and readers that have been using them for years. I always try to create a broad stripe across my reader base because I want to inform as many people as possible. This thought process was kind of beaten into me during my years as a Technical Support rep and team-lead at Macromedia. There is nothing like having to write Tech-notes and email support to teach you how to write to a broad audience.

The main point I wanted to get across with this article is that coding standards are actually much more then just code formating. Code formatting, or code conventions, really focus on how you name variables, methods, classes, etc. Yet, this is just the tip of the coding standards iceberg. One of the least discussed aspects of coding standards is the adoption and implementation practice of code design patterns. As developers, we need to better understand how adoption of patterns, frameworks and micro-architectures help structure our code. Not only do they provided rapid development but they also help guide us into a more structured development process.

As RIA and web application development expands we are seeing a demand for much more complex and scalable applications. Scalability is not just about user load but includes further expansion of features and performance over time. More and more developers are being asked to create applications that have a lifespan longer then just a few months. Some people may gaffe at that comment, but if you look at a lot of “rich” applications up to this point, most have been for marketing campaigns and advertising. The nature of these kinds of projects do not focus on lifespan and version updates. Their focus is on making them work in a short time to meet the marketing deadline and then get them out the door.

With the trend of Web 2.0 (which I hate as a term), the web world is quickly being pushed into the long standing Desktop Software model. This is forcing a lot of us to re-evaluate how we design and develop our online enabled applications. This is a scary yet wonderful time in our industry as we are rapidly adopting and developing new ways of web application design and construction. Due to this push I feel its time to help expose more of us to coding standards. My article is more a call to arms then a definitive guide to coding standards implementation. If you are interested, take a read and add your thoughts to the comments…

The big change is this version is the addition of the new SelectionController and ISelectable interface. The SelectionController is a manager that allows you to group any number of items that implement the ISelectable interface and then treat them as a Radio Group or multi-selectable group. With the controller you assign items to groups and then you can use the controller to select and deselect the items.

A great example of this code is how I handle image highlighting in the Photoslider. Each of my image thumbnails implement ISelectable and then when a user clicks a thumb it calls the SelectionController.selectItem() and passes itself as an argument. The SelectionController then sets selected on all the thumbnails in the group, setting true for the passed in item and false for the rest. I plan on doing a full tutorial in the near future so keep an eye out for it. Enjoy!

What Is a Singleton?
If you have never heard of the Singleton Pattern you are not alone, I know many senior Java and ActionScript developers that looked at me blankly when I brought up the pattern in passing. The core idea of the pattern is to solve the issue of when you need only once instance of an object that can be accessed globally in you application.

For example, you have a User object that stores the user information once they are logged in. Throughout your code you want to use this information and you also want to make sure that there is only once instance of this user data. One solution is to pass around a value that represents the user, yet there are many issues with this kind of approach. First, the code needs to understand this data and expect it when called. Second, what happens if the user logs out or changes the data, such as their address? The code needs to know this the next time its called. Passing it around gets ugly very very fast.

Another solution is to save the values in a global variable. But where should this live and how should it be accessed? Does it live in _root (really, really bad idea) or the top Application? What happens when your code gets nested in another application or is modularized? How can you find the data? This is where the singleton comes in. The Singleton pattern leverages the power of static properties and methods which are bound to the Class type itself. What!?! Let me show you:

package com.vivisectingmedia.example
{
	public class User
	{
		public var name:String;
		public var address:String;
		public var birthDate:Date;
	}
}

So there is our basic user class. Its just a simple data object class that stores our information. In most cases we create a new instance of it and then start manipulating it, such as:

var loggedInUser:User = new User();
loggedInUser.name = "Bob";
loggedInUser.address = "123 Market St.";
loggedInUser.birthData = new Date(1976, 4, 6);

In the above example we are working with an instance of a class. We used the constructor to generate the instance and we are manipulating the properties of that instance. In ActionScript 3.0 we can leverage the static keyword to define properties on the class itself:

package com.vivisectingmedia.example
{
	public class User
	{
		static public var name:String;
		static public var address:String;
		static public var birthDate:Date;
	}
}
....
 
// we now access the name value through the Class, not an instance
User.name = "Bob";
User.address = "123 Fake St.";
User.birthData = new Date(1976, 4, 6);

Those values are being set on the Class not on an instance. This means that when you change values in one part of the code and then access the class in other parts of the code the stored values are the same. In a way we have just defined a global data object that stores our user data. The Singleton pattern takes the ability to store values on the Class and then steps it up a notch.

In theory we could go in and mark EVERYTHING static but this is not ideal and can lead to complications. The better way is to create a hybrid of the first User class example and the second. We do this by exposing a static method on User that checks if an instance of User is created and if not creates one and then returns it. This part of the Singleton is kind of a mind-bender so lets just jump into code.

Defining Singletons in ActionScript
The core idea of the Singleton is to have static helper methods that manages our object instance by allowing only one instance to exist and also provides access to this instance. Using the User example (above) here is a complete Singleton which also follows the extendable pattern. Don’t worry if you don’t get all of it on the first pass, I will break it down step by step later.

package com.vivisectingmedia.example
{
	public class User
	{
		// stores our instance
		static private var __inst:User;
 
		// standard public properties
		public var name:String;
		public var address:String;
		public var birthDate:Date;
 
		// accessor for the instance
		static public function get instance():User
		{
			if(!__inst) __inst = new User(generateLock());
			return __inst;
		}
 
		// accessor for our SingletonLock
		static protected function generateLock():SingletonLock
		{
			return SingletonLock;
		}
 
		// our constructor, must be public in AS3
		public function User(lock:Class)
		{
			if(!lock is SingletonLock)
			{
				throw new Error("Invalid use of singleton.");
			}
		}
 
		// add public methods and such here
		public function get age():int
		{
			// calculate age and return it
			...
		}
 
		...
	}
}
 
class SingletonLock
{
	public function SingletonLock()
	{
 
	}
}

Let’s break this down step by step. First of all lets look at the static property __inst and the static method instance(). These two parts are the most important aspect of the Singleton pattern. So what are we doing in instance()? The first thing to notice is that the instance() method is both static and a getter with no setter which makes it read-only. We would use it like this:

// set the user's info and call the age() method
User.instance.name = "Fred";
User.instance.address = "123 Mission St."
User.instance.birthData = new Date(1978, 5, 14);
var age:int = User.instance.age;

What happens is we call the instance() method through the class reference of User, the instance() method then looks and sees if the __inst property is currently storing an instance of User, if not then we create a new instance of User, save it in __inst and then return the reference. This means the the second time we call instance on the User class, we have already created the instance of User and we just hand back the reference. That’s the magic of the Singleton right there, we now only have one instance of the class that is created exactly once and is created at the time you need it. You don’t need to worry about creating it in onCreationComplete() or in the Document class. The first time you access it the item creates itself. Pretty nifty, eh?

So what is all the other crap that is in this class? The rest of the code is both designed to help enforce Singleton usage in ActionScript and allow extending of the Singleton Class.

Protecting Singletons in ActionScript
One of the current limitations of AS3 is that constructors have to be public. In languages like Java they can be marked protected but not in AS3. This is being resolved in the ECMA 4 standard so when the new version of AS comes out we will not longer have to put all this enforcement code in.

Because constructors are always public there is nothing stopping a developer from ignoring the static instance getter and just creating an instance of the User class locally. This is a bad thing because we now have multiple instances of the object and this defeats the Singleton pattern. To help enforce this we use the SingletonLock as a special key that prevents the constructor from being used EXCEPT in instance() call and/or the extension process (more on extending later). Let’s look at the constructor again:

// our constructor, must be public in AS3
public function User(lock:Class)
{
	if(!lock is SingletonLock)
	{
		throw new Error("invalid use of singleton.");
	}
}

You will notice that the constructor expects one argument of type Class and then checks to make sure the passed in Class is of type SingletonLock, if not we throw an Error. SingletonLock is an internal class that is ONLY available to the User Class. We expose this class through a method called generateLock() which hands back the Class reference to the internal Class. The instance() method uses generateLock() to create the lock and pass it on to the constructor. By setting this structure up we have created an enforcement policy that only allows Classes with access to generateLock() to create an instance of the class. Take a moment to go back and walk through the entire User Class to make sure you understand this creation flow.

Its seems like overkill, but this kind of code is very important when working with open source projects or large teams. It forces developers to follow the pattern and prevents improper use of a Singleton based class. As I mentioned earlier this is only because AS3 does not allow protected or private constructors. In the future we can throw all this enforcement code away, but for now we should use it.

Extending A Singleton
Now that we have the Singleton how can we extended it and why would we ever want to? Very rarely would you want to extend a Singleton but it does come up. For me, the number one reason I want to extend Singletons is for automated unit testing.

Here is the situation: I have a series of unit tests that I want to run and each of the tests need to assume a clean instance of the Singleton exists. The challenge is that the tests all run in the same instance of the application (FlexUnit) and therefor the Singleton is created on the first test and the second test is now manipulating the previously created Singleton. Very bad for a testing environment.

One solution is that we expose a reset() method on the Singleton that enables the unit test to reset the Singleton instance. This is a bad approach because we really don’t want to expose this public method in the live version because we want to prevent users for resetting the Singleton, this reset() method is only for testing purposes.

The ideal solution is to extend the Singleton in the Test Suite and add the reset() method which is called on tearDown(). The test would use the extended instance so we are now able to verify the core Singleton functionality and still get reset() without exposing it for the deployed version. Here is how we would create a TestUser that extends our User example:

package com.vivisectingmedia.example
{
	public class TestUser extends User
	{
		// stores our instance
		static private var __inst:TestUser;
 
		// accessor for the instance
		static public function get instance():TestUser
		{
			if(!__inst) __inst = new TestUser(generateLock());
			return __inst;
		}
 
		static public function reset():void
		{
			__inst = new TestUser(generateLock());
		}
 
		// our constructor, must be public in AS3
		public function TestUser(lock:Class)
		{
			super(lock);
		}
	}
}

What changed? First we still define the static private instance but we type it as TestUser. The value has to be private because the __inst has to be specific to the Class its defined in. Remember that static properties and methods are bound to the Class itself. Things get a little tricky here so let me see if I can explain it.

We could try and set __inst as protected property on the User class. When the user calls instance() on TestUser we could create the TestUser instance, store it in the the protected __inst version on User since TestUser is a User. We could then cast __inst as a TestUser for the return call.

// accessor for the instance
static public function get instance():TestUser
{
	if(!__inst) __inst = new TestUser(generateLock());
	return TestUser(__inst);
}

The problem with this approach is that if you called User.instance first then tried TestUser.instance you will get an error because __inst is holding the User instance and User can not be upcasted to TestUser. The solution is to keep the __inst separate in each Class to prevent this possible issue. The added benefit is that you can have a User instance and TestUser instance living side by side which is awesome if you are extending the Singleton for other purposes.

The next thing we did is redefined instance(). Notice how I did not have to use override? Static methods are bound only to the Class and not any children that extend the Class. We have to redefine it to expose it on TestUser. Also, notice that the code is creating a TestUser and passing in the parents protected generateLock() call. Make sure to look at how we changed the constructor. We still expect the lock and we pass the generated lock on the to the super call.

This is exactly why we use a generateLock() method and pass a Class reference around. Up to this point a lot of developers (myself included) used the following style for defining the constructor:

// accessor for the instance
static public function get instance():User
{
	if(!__inst) __inst = new User(new SingletonLock());
	return __inst;
}
 
// our constructor, must be public in AS3
public function User(lock:SingletonLock)
{
	...
}

The issue with this structure is that you can not extend User because the constructor signature requires knowledge of the SingletonLock class which is an internal class of User and therefore only User can access it. By replacing the lock as a Class we can still secure the Singleton by validating the passed lock but we can easily extend it since we are expecting type Class in place of type SingletonLock.

Now that we have fully extended out Class we can add our reset() method which then overwrites the __inst. That’s how you can build and extend singletons in ActionScript. As always please let me know if you see any errors or have any questions about how this all works.

The ArrayCollection is much more then this too. It also has the ability to tie directly into FlexData services and then dynamically page the data into the ArrayCollection instance as data is requested. The ArrayCollection is also the complex data structure that is generated by the HTTPService (when parse to Object is set) if you have more then one child node in an XML structure. If you haven’t used it yet, the ArrayCollection is a very powerful data-structure.

Of course, with this robustness comes limitations. First off, its Flex only. This means that if you are used to Flex development but find yourself on an AS3 only project, you can’t use the ArrayCollection. Another big one is performance. As you begin filling the ArrayCollection up, queries into the data structure start to slow down, and I mean significantly slow down. If you have hundreds of objects in the ArrayCollection, the performance for lookup and access are way slower then just looping over an array and finding it the old fashioned way. A more minor issue is when trying to manipulate data dynamically you start having to write some pretty ugly code such as to prevent null reference errors:

// remove the item if it exists
if(myCollection.contains(objectNeeded))
{
	myCollection.removedItemAt(myCollection.getItemIndex(objectNeeded));
}

Its not that bad, but as you get more and more complex accessing structures you start longing for the simplicity of an Array. This is where the HashTable came into the picture. I wanted something that performs like an Array, yet has the API data accessors that can simplify development. Yet, there was one more thing that I wanted, the ability to map key’s to values like in an object or Dictionary but still maintain Array like access.

From this need came the HashTable. In the past I had built multiple solutions similar to the HashTable but they typically where one-offs that lived in the code the functionality was needed. I never got around to formalizing it into a proper data-structure. I finally got the chance and built it from the ground up for my Photoslider app. So, let’s talk about the HashTable…

Using The HashTable
The HashTable is an ActionScript 3.0 data structure that is not dependent on any of the Flex SDK, this means you can use it freely in both Flash and Flex projects. The HashTable, simply put, is two Arrays which are wrapped in logic to provide a simplified data access API for development. Its not complex, but it can cut out a ton of code that you would typically write over and over.

The main thing to know about the HashTable is that everything revolves around a key/value pair. The key can be anything, from a number to a complex object. When you add an item to the HashTable you define this pairing:

// create a key (person) and item (friends)
var person:Object = {name: "James"};
var friends:Array = [{name: "Eno"}, {name: "Aaron"}, {name: "Doug"}, {name: "Dave"}];
 
// create the table
var hash:HashTable = new HashTable();
hash.addItem(person, friends);
 
...
 
// get my friends
var myFriends:Array = hash.getItem(person) as Array;

As you can see from the example, we can use an Object as a key and then bind another complex object to the key. Later on we can retrieve the item by simply requesting the item by providing the key. Not only can we access via the key, but we can also get all the keys and then retrieve their data. For example, we now have multiple people in our HashTable and we want to get all their friends:

// get all the people and loop on them
var people:Array = hash.getAllKeys();
var len:int = people.length();
for(var i:uint = 0; i < len; i++)
{
	var friends:Array = hash.getItem(people[i]) as Array;
	...
}

Not only can you get all the keys but you can also get all the items by using getAllItems(). There are also other accessors that can help you along the way. Such as:

// how many key/items are in the HashTable
var numberOfItems:int = hash.length;
 
// do we have any items
if(!hash.isEmpty)
{
	// do something
	...
}
 
// is the key or the item in the table?
if(hash.containsKey(person) || hash.containsItem(friends))
{
	// do something
	...
}
 
// we can also remove key pairs
hash.remove(person);
 
// or clear the entire table
hash.removeAll();

Things to Consider When Using the HashTable
If you read my EventBroker post or my Code Behind Pattern post then you know I like to point out any possible gotcha’s when using code. I feel this is very important because if the issues are raised in the beginning it makes the life of the developer a hell of a lot easier. Here are a few nuggets to consider when using the HashTable:

• The HashTable uses an Array under the hood so this means items are strong referenced. Make sure to remove the items from the HashTable before you decide you no longer need the items in you application and want the Garbage Collection to clean them up.
• When using the getAllKeys() or getAllItems() you are being handed back a clone of the internal Array. If you want to change the value in the HashTable you will need to overwrite them by updating the HashTable. Note: The current version (0.01) of the Framework has a brute force clone in the HashTable. I was a little for loop happy and this has been fixed locally and will be available in the SVN soon. Version 0.02 of the framework will have this fix. Its nothing to worry about, I just prefer more elegant code and wanted to note this for the few of you that will poor over my code (Aaron, Eno and Dave!)
• You can have the same object multiple times in the HashTable if it is an item, but only one instance as a key. This means that if you have the object “person” as the key to item “friends”, and then try to addItem(person, friendsTwo) then “friends” will be replaced with “friendsTwo” within the table. This is silent and allowed. Key’s must be unique otherwise you overwrite.

That should be all… if you find anything, want more examples or event want new features let me know!

Events In the Flash Player
Before I give some examples for when to use the EventBroker, let me take a minute to talk about the Event model within the Flash player and some of the possible limitations that can occur within this model. The Flash Event Model is based around the classic broadcaster/listener pattern. A broadcaster is responsible for dispatching an Event object when a certain action occurs. A basic example is a Flex button and the button’s click Event. When the user clicks on the button in a running Flex application the button dispatches a click Event. This Event is designed to inform other objects that the click action has occurred.

For an item to receive the click Event notification the listening object registers to the Event via the addEventListener() method which is a public method on the button. When the object that wants to listen to the click event, the object calls addEventListener(), passes in the type of Event (ex: MouseEvent.CLICK) and what method to call on the listener when the Event is dispatched (ex: handleClickEvent()).

Going back to our example, let’s say our button is the play button for a video player and we want the video object to “listen” for the click Event. During setup, the video object would register to the play button using addEventListener(). When the user clicks the play button the button looks up all the items that have registered for the click Event and then calls the methods that were provided by the addEventListener() call.

// setup code for our video object
public function videoInit():void
{
	playButton.addEventListener(MouseEvent.CLICK, handleClickEvent);
}
...

The issue with the above example is that the Flash Event model assumes we know about or have access to the Play Button. In 7-out-of-10 cases this is true, but there are situations where we don’t know where the Event broadcasting object is. The Flash Event model does provide another solution called Event Bubbling. When an object dispatches an Event and the Event is marked to Bubble then the Event will be passed up the parent/child hierarchy until it is either captured or reaches the top of the stack. Let’s say we have a UI where the Play Button is a child of an HBox. If the Video element is outside of the HBox but is within the parent wrapper of the HBox then the video object can register to the HBox for the click Event if the event is set to bubble. When the Click event is dispatched it will be passed to the parent and the parent will then dispatch the event which our video element would receive.

<mycustomui:VideoWidget id="my_video_widget" />
<mx:HBox>
	<mx:Button id="playButton" />
</mx:HBox>

Challenges with the Flash Event Model
Unfortunately, the click event does not bubble by default and this puts the developer into a conundrum. Does the developer need to add a router method to the parent class that knows of the existence of the play button and therefore can route the play button’s events? Does the developer expose the play button and allow the Video Widget to know where it exists and therefore register to it? In most cases, exposing the play Button is not a bad thing and is the desired solution but there are exceptions.

What happens if the play Button is nested deep with in multiple components? What happens if the play Button is within a Module that may not be loaded at the time of the Video Widget initialization? What if you have n number of modules that all need to know when the video starts playing? What happens if the button is dynamically created and the location is not known until creation and the listener is in a different module or location that may or may not know of the generated button? This is were things start getting really interesting and why I created the Event Broker.

A great solution, one that is used in Cairngorm, is to create a controller that is designed to route events to the proper listener. This solution is called the Observer pattern, where the controller “observers” a dispatcher and then routes the event to the proper location. This is a great pattern but the last examples I saw in Cairngorm required the developer to keep adding events to the controller as they are required. Note: Its been a while since I have worked with Cairngorm so this process may be automated now, it if is let me know. The EventBroker takes the Observer pattern and moves further into a more flexible solution by automating how objects can register and dispatch events.

What is the Event Broker
The EventBroker is a Singleton Facade that enables any object located in the application to register to any other object’s events that are dispatched through the EventBroker. The EventBroker is a completely duel opt-in system which means that both dispatcher and listener must use the EventBroker as the Event routing system for it to work. Also, because the EventBroker is a singleton, you do not instantiate the EventBroker. You just call the static methods subscribe(), broadcast() and unsubscribe() directly off the EventBroker class.

Using our play Button example, let’s walk through how to enable the EventBroker:

// the playButton's parent init() located in
// one part of the application
public function videoControlInit():void
{
	playButton.addEventListener(MouseEvent.CLICK, handleClickEvent);
	...
}
 
// used to re-dispatch the click event through the EventBroker
protected function handleClickEvent(event:MouseEvent):void
{
	// re-casting the event so that it is specific to the action
	var playEvent:Event = new Event("PLAY");
	EventBroker.broadcast(playEvent);
 
	doSomethingElse();
}
 
...
 
// this code is in another component/module that is completely unaware
// of the playButton
public function widgetInit():void
{
	EventBroker.subscribe("PLAY", handlePlayEvent)
}
 
protected function handlePlayEvent(event:Event):void
{
	// do something
	...
}

For our example, we first need to register to the play button’s click Event to call the handleClickEvent() method because this is a built-in event within the button type. If we created a custom component or object we could have the component cut out the middle man and directly jump to the EventBroker, but this example shows how to handle pre-existing events.

In the handleClickEvent() we re-cast the event to a new “PLAY” type. We want to do this because the user clicking on the playButton is really calling an action. We could, in theory, re-dispatch the click event to the EventBroker but the listeners would need to know that when a click event is broadcasted the code needs to look at the currentTarget and determine if it is set to “playButton” which would call the play action defined in the listener. Its just easier to define a new Event Type the represents the global action and use this as the Event. To broadcast the event we just call broadcast, very similar to the EventDispatcher’s dispatchEvent() call.

Now, in the Widget’s init() code we call the EventBroker’s subscribe() method and pass in the event type we want to listen to and what method to call. The method provided should always take one argument with the type of Event.

So in our example, this is how the EventBroker works. When the wigetInit() is called it subscribes to the “PLAY” and registers the handlePlayEvent method. The EventBroker stores the type and method closure in a lookup table. When the playButton dispatches the click event the handle method calls EventBroker.broadcast() passing the “PLAY”. The EventBroker looks up any objects that are currently registered to this type and then passes the event to the provided method closure, in effect calling our handlePlayEvent() on the Widget.

By using this process, we have virtually removed all cross-dependancies of the Widget and the playButton and they can be moved around, loaded independently, etc. without breaking our application’s functionality.

When you no longer want to listen to an Event, call the EventBroker’s unsubscribe() method passing in the Event type and the method closure. This then removes the paring from the EventBroker’s table and any further call to broadcast() will be ignored for the unsubscribed object.

Things to consider
The EventBroker is a very helpful tool but should be used sparingly due to some potentially challenging issues. First off, when an Event is broadcasted all subscribers are called. This doesn’t sound harmful unless you consider the following use case. Let’s say that you have four widgets. Each Widget broadcasts a “DATACHANGE” Event when the user changes something within the Widget. All the Widgets subscribe to the “DATACHANGE” event so that they can update their content based on the user’s action. We want all the widgets to be independent and have no direct linking to each other so the EventBroker is used.

Here is the challenge, when Widget Foo dispatches “DATACHANGE”, Widget Foo will also get its own “DATACHANGE” event. This means that the Widgets has to be self-aware enough to know when it is dispatching an event that it is also will receive the event. This means that code has to be added to ignore the incoming event for that specific case. Otherwise you may have some really nasty recursion.

I have looked into having the EventBroker try to ignore self calls but there is not a way for ActionScript to determine the callee of the method is the same instances as the closure in the registered subscribers. Also, there are cases where you may want the callee to call itself. So, just be aware of this issue.

The other thing to consider is that the EventBroker is NOT using the Flash Event model and there for is considered a synchronous action. This means that when the broadcast() method is called Flash calls all the subscribed methods before calling the next line after the original broadcast() call. In our example code this means that all the code in handlePlayEvent() on the Widget will be completed before the doSomethingElse() call is made in the handleClickEvent() for the button.

This is an import difference then the dispatchEvent() call because the Event propagation system in Flash happens after the current synchronous functionality is completed. In 99.9% of cases this is not an issue but there are edge cases that may arise due to this. So keep this in-mind during the debugging process.

Finally, the EventBroker is strong referenced and therefore you should ALWAYS unsubscribe listeners before you delete them. If you do not unsubscribe you will have a strong reference and the Garbage Collection will not clear them from memory. This is very, very important to remember for larger applications that are adding / removing objects dynamically.

So that’s the EventBroker… let me know of you like it or see any issues when using it!