Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darscan/robotlegs-extensions-Oil

Oil is a collection of utilities and extensions for the Robotlegs framework
https://github.com/darscan/robotlegs-extensions-Oil

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
h1. Oil



h2. Overview



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



h2. Async



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



h3. 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.



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

  }





    

      

    

    




h4. 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 



h4. 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.



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

  }

}




h2. 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();




h2. Flex



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



h3. InjectingFactory



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




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




h3. InjectingFactoryBuilder



Builds an InjectingFactory pre-configured with an Injector.




  builder = new InjectingFactoryBuilder(injector);

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




h3. 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.




  




Alternatively




  provider = new PooledRendererFactoryProvider(injector);

  provider

    .getFactory(MyRenderer)

    .manage(list);