Carregamento de dados externos

Muitas APIs que carregam dados externos utilizam a classe URLRequest para definir as propriedades da solicitação de rede necessária.

A classe URLLoader permite enviar uma solicitação ao servidor e acessar as informações retornadas. Você também pode utilizar a classe URLLoader para acessar arquivos no sistema de arquivos local, onde o acesso de arquivos é permitido (por exemplo, na área de segurança local do Flash Player e do aplicativo AIR). A classe URLLoader baixa dados de um URL como texto, dados binários ou variáveis codificadas em URL. A classe URLLoader envia eventos como complete, httpStatus, ioError, open, progress e securityError.

O modelo de manipulação de eventos do ActionScript 3.0 é substancialmente diferente do modelo do ActionScript 2.0 que utilizava os manipuladores de evento LoadVars.onData, LoadVars.onHTTPStatus e LoadVars.onLoad. Para obter mais informações sobre como tratar eventos no ActionScript 3.0, consulte Manipulação de eventos

Os dados descarregados só ficam disponíveis depois que o download é concluído. Você pode monitorar o andamento do download (bytes carregados e total de bytes) ouvindo o evento progress a ser despachado. No entanto, se um arquivo é carregado muito rapidamente, o evento progress pode não ser despachado. Quando um arquivo é baixado com sucesso, o evento complete é despachado. Ao definir a propriedade URLLoader dataFormat, é possível receber os dados como texto, raw, dados binários ou como objeto URLVariables.

O método URLLoader.load() (e opcionalmente o construtor da classe URLLoader) utiliza um único parâmetro, request, que é um objeto URLRequest. Um objeto URLRequest contém todas as informações para uma única solicitação HTTP, como o URL de destino, método de solicitação (GET ou POST), informações de cabeçalho adicionais e o tipo MIME.

Por exemplo, para carregar um pacote XML em um script de servidor, você pode usar o seguinte código:

var secondsUTC:Number = new Date().time; 
var dataXML:XML =  
    <clock> 
        <time>{secondsUTC}</time> 
    </clock>; 
var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML.toXMLString(); 
request.method = URLRequestMethod.POST; 
var loader:URLLoader = new URLLoader(); 
loader.load(request); 

O snippet anterior cria um documento XML denominado dataXML que contém um pacote XML a ser enviado ao servidor. O exemplo define a propriedade URLRequest contentType para "text/xml" e atribui o documento XML à propriedade URLRequest data. Por fim, o exemplo cria um objeto URLLoader e envia a solicitação para o script remoto utilizando o método load().

A classe URLStream fornece acesso aos dados descarregados conforme os dados se tornam disponíveis. A classe URLStream também permite encerrar um fluxo antes que o seu download seja finalizado. Os dados descarregados estão disponíveis como dados binários raw.

Ao ler dados de um objeto URLStream, use a propriedade bytesAvailable para determinar se dados suficientes estão disponíveis antes da leitura. Uma exceção EOFError é enviada se você tentar ler mais dados do que o disponível.

Ao construir aplicativos dinâmicos, pode ser útil carregar os dados de arquivos externos ou de scripts do lado do servidor. Isso permite criar aplicativos dinâmicos sem precisar editar ou recompilar seu aplicativo. Por exemplo, se você criar um aplicativo “dica do dia”, poderá gravar um script do lado do servidor que recupera uma dica aleatória de um banco de dados e salva-a em um arquivo de texto uma vez por dia. Em seguida, o aplicativo pode carregar o conteúdo de um arquivo de texto estático em vez de consultar o banco de dados a cada vez.

O seguinte snippet cria um objeto URLRequest e URLLoader que carrega o conteúdo de um arquivo de texto externo, params.txt:

var request:URLRequest = new URLRequest("params.txt"); 
var loader:URLLoader = new URLLoader(); 
loader.load(request);

var request:URLRequest = new URLRequest("sendfeedback.cfm"); 
request.method = URLRequestMethod.POST;

O documento externo (params.txt), que é carregado no tempo de execução, contém os seguintes dados:

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

O arquivo contém dois parâmetros: monthNames e dayNames. Cada parâmetro contém uma lista separada por vírgulas que é analisada como strings. Você pode dividir essa lista em uma matriz usando o método String.split().

Evite usar palavras reservadas ou construções de linguagem como nomes de variáveis em arquivos de dados externos, porque isso dificulta a leitura e a depuração do código.

function completeHandler(event) 
{ 
    var loader2 = event.target; 
    air.trace(loader2.data); 
}

Se o documento remoto contém pares de nome e valor, é possível analisar os dados através da classe URLVariables passando o conteúdo do arquivo carregado, como segue:

private function completeHandler(event:Event):void 
{ 
    var loader2:URLLoader = URLLoader(event.target); 
    var variables:URLVariables = new URLVariables(loader2.data); 
    trace(variables.dayNames); 
}

