Oil

Overview

Oil is a collection of utilities and extensions for the Robotlegs framework.

Async

Some simple tools for dealing with asynchronous operations. May be expanded to include things like Tasks and Schedules.

Promise

A Promise allows you to bind to the result of an asynchronous operation, and has a fluent interface for adding result, error and progress callbacks.

The status, result, error and progress properties are bindable. Handlers will run even if they are added “late” (after-the-fact). A handler must accept a single argument: a Promise.

Consumption

Promise consumption might look like this:

  view.userPromise = service.getUser(userId)
    .addResultHandler(handler)
    .addErrorHandler(handler)
    .addProgressHandler(handler);
  
  function handler(p:Promise):void
  {
    trace(p.status);
    trace(p.result);
    trace(p.error);
    trace(p.progress);
  }

    <fx:Declarations>
      <async:Promise id="userPromise"/>
    </fx:Declarations>
    <s:DataGroup dataProvider="{userPromise.result}" />

Making Promises

A provider might look something like this:

  public function getUser(userId:String):Promise
  {
    var promise:Promise = new Promise();
    // .. wire up some async call that ends up at handleComplete() //
    return promise;
  }
  
  protected function handleComplete(event:Event):void
  {
    var loader:URLLoader = event.target as URLLoader;
    var promise:Promise = promises[loader];
    delete promises[loader];
    promise.handleResult(loader.data);
  }

Note: the promises dictionary above is just an example. How you manage Promises from your provider is completely up to you. For a more thorough example see: org.robotlegs.oil.rest.RestClientBase

Processing Promises (updated)

You might want your provider to process results before calling the result handlers. A processor is an asynchronous function that accepts a data payload and a callback. You must call the callback with an error (or null) as the first argument and the transformed data as the second.

  public function getUser(userId:String):Promise
  {
    var promise:Promise = new Promise()
      .addResultProcessor(jsonProcessor)
      .addResultProcessor(timestampProcessor)
      .addResultProcessor(throttleProcessor);
    // .. snip .. //
    return promise;
  }
  
  function jsonProcessor(input:String, callback:Function):void
  {
    var data:Object = new JSONDecoder().decode(input);
    if (data && data.error)
    {
      callback(data.error);
    }
    else
    {
      callback(null, output);
    }
  }
  
  function timestampProcessor(input:Object, callback:Function):void
  {
    var output:Object = input;
    output.timestamp = new Date().time;
    callback(null, output);
  }
  
  function throttleProcessor(data:Object, callback:Function):void
  {
    setTimeout(function():void
    {
      callback(null, data);
    }, 500);
  }

Note: You must call the callback at some point.

Note: Passing any non-falsey value as the first argument to the callback will halt processing, put the promise into the failed state and invoke any error handlers.

Rest

An IRestClient returns Promises from get, post, put and delete calls.

  client = new JSONClient("http://api.somewhere.com");
  view.userPromise = client.get("/user/" + userId)
    .addResultHandler(onUser)
    .addErrorHandler(onUserError)
    .addProgressHandler(onUserProgress);

A service might look something like this:

public class UserService
{
  protected var service:IRestClient;
  
  public function UserService(service:IRestClient)
  {
    this.service = service;
  }

  public function getUsers():Promise
  {
    return service.get('/users/');
  }

  public function getUserDetails(userId:String):Promise
  {
    return service.get('/users/' + userId);
  }
}

Pool

Basic object pooling.

  pool = new BasicObjectPool(MyRenderer, {someProp:"hello"});
  object = pool.get();
  pool.put(object);
  pool.ensureSize(10);

  pool = new InjectingObjectPool(injector, MyRenderer, {someProp:"hello"});
  object = pool.get();

Flex

Some Flex-specific stuff, like IFactory implementations that pull instances from DI containers or object pools.

InjectingFactory

A Flex IFactory implementation that pulls objects from a Robotlegs IInjector.

  list.itemRenderer = new InjectingFactory(injector, MyRenderer, {someProp:"hello"});

InjectingFactoryBuilder

Builds an InjectingFactory pre-configured with an Injector.

  builder = new InjectingFactoryBuilder(injector);
  list.itemRenderer = builder.build(MyRenderer, {someProp:"hello"});

PooledRendererFactory, PooledRendererFactoryProvider

A Flex IFactory implementation that pulls objects from an object pool.

  pool = new InjectingObjectPool(injector, MyRenderer, {someProp:"hello"});
  list.itemRenderer = new PooledRendererFactory(pool);

Includes a mechanism for pooling data renderers across multiple consumers.

  <s:DataGroup id="list"
    typicalItem="{prFactory.newInstance()}"
    itemRenderer="{prFactory}"
    itemRendererFunction="{prFactory.itemRendererFunction}"
    rendererRemove="prFactory.rendererRemoveHandler(event)" />

Alternatively

  provider = new PooledRendererFactoryProvider(injector);
  provider
    .getFactory(MyRenderer)
    .manage(list);