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

You might want your provider to process results before calling the result handlers. A processor is a function that accepts a single argument and returns an output.

  public function getUser(userId:String):Promise
  {
    var promise:Promise = new Promise()
      .addResultProcessor(jsonProcessor)
      .addResultProcessor(timestampProcessor);
    // .. snip .. //
    return promise;
  }
  
  function jsonProcessor(input:String):Object
  {
    var output:Object = new JSONDecoder().decode(input);
    return output;
  }
  
  function timestampProcessor(input:Object):Object
  {
    var output:Object = input;
    output.timestamp = new Date().time;
    return output;
  }

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);