Cada par de nome e valor do arquivo externo é criado como propriedade no objeto URLVariables. Cada propriedade no objeto variables do exemplo de código anterior é tratada como string. Se o valor do par de nome e valor é uma lista de termos, você pode converter a string em qualquer matriz chamando o método String.split(), como segue:

var dayNameArray:Array = variables.dayNames.split(",");

Se você estiver carregando dados numéricos de arquivos de texto externos, converta os valores em valores numéricos usando a função de nível superior, como int(), uint() ou Number().

Em vez de carregar o conteúdo do arquivo remoto como uma string e criar um novo objeto URLVariables, você pode definir a propriedade URLLoader.dataFormat como uma das propriedades estáticas encontradas na classe URLLoaderDataFormat. Os três valores possíveis para a propriedade URLLoader.dataFormat são os seguintes:

• URLLoaderDataFormat.BINARY — a propriedade URLLoader.data contém dados binários armazenados em um objeto ByteArray.

• URLLoaderDataFormat.TEXT — a propriedade URLLoader.data contém texto em um objeto String.

• URLLoaderDataFormat.VARIABLES — a propriedade URLLoader.data contém variáveis codificadas em URL armazenadas em um objeto URLVariables.

O código a seguir demonstra como a configuração da propriedade URLLoader.dataFormat como URLLoaderDataFormat.VARIABLES permite analisar automaticamente dados carregados em um objeto URLVariables:

package 
{ 
    import flash.display.Sprite; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLLoaderDataFormat; 
    import flash.net.URLRequest; 
 
    public class URLLoaderDataFormatExample extends Sprite 
    { 
        public function URLLoaderDataFormatExample() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); 
            var variables:URLLoader = new URLLoader(); 
            variables.dataFormat = URLLoaderDataFormat.VARIABLES; 
            variables.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                variables.load(request); 
            }  
            catch (error:Error) 
            { 
                trace("Unable to load URL: " + error); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
        var loader:URLLoader = URLLoader(event.target); 
        trace(loader.data.dayNames); 
        } 
    } 
}

Como ilustrado no exemplo a seguir, carregar XML de um arquivo externo é o mesmo que carregar URLVariables. Você pode criar uma ocorrência de URLRequest e uma de URLLoader e usá-las para baixar um documento XML remoto. Quando o arquivo é baixado completamente, o evento Event.COMPLETE é despachado e o conteúdo do arquivo externo é convertido para uma ocorrência XML, que pode ser analisada usando métodos e propriedades XML.

package 
{ 
    import flash.display.Sprite; 
    import flash.errors.*; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLRequest; 
 
    public class ExternalDocs extends Sprite 
    { 
        public function ExternalDocs() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); 
            var loader:URLLoader = new URLLoader(); 
            loader.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                loader.load(request); 
            } 
            catch (error:ArgumentError) 
            { 
                trace("An ArgumentError has occurred."); 
            } 
            catch (error:SecurityError) 
            { 
                trace("A SecurityError has occurred."); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
            var dataXML:XML = XML(event.target.data); 
            trace(dataXML.toXMLString()); 
        } 
    } 
}

Além de carregar arquivos de dados externos, você pode usar também a classe URLVariables para enviar variáveis a um script do lado do servidor e processar a resposta do servidor. Isso é útil, por exemplo, se você está programando um jogo e deseja enviar a pontuação do usuário para um servidor, que calculará se ela deve ser adicionada à lista de pontuações mais altas, ou mesmo enviar informações de logon de um usuário para um servidor validá-las. Um script de servidor pode processar o nome do usuário e a senha, validá-los em um banco de dados e confirmar se as credenciais fornecidas pelo usuário são válidas.

O seguinte snippet cria um objeto URLVariables denominado variables que cria uma nova variável chamada name. Em seguida, é criado um objeto URLRequest que especifica a URL do script de servidor para a qual enviar as variáveis. Depois, você define a propriedade method do objeto URLRequest para enviar as variáveis como uma solicitação HTTP POST. Para adicionar o objeto URLVariables à solicitação de URL, defina a propriedade data do objeto URLRequest como o objeto URLVariables criado anteriormente. Por fim, é criada a ocorrência de URLLoader e o método URLLoader.load(), que inicia a solicitação, é chamado.

var variables:URLVariables = new URLVariables("name=Franklin"); 
var request:URLRequest = new URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = URLRequestMethod.POST; 
request.data = variables; 
var loader:URLLoader = new URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error:Error) 
{ 
    trace("Unable to load URL"); 
} 
 
function completeHandler(event:Event):void 
{ 
    trace(event.target.data.welcomeMessage); 
}

O código a seguir contém o conteúdo do documento greeting.cfm do Adobe ColdFusion® usado no exemplo anterior:

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>