Creando APIs en Actionscript

Recientemente he tenido en mis ratos libres la mania de bajar API's para Actionscript 3 de diferentes servicios que hay por ahi, como Digg, Twitter, Facebook, Salesforce, etc para probarlos, jugar con ellos y hacer alguna aplicacion sencilla con ellos aunque nunca vaya a ser utilizada.
Esto me divierte en realidad y mas importante me ayuda a ver codigo de otras personas, maneras de pensar y de implementar. Creo que es una experiencia enriquecedora. Muchos desarrolladores piensan que ver el codigo de otros es malo, es bajo, es denigrante. Honestamente creo que no! Primero yo escojo de quien veo el codigo y la mayoria de personas que hacen estos APIs son mucho mas competentes que yo! Ademas es una manera de aprender de mejorar y de desarollar mejor. Un claro ejemplo es el acceso que tenemos al framework de Flex. Si algo puedo decir de mi actual trabajo y de los dos maestros de Flex con los que trabajo es que se conocen ese framework de arriba a abajo. De ahi que puedan hacer las cosas que hacen.
Bueno siguiendo con mi fascinacion tan geek de las ultimas semanas, me he puesto a pensar en que requisitos son necesarios para construir un API en ActionScript.

Primero pensemos para que necesitamos realizar un API. Un API es utilizado para ofrecer una serie de servicios que puedan ser invocados por otras aplicaciones con el fin de ejecutar una accion. No es lo mismo que un framework. El API debe ser claro, sencillo y definido. Mejor si esta documentado. Mejor aun si tiene ejemplos. El API debe ser facil de usar, intuitivo y tener todo lo que nuestros futuros clientes vayan a ocupar para interactuar con nuestra plataforma. Incluyendo objetos definidos por nosotros mapeando la informacion de nuestros servicios.

Segundo analicemos la forma en que vamos a entregar nuestra informacion. Aqui desde dos perspectivas distintas:
a) Como se accedera a la informacion que se quiere facilitar (ya pensando en algo mas "fisico"). Esto incluye como se haran los llamados a nuestros servicios: REST Services? Web Services? Remoting? External Calls (como tiene el API de Facebook)? Todo esto debe ser transparente para el usuario de nuestro API. Si acaso lo mas es la opcion de escoger que tipo de canal usar para comunicarse con nuestros servicios, pero la implementacion y demas no debe ser de importancia para el.
b) La forma en que entregaremos la informacion recolectada de nuestros servicios. Si recibimos XML, no podemos pasarle simplemente XML al cliente y dejar que el piense que va a hacer con esa informacion (tecnicamente si podemos, pero no debemos :) ). La creacion de objetos que mapeen nuestro servicio hace que nuestro API sea mas facil de usar.

Tercero consideremos en la naturaleza Asincronima de nuestra plataforma. Cuando hacemos una invocacion a un servicio externo sea por WebService, Remoting o simple REST Services no sabemos cuando vamos a recibir la informacion de vuelta. Esto hace que nuestros APIs no sean tan facil de usar cuando invocamos servicios remotos como hacer:

var misUsuarios:ArrayCollection = miAPI.cargarUsuarios(); //ESTO NO FUNCIONA!!

El metodo cargarUsuarios puede demorar un tiempo (incluso has segundos) en devolvernos esta informacion, asi que la asignacion a mis usuarios no va a ser correcta.

Soluciones:
a) Una forma de hacerlo es pasarle al metodo el arraycollection que queremos cargar y cuando se reciba la informacion se carguen los resultados en esa variable pasada como parametro. Recordemos que nuestros objetos en AS3 se pasan por referencia y no por valor, asi que los cambios que hagamos al objeto pasado por parametro, se reflejaran en nuestro objeto original (a menos que se haga una copia del mismo. En lo personal la siento como valida, pero no es aplicable en todas las ocasiones. A veces ocupamos darnos cuenta cuando algo fue procesado y eso se logra a traves de eventos.

b) Otra forma de hacerlo es atraves del uso de eventos. Cuando nuestra funcion recibe el resultado, esta manda un evento indicando que fue recibido. Anadiendo un event listener a ese evento, podemos procesar esa informacion desde donde queramos. Algo importante es aislar cada llamada o cada proceso de datos por aparte, para que cada llamada despache un solo evento, en lugar de estar llamando handlers de otras locaciones por eventos que se invocan con otros propositos. Por supuesto es importante recordar el removeEventListener una vez que es ejecutado un event handler que no se ocupa tener mas y poner las referencias como weak, pero igual si no se aislan las llamadas pueden crear conflictos.

Esta practica es seguida en el API para Facebook, a continuacion parte del codigo de uno de sus ejemplos:

var call:AddComment = new AddComment(story_id, body);
call.addEventListener(FacebookEvent.COMPLETE, onAddComment);
facebook.post(call);

onAddComment Va a encargarse de utilizar la informacion recibida como se quiera, puesto que ya esta informacion viene procesada y convertida en el tipo de dato que se quiere todo esto cuando se despache el evento de Complete.

c) Otra forma de hacerlo, es aislando el resultado de la funcion invocada y que ella se encargue de manejar el resultado. Esto es como lo que hacen con el API de Digg . Esto es delegar la llamada y el procesamienta del resultado y posterior conversion a objetos normales a un objeto que es devuelto por nuestra funcion invocada. Por ejemplo:

