The Hard Limit approach

The first attempt I made at the N-gleton was to simply throw an error when the class had been instantiated too many times.

package {
	public class NGletonHardLimit {
		protected static var maxInstances:int = 3;
		protected static var numberOfInstances:int = 0;

		public function NGletonHardLimit() {
			if (numberOfInstances >= maxInstances) {
				throw new Error ("There can only be " + maxInstances + " instances of this class");
			}
			numberOfInstances++;

			// initialize code
		}
	}
}

This was shortly followed by a slightly more friendly version of the same idea…

package {
	public class NGletonRequestInstance {
		protected static var maxInstances:int = 3;
		protected static var numberOfInstances:int = 0;

		public static function requestInstance():NGletonRequestInstance {
			if (numberOfInstances >= maxInstances) {
				return null;
			} else {
				return new NGletonRequestInstance(new Key());
			}
		}

		public function NGletonRequestInstance(key:Key) {
			// initialize code
		}
	}
}
class Key {}

However, I soon realized that this method is quite flawed in its logic. The counter is actually just counting the number of times the requestInstance() method is being called rather than truly controlling the number of instances of the class. It also doesn’t allow you to release an instance and decrement the instance count. Perhaps something like this would work in C where you can use alloc and dealloc but for Flash, it doesn’t really make sense. Besides, It doesn’t really seem useful.

Cycling through instances

Next, I tried looping through the same limited set of instances. Each time you request an instance you get a new one until you’ve reached your limit, then it starts over with the first instance again.

	package
	{
		public class NGletonLoop
		{
			protected static var maxInstances:int = 3;
			protected static var numberOfInstances:int = 0;
			protected static var instances:Array = [];

			public function NGletonLoop(key:Key) {
				// initialize code
			}

			public static function requestInstance():NGletonLoop {
				var n:int = numberOfInstances++ % maxInstances;
				if (instances[n] == null) {
					instances[n] = new NGletonLoop(new Key());
				}
				return NGletonLoop(instances[n]);
			}
		}
	}
	class Key {}

This approach just felt wrong. In fact, it was totally stupid. There is no way to know what you’re going to get when you request an instance and it seems like it would be very easy to overwrite data without even knowing it. You still have the problem of the instantiation being counted rather than the actual objects. Besides, it’s really totally useless.

It was looking like the whole idea of an N-gleton may not really have a practical application. But in the name of theoretical computer science, I chose to press on and try one more idea I had.

Tracking individual instances

The previous idea of storing instances in an Array seemed to make some kind of sense to me but it was missing individual control over the instances. So I decided to try using an index to track the instances. I soon realized that a Dictionary that uses objects as keys might give a more useful identifier than an integer. The maximumInstances didn’t really make sense any more so I took it out. I seemed to be onto something but it wasn’t really the N-gleton I had imagined, it was something more useful. I called it an IndexedObject.

	package {
		import flash.utils.Dictionary;

		/**
		 * An example of a class that tracks multiple individual instances by using a dictionary.
		 */
		public class IndexedObject {

			/**
			 * Stores the actual instances of the class.
			 */
			protected static var _instances:Dictionary = new Dictionary(false);

			/**
			 * The identifier that the dictionary uses to reference this instance.
			 */
			public function get id():* { return _id; }
			protected function set id (id:*):void { _id = id; }
			protected var _id:*;  

			/**
			 * Gets an instance of the class. Similar to how a singleton would get the
			 * instance but uses an identifier token to specify which instance to get.
			 */
			public static function getInstance(id:*):IndexedObject {
				if (_instances[id] == null) {
					_instances[id] = new IndexedObject(new Key)
				}
				var instance:IndexedObject = _instances[id] as IndexedObject;
				instance._id = id;
				return instance;
			}

			/**
			 * Returns all of the created instances as an array.
			 */
			public static function get allInstances():Array {
				var array:Array = [];
				var obj:IndexedObject;

				for each (obj in _instances) {
					array.push(obj);
				}
				return array;
			}

			/**
			* Removes an item from the list of instances.
			* Actually, doesn't quite work because an instance referenced by a variable
			* outside of the class could still hold a reference to the deleted instance.
			*/
			public static function deleteObject(id:*):void {
				delete _instances[id];
			}

			/** Just used for testing */
			public var name:String;

			/**
			 * Constructor can't be used by outsided classes.
			 */
			public function IndexedObject(key:Key) {
				// Initialize code
			}
		}
	}
	class Key{}

So essentially what’s happening here is the Singleton’s getInstance() method is being replaced with one that allows you to specify a particular instance. Any class could create new instances or access the same instances provided they had the same id. Here’s a little demo. I’m using a name property to show the example.

	var thing:IndexedObject = IndexedObject.getInstance(5);
	thing.name = "thing 5";

	thing = IndexedObject.getInstance("foo");
	thing.name = "thing foo";

	for each (var obj:IndexedObject in IndexedObject.allInstances) {
		trace("IndexedObject.getInstance(",obj.id,") =", IndexedObject.getInstance(obj.id).name);
	}

