Chargement de données externes

Un grand nombre d’API qui chargent des données externes font appel à la classe URLRequest pour définir les propriétés de la requête réseau requise.

La classe URLLoader permet d’envoyer une requête à un serveur et d’accéder aux informations renvoyées. Vous disposez également de la classe URLLoader pour accéder aux fichiers du système de fichiers local dans les contextes où l’accès aux fichiers locaux est autorisé (le sandbox local avec système de fichiers de Flash Player et le sandbox d’application AIR, par exemple). La classe URLLoader télécharge des données à partir d’une URL sous forme de texte, de données binaires ou de variables codées au format URL. La classe URLLoader distribue des événements tels que complete , httpStatus , ioError , open , progress et securityError .

Le modèle de gestion des événements d’ActionScript 3.0 est sensiblement différent du modèle d’ActionScript 2.0, qui utilisait les gestionnaires d’événement LoadVars.onData , LoadVars.onHTTPStatus et LoadVars.onLoad . Pour plus d’informations sur la gestion des événements en ActionScript 3.0, voir Gestion des événements .

Les données téléchargées ne sont pas disponibles tant que le téléchargement n’est pas terminé. Pour surveiller la progression du téléchargement (nombre d’octets chargés et nombre total d’octets), écoutez la distribution de l’événement progress . Toutefois, si le chargement d’un fichier est rapide, l’événement progress risque de ne pas être distribué. Une fois que le téléchargement d’un fichier est terminé, l’événement complete est distribué. En définissant la propriété dataFormat de la classe URLLoader, vous pouvez recevoir les données sous forme de texte, de données binaires brutes ou d’objet URLVariables.

La méthode URLLoader.load() (et éventuellement le constructeur de la classe URLLoader) gère un seul paramètre, request , qui correspond à un objet URLRequest. Un objet URLRequest contient toutes les informations d’une requête HTTP unique, telles que l’URL cible, la méthode de requête ( GET ou POST ), d’autres informations d’en-tête et le type MIME.

Pour charger un paquet XML dans un script côté serveur, par exemple, vous pouvez utiliser le code ci-après :

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

L’extrait ci-dessus crée un document XML appelé dataXML , qui contient le paquet XML à envoyer au serveur. L’exemple définit la propriété contentType de l’objet URLRequest sur "text/xml" et affecte le document XML à la propriété data de l’objet URLRequest. Il crée enfin un objet URLLoader et envoie la requête au script distant par le biais de la méthode load() .

La classe URLStream permet d’accéder aux données en cours de téléchargement au fur et à mesure de leur arrivée. Elle permet également de fermer un flux continu avant la fin du téléchargement. Les données téléchargées sont disponibles au format binaire brut.

Lorsque vous lisez les données issues d’un objet URLStream, faites appel à la propriété bytesAvailable pour déterminer si les données disponibles sont suffisantes avant de les lire. Une exception EOFError est renvoyée si vous essayez de lire des données qui ne sont pas disponibles.

Lorsque vous programmez des applications dynamiques, il peut s’avérer utile de charger des données issues de fichiers externes ou de scripts côté serveur. Vous pouvez ainsi programmer des applications dynamiques sans avoir à les modifier ou les recompiler. Par exemple, si vous créez une application « conseil du jour », vous pouvez écrire un script côté serveur qui récupère un conseil au hasard dans une base de données et l’enregistre dans un fichier texte une fois par jour. Votre application peut ensuite charger le contenu du fichier texte statique au lieu d’envoyer une requête à la base de données à chaque fois.

L’extrait de code suivant crée un objet URLRequest et URLLoader, qui charge le contenu d’un fichier texte externe nommé 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;

Le document externe, params.txt, chargé au moment de l’exécution, contient les données suivantes :

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

Le fichier contient deux paramètres, monthNames et dayNames . Chacun des paramètres contient une liste séparée par des virgules qui est analysée sous forme de chaîne. Vous pouvez transformer cette liste en tableau à l’aide de la méthode String.split() .

Evitez d’utiliser des mots réservés ou des éléments de langage comme noms de variables dans les fichiers de données externes, car cela complique la lecture et le débogage du code.

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

Si le document distant contient des paires nom-valeur, vous pouvez analyser les données à l’aide de la classe URLVariables en transmettant le contenu du fichier chargé, comme suit :

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

Chaque paire nom-valeur issue du fichier externe devient une nouvelle propriété de l’objet URLVariables. Chaque propriété de cet objet dans l’exemple de code précédent est traité comme une chaîne. Si la valeur de la paire nom-valeur est une liste d’éléments, vous pouvez convertir la chaîne en tableau en appelant la méthode String.split() , comme suit :

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

Si vous chargez des données numériques à partir de fichiers externes, convertissez-les en valeurs numériques à l’aide d’une fonction de niveau supérieur, telle que int() , uint() ou Number() .

Au lieu de charger le contenu du fichier distant sous forme de chaîne et de créer un objet URLVariables, vous pouvez attribuer à la propriété URLLoader.dataFormat la valeur de l’une des propriétés statiques de la classe URLLoaderDataFormat. Les trois valeurs possibles de la propriété URLLoader.dataFormat sont les suivantes :

• URLLoaderDataFormat.BINARY : la propriété URLLoader.data contient des données binaires stockées dans un objet ByteArray.

• URLLoaderDataFormat.TEXT : la propriété URLLoader.data contient du texte sous forme d’objet String.

• URLLoaderDataFormat.VARIABLES : la propriété URLLoader.data contient des variables encodées au format URL issues d’un objet URLVariables.

Le code suivant montre comment vous pouvez automatiquement analyser les données chargées dans un objet URLVariables en attribuant à la propriété URLLoader.dataFormat la valeur URLLoaderDataFormat.VARIABLES .

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

Comme le montre l’exemple suivant, le chargement de données XML à partir d’un fichier externe s’effectue comme le chargement de données URLVariables. Vous pouvez créer une occurrence d’URLRequest et une occurrence d’URLLoader et vous en servir pour télécharger un document XML distant. Lorsque le fichier est complètement téléchargé, l’événement Event.COMPLETE est distribué et le contenu du fichier externe est converti en occurrence de XML, que vous pouvez analyser avec les méthodes et propriétés 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()); 
        } 
    } 
}

Outre le chargement de fichiers de données externes, la classe URLVariables permet d’envoyer des variables à un script côté serveur et de traiter la réponse du serveur. Cela s’avère utile, par exemple, si vous programmez un jeu et souhaitez envoyer le score de l’utilisateur à un serveur afin de vérifier s’il faut l’ajouter à la liste des scores les plus élevés ; ou encore envoyer les informations de connexion de l’utilisateur au serveur pour validation. Un script côté serveur peut traiter le nom d’utilisateur et le mot de passe, les comparer à une base de données et confirmer en retour la validité des informations fournies par l’utilisateur.

L’extrait de code ci-après crée un objet URLVariables nommé variables , qui génère une nouvelle variable appelée name . Ensuite, un objet URLRequest est créé pour spécifier l’URL du script côté serveur à laquelle doivent être envoyées les variables. Vous pouvez alors définir la propriété method de l’objet URLRequest pour envoyer les variables sous forme de requête HTTP POST . Pour ajouter l’objet URLVariables à la requête URL, définissez la propriété data de l’objet URLRequest sur l’objet URLVariables créé plus tôt. Enfin, l’occurrence de URLLoader est créée et la méthode URLLoader.load() appelée ; cette dernière lance la requête.

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

Le code suivant reprend le contenu du document Adobe ColdFusion® greeting.cfm utilisé dans l’exemple précédent :

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