Del API de DIGG

public static function getUser(user:*):UserResponse
{
var request:URLRequest = new URLRequest(getUserURL(user));
return load(request, new UserResponse()) as UserResponse;
}

Esta clase devuelve un UserResponse, que hereda de la clase Response que a su vez es la que hace el llamado al servicio y delega en UserResponse el procesamiento y conversion del resultado en un objeto utilizable en la aplicacion y no simple XML.

Como ven, enfoques distintos, pero el mismo principio aislar la invocacion para que pueda ser tratada como una llamada distinta.

Espero esto pueda ayudar a otras personas que tengan que crear APIs para servicios externos para AS3 o que anden buscando como ingresar a esto de APIs y servicios externos y que puedan de este humilde texto encontrar algo que les ayude
Disfruten...

Eventos en Flex

Los eventos en AS3 son a mi parecer la clave que permite crear RIAs interactivas, agradables y completas.
Un evento es generado la mayor cantidad de veces por la interaccion del usuario (tambien conocido como gestos) con el sistema (un boton, un campo de texto, cualquier interaccion que se haga por mouse o teclado). Algunos eventos son generados por el sistema automaticamente.
Los eventos son maneras eficaces para realizar aplicaciones con un acoplamiento bajo, esto debido a que la comunicacion se da a traves de ellos, un componente dispara un evento y solo se preocupa por eso. Si algun otro componente o contenedor ocupa de ese componente recibira el evento y procedera a realizar la funcionalidad que requiera con ese evento y la informacion que el contenga, sin conocer absolutamente nada del componente ni siquiera saber quien lo envio.
Otra cosa muy interesante de los eventos es que uno puede crear sus propios eventos customizados, descendiendo de la clase Event. Aqui un ejemplo:

package{
import flash.events.Event;

public class miEvento extends Event{
public static const AGREGAR_PERSONA:String = "AgregarPersona";

public var nombre:String;
public var apellidos:String;
public var action:String;

public function miEvento(action:String,nombre:String,apellidos:String,bubbles:Boolean=false,cancelable:Boolean=false){
super(action,bubbles, cancelable);
this.action = action;
this.nombre = nombre;
this.apellidos = apellidos;
}

override public function clone():Event{
return new EventoEvent(action, nombre, apellidos, evento);
}
}
}

En este ejemplo simple y chapucero, se pasan dos variables, nombre y apellidos que seran seteadas por el disparador del evento y que podran ser recolectadas por cualquier componente O o contenedor que este interesado en recibirlo. Nota, se pueden incluir clases para encapsular la informacion o incluso clases de cualquier tipo que se hayan creado.

Existen 3 fases de propagacion, durante los eventos:

1. Capturing: De arriba a abajo.
Un componente dispara un evento y Flex se encargara de buscar desde el contenedor mas afuera de ese objeto (generalmente el application) hasta el contenedor directo del componente mismo. Cada vez que va cambiando de componente, la variable currentTarget del event va cambiando. Cabe aclarar que los eventos tienen dos propiedades importantes: target y currentTarget.
El target en los eventos de AS3 se refiere al que emitio o disparo el evento y el currentTarget se refiere al nodo u objeto que se esta chequeando por EventListeners. No se, talvez a los de Adobe no les dio mas para ponerle otros nombres pues es algo confuso... Con estas dos propiedades podemos averiguar quien hizo quien y quien va a encargarse de...
Ejemplo:
Tenemos esto:
Application -->
Canvas -->
Button

El Capturing buscaria por event listeners en este orden: Application, Canvas.
Si existieran mas capas arriba del button, pues se revisaria en cada una de estas si tenian event handlers en cada una de ellos. El default del capturing es false.

2. Targeting:

Es el mas sencillo, solo se revisa por event listeners dentro del componente que dispara el evento, como cuando se define en el boton la propiedad click="funcion()". Esto ademas indica que el target y currentTarget son los mismos.

3. Bubbling: De abajo para arriba.
Es el contrario al Capturing
Ejemplo:
Tenemos esto:
Application -->
Canvas -->
Button

El Bubbling buscaria por event listeners en este orden: Canvas, Application.
Flex buscara event listeners hasta que se le permita. Puede ser que llegue hasta al application o puede ser que se le pare en el contenedor siguiente al componente que despacha el evento, en este caso el Canvas. El default del bubbling es false.

Tanto para capturing como para bubbling, es posible el parar la propagacion desde un listener que se quiera, con stopPropagation() y stopImmediatePropagation().

Lo mejor en la propagacion es ver cual es la que mejor sirve para su aplicacion para optimizar tiempos. Por ejemplo si solo ocupa targeting, deje bubbling y capturing en false. Si ocupa capturar un evento solamente desde el contendor del componente, pues user bubbling. Si lo ocupa hacer desde mas afuera, pues hagalo con capturing. Si ocupa capturar el evento por alguien mas que el target y no usen bubbling o targetting no se va a poder capturar los eventos lanzados a no ser que agregue el listener al contenedor, pero no siempre se puede hacer.

Esto es algo muy basico, pero necesario y que hay que estar revisando casi todos los dias para comprenderlo mejor. Cuando se dominen los eventos en Flex, estoy seguro que tendra un 80% de lo escencial dominado.