Caricamento di dati esterni

Numerose API che caricano dati esterni utilizzano la classe URLRequest per definire le proprietà di richiesta di rete necessarie.

La classe URLLoader vi consente di inviare una richiesta a un server e accedere alle informazioni restituite. Potete anche utilizzare la classe URLLoader per accedere ai file nel file system locale in contesti in cui l'accesso ai file locali è consentito (ad esempio, la sandbox locale con file system Flash Player e la sandbox dell'applicazione AIR). La classe URLLoader scarica i dati da un URL sotto forma di testo, dati binari o variabili con codifica URL. La classe URLLoader invia eventi quali complete, httpStatus, ioError, open, progress e securityError.

Il modello di gestione degli eventi di ActionScript 3.0 è significativamente diverso dal modello ActionScript 2.0, che utilizza i gestori di evento LoadVars.onData, LoadVars.onHTTPStatus e LoadVars.onLoad. Per ulteriori informazioni sulla gestione degli eventi in ActionScript 3.0, vedete Gestione degli eventi

I dati scaricati non sono disponibili fino al termine dello scaricamento. Potete verificare lo stato di avanzamento dello scaricamento (byte caricati e byte totali) intercettando l'evento progress da inviare. Tuttavia, se un file viene caricato in maniera abbastanza rapida, l'evento progress potrebbe non essere inviato. L'evento complete viene inviato dopo che un file è stato scaricato. Impostando la proprietà dataFormat di URLLoader, potete ricevere i dati come testo, dati binari originari o come un oggetto URLVariables.

Il metodo URLLoader.load() (e facoltativamente la funzione di costruzione della classe URLLoader) accetta un solo parametro, request, ovvero un oggetto URLRequest. Un oggetto URLRequest contiene tutte le informazioni per una singola richiesta HTTP, ad esempio l'URL di destinazione, il metodo di richiesta (GET o POST), informazioni aggiuntive sull'intestazione e il tipo MIME.

Ad esempio, per caricare un pacchetto XML in uno script sul lato server, potete utilizzare il codice riportato di seguito:

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

Lo snippet di codice precedente crea un documento XML denominato dataXML che contiene un pacchetto XML da inviare al server. L'esempio imposta la proprietà contentType di URLRequest su "text/xml" e assegna il documento XML alla proprietà data di URLRequest. Infine, l'esempio crea un oggetto URLLoader e invia la richiesta allo script remoto utilizzando il metodo load().

La classe URLStream fornisce l'accesso ai dati in corso di scaricamento man mano che questi arrivano. La classe URLStream consente inoltre di chiudere uno streaming prima che termini lo scaricamento. I dati scaricati sono disponibili come dati binari originari.

Durante la lettura di dati da un oggetto URLStream, utilizzate la proprietà bytesAvailable per determinare se sono disponibili dati sufficienti prima di leggerli. Se si tenta di leggere più dati di quelli disponibili, viene generata un'eccezione EOFError.

Quando create applicazioni dinamiche, può essere utile per caricare dati da file esterni o da script lato server. In questo modo è possibile creare applicazioni dinamiche senza modificare o ricompilare l'applicazione. Ad esempio, se create un'applicazione “suggerimento del giorno”, potete scrivere uno script sul lato server che una volta al giorno recupera un suggerimento causale da un database e lo salva in un file di testo. L'applicazione può quindi caricare il contenuto di un file di testo statico, anziché interrogare il database ogni volta.

Lo snippet di codice seguente crea un oggetto URLRequest e URLLoader che carica il contenuto di un file di testo esterno, 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;

Il documento esterno, params.txt, che viene caricato in fase di runtime contiene i seguenti dati:

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

Il file contiene due parametri, monthNames e dayNames. Ogni parametro contiene un elenco separato da virgole che viene analizzato come stringa. Questo elenco può essere suddiviso in un array utilizzando il metodo String.split().

Evitate di utilizzare parole riservate o costrutti del linguaggio come nomi di variabili nei file di dati esterni, perché ciò rende più difficile la lettura e il debug del codice.

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

Se il documento remoto contiene coppie nome-valore, è possibile analizzare i dati utilizzando la classe URLVariables passando il contenuto del file caricato, come riportato di seguito:

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

Ogni coppia nome-valore contenuta nel file esterno viene creata sotto forma di proprietà nell'oggetto URLVariables. Ogni proprietà all'interno dell'oggetto variables nell'esempio di codice precedente viene considerato come una stringa. Se il valore della coppia nome-valore è un elenco di elementi, potete convertire la stringa in un array chiamando il metodo String.split(), come riportato di seguito:

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

Se caricate dati numerici dai file di testo esterni, convertite i valori in valori numerici utilizzando una funzione di primo livello quale int(), uint() o Number().

Anziché caricare il contenuto del file remoto come stringa e creare un nuovo oggetto URLVariables, è possibile impostare la proprietà URLLoader.dataFormat su una delle proprietà statiche presenti nella classe URLLoaderDataFormat. Di seguito sono riportati i tre valori possibili per la proprietà URLLoader.dataFormat:

• URLLoaderDataFormat.BINARY: la proprietà URLLoader.data contiene dati binari memorizzati in un oggetto ByteArray.

• URLLoaderDataFormat.TEXT: la proprietà URLLoader.data contiene testo in un oggetto String.

• URLLoaderDataFormat.VARIABLES: la proprietà URLLoader.data contiene variabili con codifica URL memorizzate in un oggetto URLVariables.

Il codice seguente dimostra come l'impostazione della proprietà URLLoader.dataFormat su URLLoaderDataFormat.VARIABLES consenta di analizzare automaticamente i dati caricati in un oggetto 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); 
        } 
    } 
}

Come illustrato nell'esempio seguente, caricare contenuto XML da un file esterno è come caricare URLVariables. Potete creare un'istanza di URLRequest e un'istanza di URLLoader e utilizzarle per scaricare un documento XML remoto. Dopo che il file è stato completamente scaricato, viene inviato l'evento Event.COMPLETE e il contenuto del documento esterno viene convertito in un'istanza di XML che può essere analizzata utilizzando i metodi e le proprietà 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()); 
        } 
    } 
}

Oltre a caricare file di dati esterni, potete utilizzare la classe URLVariables per inviare variabili a uno script sul lato server ed elaborare la risposta del server. Questa operazione è utile, ad esempio, quando programmate un gioco e desiderate inviare il punteggio dell'utente a un server per calcolare se dovrà essere aggiunto all'elenco dei punteggi più alti oppure per inviare le informazioni di login di un utente a un server per la convalida. Uno script sul lato server può elaborare il nome utente e la password, convalidarli rispetto a un database e confermare se le credenziali fornite dall'utente sono valide.

Lo snippet di codice seguente crea un oggetto URLVariables di nome variables, che a propria volta crea una nuova variabile denominata name. Viene quindi creato un oggetto URLRequest che specifica l'URL dello script sul lato server a cui inviare le variabili. Impostate quindi la proprietà method dell'oggetto URLRequest in modo che le variabili siano inviate come una richiesta POST HTTP. Per aggiungere l'oggetto URLVariables alla richiesta URL, impostate la proprietà data dell'oggetto URLRequest sull'oggetto URLVariables creato precedentemente. Infine, viene creata l'istanza di URLLoader e viene richiamato il metodo URLLoader.load(), che avvia la richiesta.

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

Il codice seguente contiene il contenuto del documento greeting.cfm di Adobe ColdFusion® utilizzato nell'esempio precedente:

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