Spring ActionScript: The Operation API
ActionScript, Air, Flash, Flex, Spring ActionScript 2 Comments »Introduction
As Flex and Flash developers, we are used to working with asynchronous code. Whenever we load data from a server for instance, we need to wait for the result to come back as we can't just read the result of such a call directly. The way in which we wait for these asynchronous calls to complete differs from API to API. There are events, async tokens, callback functions, ... The fact that there is no unified approach to this, is a core problem in our opinion of Flash. It is not only confusing to developers, but it also prevents us from easily integrating these various techniques and abstracting away their details.
Consider a service that manages User objects by providing basic operations on these entities like create, read, update and delete (CRUD). If you plan on creating an interface for this user service so you can vary the implementation easily, what return type would the methods have?
-
public interface IUserService {
-
function addUser(user:User): ? ;
-
function deleteUser(user:User): ? ;
-
function saveUser(user:User): ? ;
-
function loadAllUsers(): ? ;
-
}
We could either:
- return nothing and wait for events to be dispatched by the service when its methods have executed: this has the disadvantage that there is no real contract on the method.
- return nothing and pass in a Responder or result and fault handler callback functions: this has the disadvantage that it blurs the signature of the service method with technical details.
- return an AsyncToken: this is a stricter contract, but it would tie our code to the Flex framework and it would only work if you create implementations that support AsyncToken
In general, the biggest problem is that there is no standard way of defining an asynchronous execution in the Flash Player.
Operation API
The solution Spring ActionScript provides comes in the form of the Operation API. This is a set of interfaces and classes that enables developers to work with asynchronous processes in a uniform fashion. An "operation" in Spring ActionScript vocabulary is the term used for an asynchronous execution and is defined by the IOperation interface. Once an operation is created, it executes immediately and when it is done executing, it either dispatches a "complete" event or an "error" event.
Going back to our user service, this means that we would type all return types of its (asynchronous) methods to IOperation:
-
public interface IUserService {
-
function addUser(user:User):IOperation;
-
function deleteUser(user:User):IOperation;
-
function saveUser(user:User):IOperation;
-
function loadAllUsers():IOperation;
-
}
Whether you now have an implementation that uses Remote Objects, Webservices, locally loaded XML data, a local SQLite database, ... clients working with the user service should not know and care about implementation details. All that they know is that asynchronous methods return an operation to which they can attach listeners to for dealing with the result or error of the call.
A client calling one of these methods might to something like the following, considering there is a userService of type IUserService:
-
var user:User = new User("John", "Doe");
-
var operation:IOperation = userService.saveUser(user);
-
operation.addCompleteListener(saveUser_completeHandler);
-
operation.addErrorListener(saveUser_errorHandler);
-
-
function saveUser_completeHandler(event:OperationEvent):void {
-
// user was saved
-
// event.result contains an optional result of the asynchronous method
-
}
-
-
function saveUser_errorHandler(event:OperationEvent):void {
-
// user was not saved, since an error occurred
-
// event.error contains error information
-
}
Notice that each operation has the convenience methods "addCompleteListener" and "addErrorListener" for listening to the events dispatched by the operation. The handlers for these events receive an instance of the OperationEvent which contains either the result or the error details.
We have also included some base classes that make it easy to create operations and services. The AbstractOperation class for instance provides a basic implementation of the IOperation interface and implements the event dispatching functionality. You might want to extend this class if you create your own operations.
Here's an example of a custom operation:
-
public class MyOperation extends AbstractOperation {
-
-
public function MyOperation() {
-
// execute something asynchronously
-
// the resultHandler and errorHandler deal with the result of fault
-
}
-
-
private function resultHandler(aResult:Object):void {
-
dispatchCompleteEvent(aResult);
-
}
-
-
private function errorHandler(anError:Object):void {
-
dispatchErrorEvent(anError);
-
}
-
-
}
Notice that we call the "dispatchCompleteEvent" and "dispatchErrorEvent" on either success or failure. We pass in the result or the error we received. These will internally be set on the operation so that clients can request them via the OperationEvent.
The Spring ActionScript framework also contains a series of operation implementations for working with Remote Objects, NetConnections, etc.
Combining Operations into Services
Taking this a step further, we also provide base classes for creating services that consist of operations. Going back to our user service, we might create an implementation that uses RemoteObject by subclassing the RemoteObjectService class. This class provides basic functionality for delegating to the underlying Remote Object. Here's an example:
-
public class UserService extends RemoteObjectService implements IUserService {
-
-
public function UserService(remoteObject:RemoteObject) {
-
super(remoteObject);
-
}
-
-
public function addUser(user:User):IOperation {
-
return call("addUser", user);
-
}
-
-
public function deleteUser(user:User):IOperation {
-
return call("deleteUser", user);
-
}
-
-
public function saveUser(user:User):IOperation {
-
return call("saveUser", user);
-
}
-
-
public function loadAllUsers():IOperation {
-
return call("loadAllUsers");
-
}
-
-
}
Notice how easy it is to abstract away the use of a remote object and make clients unaware of this by only providing them with the IUserService interface. The "call" method is a very convenient method to forward the call to the remote object, without having to take care of AsyncTokens and Reponders.
Progress Operations
For operations that take longer to execute the IOperation interface has a subinterface called IProgressOperation. This might for instance be the loading of a sound file, a module, etc. Implementations of this interface can let clients know about the progress the operation made by dispatching progress events at certain intervals. When listening for these events, via the "addProgressListener" method, a ProgressOperationEvent is received that contains a "progress" and "total" property.
-
var loadSoundOperation:IProgressOperation = new MyLoadSoundOperation("aSoundFile.mp3");
-
loadSoundOperation.addProgressListener(loadSoundOperation_progressHandler);
-
-
function loadSoundOperation_progressHandler(event:ProgressOperationEvent):void {
-
trace("Loaded " + event.progress + " of " + event.total + " bytes");
-
}
Batch Operations
When you are in a scenario where you need to execute several operations and you don't care about the order in which they finish, you might want to use the OperationQueue class. This is an implementation of the IProgressOperation interface that lets you add operations to a queue and receive information about the progress of the complete execution. Since this also is an IOperation, we can listen to the completion of the queue via the "addCompleteListener" method.
-
var queue:OperationQueue = new OperationQueue();
-
-
// setup event listeners
-
queue.addCompleteListener(queue_completeHandler);
-
queue.addProgressListener(queue_progressHandler);
-
-
// add operations to the queue
-
queue.addOperation(new AnOperation());
-
queue.addOperation(new AnotherOperation());
-
queue.addOperation(new YetAnotherOperation());
-
-
function queue_completeHandler(event:OperationEvent):void {
-
trace("Queue is done executing.");
-
}
-
-
function queue_progressHandler(event:ProgressOperationEvent):void {
-
trace("Executed " + event.progress + " of " + event.total + " operations");
-
}
Mocking Operations
During development it is often good to have mock or stub implementations of the services that normally connect to a backend. The main reason is that this provides a way of (unit) testing the use of the services without the backend running. Spring ActionScript provides a class called MockOperation for this purpose. Its constructor takes the following arguments:
- result: the result returned by the operation
- delay (optional): the time the operations waits before completing, in milliseconds (default = 1000)
- returnError (optional): a flag indicating wether or not the operation should return an error at random times (default = false)
If you would mock the user service, you could do this as follows (only one method is implemented):
-
public function loadAllUsers():IOperation {
-
var users:ArrayCollection = new TypedCollection(User);
-
users.addItem(new User("John", "Doe"));
-
users.addItem(new User("Mitch", "Hedberg"));
-
return new MockOperation(users);
-
}
Conclusion
The Operation API provides a neat way of abstracting away technical details and makes it easier to swap implementations without affecting any code. It unifies asynchronous programming for the Flash Player into a simple set of interfaces and base classes. You will also see that it is the basis for other APIs in the Spring ActionScript framework such as the Command and Task API.
For more information on Spring ActionScript, refer to www.springactionscript.org
Add to Bloglines - Digg This! - del.icio.us - Stumble It! - Twit This! - Technorati links - Share on Facebook - Feedburner
Christophe Herreman is a software developer living in Belgium. He's working on high-end Flex and AIR solutions at 
Recent Comments