Läsa in externa data

Många API:er som läser in externa data använder klassen URLRequest för att definiera egenskaperna för den nödvändiga nätverksbegäran.

Med klassen URLLoader kan du skicka en begäran till en server och få åtkomst till den information som skickas tillbaka. Du kan också använda klassen URLLoader för att få åtkomst till filer på det lokala filsystemet om lokal filåtkomst tillåts (till exempel i sandlådan lokal-med-filsystem i Flash Player och i AIR-programsandlådan). Med klassen URLLoader laddas data ned från en URL som text, binära data eller URL-kodade variabler. Klassen URLLoader skickar händelser som complete, httpStatus, ioError, open, progress och securityError.

Händelsehanteringsmodellen i ActionScript 3.0 skiljer sig väsentligen från ActionScript 2.0-modellen, som använde händelsehanterarna LoadVars.onData, LoadVars.onHTTPStatus och LoadVars.onLoad. Mer information om hur du hanterar händelser i ActionScript 3.0 finns i Hantera händelser

Hämtade data är inte tillgängliga förrän hämtningen har slutförts. Du kan följa hämtningsförloppet (inlästa byte av totalt antal byte) genom att avlyssna när händelsen progress skickas. Men om det går tillräckligt fort att läsa in en fil kanske inte någon progress-händelse skickas. När en fil har laddats ned skickas händelsen complete. Genom att ange URLLoader-egenskapen dataFormat kan du välja att ta emot data som text, binära rådata eller som ett URLVariables-objekt.

Metoden URLLoader.load() (och eventuellt konstruktorn för klassen URLLoader) har en enda parameter, request, som är ett URLRequest-objekt. Ett URLRequest-objekt innehåller all information för en enskild HTTP-begäran, till exempel mål-URL, begärandemetod (GET eller POST), annan huvudinformation samt MIME-typ.

Om du till exempel vill överföra ett XML-paket till ett skript på en server kan du använda följande kod:

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

Ovanstående kodutdrag skapar ett XML-dokument med namnet dataXML som innehåller det XML-paket som ska skickas till servern. I exemplet anges att URLRequest-egenskapen contentType ska vara "text/xml" och XML-dokumentet tilldelas URLRequest-egenskapen data. Slutligen skapar exemplet ett URLLoader-objekt och skickar begäran till fjärrskriptet med metoden load().

Klassen URLStream ger åtkomst till hämtade data samtidigt som de hämtas. Med klassen URLStream kan du även stänga en ström innan hämtningen har slutförts. De data som hämtats är tillgängliga som binära rådata.

Vid läsning av data från ett URLStream-objekt använder du egenskapen bytesAvailable om du vill avgöra om tillräcklig mängd data finns tillgänglig för inläsningen. Ett EOFError-undantag genereras om du försöker att läsa mer data än vad som finns tillgängligt.

När du skapar dynamiska program kan det vara användbart att läsa in data från externa filer eller från skript på servern. På det sättet kan du skapa dynamiska program utan att behöva redigera eller kompilera om programmet. Om du till exempel skapar ett program för ”dagens tips” kan du skriva ett skript på servern som hämtar ett slumpmässigt tips från en databas och sparar det i en textfil en gång om dagen. Då kan programmet läsa in innehållet från en statisk textfil i stället för att varje gång skicka en begäran till databasen.

Följande kodfragment skapar ett URLRequest- och ett URLLoader-objekt, som läser in innehållet i en extern textfil med namnet 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;

Det externa dokumentet params.txt som läses in under körningen innehåller följande data:

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

Filen innehåller två parametrar: monthNames och dayNames. Varje parameter innehåller en kommaavgränsad lista som analyseras som strängar. Du kan dela in listan i en array med hjälp av metoden String.split().

Undvik reserverade ord eller språkkonstruktioner som variabelnamn i externa datafiler, eftersom det försvårar läsningen och felsökningen av din kod.

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

Om fjärrdokumentet innehåller namnvärdespar kan du analysera data med hjälp av klassen URLVariables genom att ange innehållet i den inlästa filen enligt följande:

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

Varje namnvärdespar från den externa filen skapas som en egenskap i URLVariables-objektet. Varje egenskap i variabelobjektet i ovanstående kodexempel behandlas som en sträng. Om värdet i namnvärdesparet är en lista över objekt, kan du konvertera strängen till en array genom att anropa metoden String.split() enligt följande:

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

Om du läser in numeriska data från externa datafiler konverterar du värden till numeriska värden med hjälp av en högnivåfunktion, till exempel int(), uint() eller Number().

I stället för att läsa in innehållet i fjärrfilen som en sträng och skapa ett nytt URLVariables-objekt, kan du ställa in egenskapen URLLoader.dataFormat på en av de statiska egenskaperna som finns i klassen URLLoaderDataFormat. Det finns tre möjliga värden för egenskapen URLLoader.dataFormat:

• URLLoaderDataFormat.BINARY: Egenskapen URLLoader.data kommer att innehålla binära data lagrade i ett ByteArray-objekt.

• URLLoaderDataFormat.TEXT: Egenskapen URLLoader.data kommer att innehålla text i ett String-objekt.

• URLLoaderDataFormat.VARIABLES: Egenskapen URLLoader.data kommer att innehålla URL-kodade variabler lagrade i ett URLVariables-objekt.

Följande kod visar hur inställning av egenskapen URLLoader.dataFormat på URLLoaderDataFormat.VARIABLES gör att du automatiskt kan analysera inlästa data till ett URLVariables-objekt:

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

Som nedanstående exempel visar är inläsning av XML från en extern fil detsamma som att läsa in URLVariables. Du kan skapa en URLRequest-instans och en URLLoader-instans och sedan använda dem för att ladda ned ett XML-fjärrdokument. När filen har laddats ned skickas händelsen Event.COMPLETE och innehållet i den externa filen konverteras till en XML-instans, som du kan analysera med hjälp av XML-metoder och -egenskaper.

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

Klassen URLVariables kan inte bara användas för att läsa in externa filer. Du kan även använda den för att skicka variabler till ett skript på servern och för att bearbeta serverns svar. Det här är användbart om du till exempel programmerar ett spel och vill skicka användarens resultat till en server för att beräkna om resultatet ska läggas in i listan med bästa resultat, eller om en användares inloggningsinformation ska skickas till en server för validering. Ett skript på en server kan bearbeta användarnamnet och lösenordet, validera informationen mot en databas och sedan returnera en bekräftelse som anger om informationen är giltig.

Nedanstående utdrag skapar ett URLVariables-objekt med namnet variables, som skapar en ny variabel med namnet name. Sedan skapas ett URLRequest-objekt som anger webbadressen för skriptet på servern som variablerna ska skickas till. Sedan anger du egenskapen method för URLRequest-objektet så att variablerna skickas som en HTTP POST-begäran. Om du vill lägga till URLVariables-objektet till URL-begäran anger du det tidigare skapade URLVariables-objektet för URLRequest-objektets data-egenskap. Slutligen skapas URLLoader-instansen och metoden URLLoader.load() anropas, vilket initierar begäran.

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

Följande kod rymmer innehållet i Adobe ColdFusion®-dokumentet greeting.cfm från föregående exempel:

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