You may run into situations where you wish to batch commands. Macrobot simplifies this process and provides two ways to batch commands:

Sequence: The batch of commands will be executed in order. The second command will not be executed until the first is complete, the third command will not be executed until the second is complete, and so on. The batch will not be complete until all its commands are complete.

Parallel: The batch of commands will be executed as quickly as possible without respect to completion of any of the other commands. The commands may complete out-of-order. The batch as a whole will not be complete until all its commands are complete.

To create a macro command, extend one of the two macro command classes Macrobot provides: SequenceCommand or ParallelCommand. Add subcommands by calling either addCommand() or addCommandInstance(). addCommand() lets you specify a command class and a payload (such as an event). At the appropriate time, the command instance will be created, the payload injected, and the command executed. This automated process of instantiation, injection, and execution is very similar to how commands are normally prepared and executed in Robotlegs. addCommandInstance(), on the other hand, allows you to add a command you have already instantiated and prepared yourself.

Here’s an example of how a macro command might look (in this case, sequential):

public class MyMacroCommand extends SequenceCommand
{
	public function MyMacroCommand()
	{
		// Commands for Macrobot to prepare before execution.
		addCommand(CommandA, new MyEvent());
		addCommand(CommandB, new MyEvent());
		addCommand(CommandC, new MyEvent());
 
		// Custom-prepared commands.
		var command:Command = new CommandD();
		command.event = new MyEvent();
		addCommandInstance(command);
 
		command = new CommandE();
		command.event = new MyEvent();
		addCommandInstance(command);
 
		command = new CommandF();
		command.event = new MyEvent();
		addCommandInstance(command);
	}
}

Asynchronous Commands

While Macrobot can be used to execute solely synchronous commands, it may come in handy to execute commands that are asynchronous, that is, the command is not deemed complete until a later time. The command may need to wait for a response from the server or for user interaction before being marked complete. In this case, your subcommands can extend from Macrobot’s AsyncCommand and call dispatchComplete() once the subcommand should be deemed complete. dispatchComplete() receives a single parameter which reports whether the subcommand completed successfully. The importance of this distinction will become clearer when we discuss atomic execution below. Here’s an example of a simulated asynchronous subcommand:

public class MyCommandWhichHappensToBeASubcommand extends AsyncCommand
{
	protected var timer:Timer;
 
	override public function execute():void
	{
		timer = new Timer(50, 1);
		timer.addEventListener(TimerEvent.TIMER_COMPLETE, timerCompleteHandler);
		timer.start();
	}
 
	protected function timerCompleteHandler(event:TimerEvent):void
	{
		timer.removeEventListener(TimerEvent.TIMER_COMPLETE, timerCompleteHandler);
		timer = null;
		dispatchComplete(true);
	}
}

Atomic Execution

In our first example, subcommands A-F would all be executed by default. However, the atomic property can be set to false (it’s true by default) to modify this behavior. If atomic is set to false and at least one of the subcommands dispatches a failure (using dispatchComplete(false)), subsequent subcommands will not be executed and the macro command itself will dispatch failure. The concept of atomic execution does not apply to parallel commands.

Command Nesting

If you want, you can get crazy and nest your macro commands. Take this as an example:

public class MyMacroCommand extends SequenceCommand
{
	public function MyMacroCommand()
	{
			addCommand(new CommandA());
 
			var parallel1:ParallelCommand = new ParallelCommand();
			parallel1.addCommandInstance(new CommandB());
			parallel1.addCommandInstance(new CommandC());
			addCommandInstance(parallel1);
 
			addCommandInstance(new CommandD());
 
			var parallel2:ParallelCommand = new ParallelCommand();
			parallel2.addCommandInstance(new CommandE());
 
			var sequence:SequenceCommand = new SequenceCommand();
			sequence.atomic = false;
			sequence.addCommandInstance(new CommandF());
			sequence.addCommandInstance(new CommandG());
 
			parallel2.addCommandInstance(sequence);
			parallel2.addCommandInstance(new CommandH());
			parallel2.addCommandInstance(new CommandI());
			addCommandInstance(parallel2);
 
			addCommandInstance(new CommandJ());
	}
}

The overall execution structure of this example looks like this:

• sequence
• command A
• parallel
• command B
• command C
• command D
• parallel
• command E
• sequence
• command F
• command G
• command H
• command I
• command J

Sequential, parallel, and atomic rules apply as you would expect.

Tests

Macrobot comes with a full suite of tests to make sure everything is squeaky clean.

Feedback

If you have any questions or comments regarding Macrobot, please post a comment below!

For those who don’t know, Nimbus is a Flex MVC framework (or micro-architecture for the technically-inclined). Sponsored by Rain, we develop it primarily for use on our applications but make it available for public use and encourage the community to contribute.

Nimbus pulls core concepts from Cairngorm but is meant to cut out a lot of the plumbing developers groan about when they hear “Cairngorm.” It’s light, but it’s not fluffy. Baked in are those rare and tasty flavor morsels you thought only existed in those Funfetti cupcakes your grandmother bakes with love on your birthday.

Until the end of 2008, Nimbus had been shaped, re-shaped, patched, and plugged. A complete re-write was merited so that’s what we did. And really, what makes for a better Christmas than sitting down with your stocking stuffed with jelly beans and re-writing an MVC framework. A few months later, the code is settling down along with the sugar and we’re ready for action.

Here are some features of Nimbus:

• Notification system of command completion so portions of the application can know when a command has finished executing.
• Nestable “macro” commands. Think “I want commands A and B to run in parallel, then C, then D and E in parallel, but inside D I want F and G to run sequentially…”
• Undo/Redo functionality.
• Progress feedback system. You as a developer can associate a processing message with each command or macro command to provide feedback to users.
• Interaction blocking system. While commands are executing, easily disable user interaction to protect your service calls.
• Combinable commands. Ensure that similar command instances can be grouped appropriately in the undo/redo history.

Nimbus may not be right for everyone. Call your system administrator if your scalability problem worsens or is not better within 7 to 10 days. This may mean that there is another condition causing your RTE problems. Do not take Nimbus with alcohol. Call your system administrator right away if after taking Nimbus you are unable to walk, drive, eat, or engage in other activities. In rare cases, severe allergic reactions can occur. Most MVC frameworks carry some risk of dependency. Do not use MVC frameworks for extended periods without first talking to your system administrator. You are encouraged to report negative side effects of Nimbus. Visit http://code.google.com/p/nimbus-as3 for more information.