Results in:

IndexedObject.getInstance( foo ) = thing foo
IndexedObject.getInstance( 5 ) = thing 5

Voila. The “indexed object”. I think for me the jury is still out on whether this is a good idea. It seems like it might be kind of a hack since it, like Singleton, is essentially just a complicated implementation of global variables but even more so and without Singleton’s benefits. It also intuitively feels like it could be very useful. Either way, I’m proud of it.

So what do you think? What would you use this for? Is it a hack? Pattern or anti-pattern?


getNumberAsHexString(255); // 0xFF
getNumberAsHexString(0xABCDEF); // 0xABCDEF
getNumberAsHexString(0x00FFCC); // 0xFFCC
getNumberAsHexString(0x00FFCC, 6); // 0x00FFCC - Uses 6 as a minimum number of hexits

I’ve added the code to the AS3lib as  as a global function. I may move it to a utility class later on. You can view the source on Google Code.

Incidentally, in a moment of bug-fixing frustration, I found this article on O.C.A.S. which describes how the same functionality is already built into the toString() method! However, the work isn’t completely wasted since my version includes the option to show leading zeroes and adds “0x” at the front of the result.

My current configuration is Mac OS X 5.2 + TextMate 1.5.7 + Flex SDK 4.0.0.3504. I have two shell scripts in place:

1. /usr/bin/mxmlc
2. A TextMate run bundle set to a hotkey, “command + R”
3. I’ve also have my Flex SDK set to the absolute path of: /Developer/SDKs/Flex/4.0.0.3504

This configuration requires a flex-config.xml in the same directory as the AS3 class file that you’re compiling. When you run the TextMate script (or something similar in your Terminal shell) it will compile the filename you pass in and default to using a config.xml which acts as a local flex-config.xml file. All of these can be customized as needed.

Example Flash 10 3D cube rotation:
[kml_flashembed movie="http://www.calebjohnston.com/storage/fl10_examples/01_cube_rotation/CubeRotationExample.swf" height="260" width="410" bgcolor="#FFFFFF" /]

Obviously, the above swf won’t work without Flash player 10 installed.

Download the source here.

Take this FLA animation.

As you can see, there is a simple animation using a guide layer and labels on the key frames.

The following SWF uses KitchenSync to control the same ball animation. As you can see, the duration and easing functions of the animation can be controlled. You can even animate backwards!

See it in action.

The source that controls this is here.

package {
	import flash.display.MovieClip;

	import org.as3lib.kitchensync.KitchenSync;
	import org.as3lib.kitchensync.action.*;
	import org.as3lib.kitchensync.action.tweentarget.*;
	import org.as3lib.kitchensync.easing.Bounce;
	import org.as3lib.kitchensync.easing.Cubic;
	import org.as3lib.kitchensync.easing.Linear;
	import org.as3lib.kitchensync.easing.Oscillate;

	/**
	*	Demos the TimelineController which controls the animation of a MovieClip's timeline.
	*/
	public class FlashIntegrationTest extends MovieClip
	{
		protected var test1:MovieClip;

		public function FlashIntegrationTest()
		{
			super();
			// initialize kitchensync.
			KitchenSync.initialize(this, "1.5");

			// add a movieclip from the library
			test1 = MovieClip(new AnimationTest1());
			addChild(test1);

			// define the start and end frame with strings or ints or FrameLabel's
			var startLabel:* = "start";
			var endLabel:* = "end";

			// set up the TimelineController tween target.
			var tweenTarget:TimelineController = new TimelineController(test1, startLabel, endLabel);
			// Animate the ball with a linear ease.
			var tween:KSTween = KSTween.newWithTweenTarget(tweenTarget, "1s", 0, Linear.ease);

			// animate the ball backwards with a bounce tween
			var tween2:KSTween = tween.cloneReversed();
			tween2.duration = "4s";
			tween2.easingFunction = Bounce.easeOut;
			tween2.addTrigger(tween);

			// animate the ball with an oscillator
			var tween3:KSTween = KSTween.newWithTweenTarget(tweenTarget, "10m", "1s", Oscillate.sine);
			tween3.easingMod1 = 0.3;
			tween3.addTrigger(tween2);

			// start the animations
			tween.start();
		}

	}
}

Pretty cool huh? We’re creating a new TimelineController and setting the boundaries of the animation then passing it to a new KSTween object. Each of the three tweens use different parameters and are triggered by the end of the one before it.

You can download the entire thing and play around with it.

• Improved performance (50% faster!)
• Filter tweens
• Tween MovieClip animations on the timeline
• Use a KSSequenceGroup like a function queue

I’ll be posting some demos over the following days. In the meantime, check it out!