Ładowanie danych zewnętrznych

Wiele interfejsów API służących do ładowania danych zewnętrznych wykorzystuje klasę URLRequest w celu zdefiniowania właściwości wymaganego żądania sieci.

Klasa URLLoader umożliwia wysyłanie żądania na serwer i uzyskiwanie dostępu do zwracanych informacji. Klasę URLLoader można również wykorzystać w celu uzyskania dostępu do plików z lokalnego systemu plików w sytuacjach, gdy dozwolony jest dostęp do plików lokalnych (np. obszar izolowany lokalny z systemem plików Flash Player oraz obszar izolowany aplikacji AIR). Klasa URLLoader pozwala pobierać dane spod adresu URL; można je pobierać w postaci tekstu, danych binarnych i zakodowanych zmiennych. Klasa URLLoader wywołuje takie zdarzenia, jak complete , httpStatus , ioError , open , progress i securityError .

Model obsługi zdarzeń ActionScript 3.0 znacznie różni się od modelu ActionScript 2.0, w którym były wykorzystywane moduły obsługi zdarzeń LoadVars.onData , LoadVars.onHTTPStatus i LoadVars.onLoad . Więcej informacji na temat obsługiwania zdarzeń w ActionScript 3.0 zawiera sekcja Obsługa zdarzeń

Pobrane dane nie są dostępne do czasu zakończenia pobierania. Postęp pobierania (liczbę bajtów pobranych i całkowitą liczbę bajtów) można monitorować, wykrywając wywołanie zdarzenia progress . Jeśli jednak plik zostanie załadowany bardzo szybko, zdarzenie progress może nie zostać wywołane ani razu. Po pomyślnym pobraniu pliku następuje wywołanie zdarzenia complete . Poprzez ustawienie właściwości dataFormat klasy URLLoader można otrzymywać dane jako obiekty tekstowe, surowe dane binarne lub obiekt URLVariables.

Metoda URLLoader.load() (i opcjonalnie konstruktor klasy URLLoader) przyjmuje pojedynczy parametr request , który jest obiektem URLRequest. Obiekt URLRequest zawiera wszystkie informacje dla pojedynczego żądania HTTP, takie jak docelowy adres URL, metoda żądania ( GET lub POST ), dodatkowe informacje nagłówka, a także typ MIME.

Na przykład: aby wysłać pakiet XML do skryptu po stronie serwera, można użyć poniższego kodu:

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

Poprzedni urywek tworzy dokument XML o nazwie dataXML , który zawiera pakiet XML przeznaczony do wysłania na serwer. W przykładzie ustawiono właściwość contentType klasy URLRequest na wartość „text/xml" i przypisano dokument XML do właściwości data klasy URLRequest. Na końcu przykładu utworzono obiekt URLLoader i wysłano żądanie do zdalnego skryptu poprzez zastosowanie metody load() .

Klasa URLStream zapewnia dostęp do pobieranych danych w miarę ich ładowania. Klasa URLStream umożliwia również zamknięcie strumienia przed zakończeniem ładowania. Pobrane dane są dostępne jako surowe dane binarne.

Podczas odczytu danych z obiektu URLStream należy użyć właściwości bytesAvailable w celu określenia, czy dostępna jest wystarczająca ilość danych przed ich odczytaniem. W przypadku podjęcia próby odczytu większej ilości danych niż dostępna wywoływany jest wyjątek EOFError.

W aplikacjach dynamicznych stosuje się często technikę ładowania danych z plików zewnętrznych lub skryptów serwerowych. Umożliwia to budowanie dynamicznych aplikacji bez konieczności edycji lub ponownego kompilowania aplikacji. Przykład: w przypadku tworzenia aplikacji „wskazówka dnia” można napisać skrypt serwerowy, który będzie losowo pobierał wskazówkę z bazy danych i zapisywał ją w pliku tekstowym raz dziennie. Następnie aplikacja może wysłać treść statycznego pliku tekstowego zamiast generowania zapytania do bazy danych za każdym razem.

Poniższy urywek tworzy obiekt URLRequest i URLLoader, który ładuje treść zewnętrznego pliku tekstowego 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;

Zewnętrzny dokument — params.txt — ładowany w czasie wykonywania, zawiera następujące dane:

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

Plik zawiera dwa parametry: monthNames i dayNames . Każdy parametr zawiera rozdzielaną przecinkami listę, której elementy są analizowane jako ciągi znaków. Listę można rozdzielić na tablicę, korzystając z metody String.split() .

Nazwy zmiennych w plikach zewnętrznych nie powinny zawierać słów zarezerwowanych ani konstrukcji językowych, ponieważ może to spowodować utrudnienie odczytywania i debugowania kodu.

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

Jeśli zdalny dokument zawiera pary nazwa-wartość, można analizować dane za pomocą klasy URLVariables, przekazując zawartość wysłanego pliku, jak poniżej:

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

Każda para nazwa-wartość z zewnętrznego pliku jest tworzona jako właściwość w obiekcie URLVariables. Każda właściwość w obiekcie zmiennych z poprzedniego kodu jest traktowana jako ciąg znaków. Jeśli wartością pary nazwa-wartość jest lista elementów, ciąg znaków można zamienić na tablicę poprzez wywołanie metody String.split() w następujący sposób:

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

W przypadku wysyłania danych liczbowych z zewnętrznych plików tekstowych wymagana jest konwersja wartości na wartości liczbowe za pomocą funkcji najwyższego poziomu, takiej jak int() , uint() lub Number() .

Zamiast wysyłania treści pliku zdalnego w postaci ciągu znaków i tworzenia nowego obiektu URLVariables można ustawić właściwość URLLoader.dataFormat na jedną z właściwości statycznych dostępnych w klasie URLLoaderDataFormat. Trzy możliwe wartości właściwości URLLoader.dataFormat są następujące:

• URLLoaderDataFormat.BINARY — właściwość URLLoader.data będzie zawierała dane binarne zapisane w obiekcie ByteArray.

• URLLoaderDataFormat.TEXT — właściwość URLLoader.data będzie zawierała tekst w obiekcie String.

• URLLoaderDataFormat.VARIABLES — właściwość URLLoader.data będzie zawierała zmienne (zakodowane w adresie URL) zapisane w obiekcie URLVariables.

Poniższy kod przedstawia sposób, w jaki ustawienie URLLoaderDataFormat.VARIABLES dla właściwości URLLoader.dataFormat umożliwia automatyczne analizowanie wysłanych danych na obiekt 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); 
        } 
    } 
}

W poniższym przykładzie przedstawiono ładowanie danych XML z zewnętrznego pliku w ten sam sposób, jak wysyłanie URLVariables. W celu pobrania zdalnego dokumentu XML można utworzyć instancję URLRequest oraz instancję URLLoader. Po pobraniu całego pliku następuje wywołanie zdarzenia Event.COMPLETE , a treść zewnętrznego pliku zostaje przekonwertowane na instancję XML, którą można przeanalizować za pomocą metod i właściwości 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()); 
        } 
    } 
}

Oprócz wysyłania zewnętrznych plików danych klasa URLVariables może również służyć do wysyłania zmiennych do skryptów serwerowych oraz przetwarzania odpowiedzi serwera. Jest to użyteczne szczególnie w przypadku programowania gry, gdy wymagane jest przesyłanie punktacji użytkownika na serwer w celu obliczenia, czy punktacja powinna zostać dodana do listy rekordów, a także w przypadku wysyłania danych logowania użytkownika na serwer w celu sprawdzenia poprawności. Skrypt serwerowy może przetworzyć nazwę i hasło użytkownika, sprawdzić jego poprawność w bazie danych, a następnie zwrócić potwierdzenie dotyczące tego, czy dane wprowadzone przez użytkownika są poprawne.

Poniższy urywek tworzy obiekt URLVariables o nazwie variables, , który tworzy nową zmienną o nazwie name . Następnie zostaje utworzony obiekt URLRequest, który określa adres URL skryptu serwerowego, do którego wysyłane są zmienne. Następnie użytkownik ustawia właściwość method obiektu URLRequest w celu wysłania zmiennych w postaci żądania HTTP POST . Aby dodać obiekt URLVariables do żądania URL, należy ustawić dla właściwości data obiektu URLRequest obiekt URLVariables utworzony wcześniej. Na koniec następuje utworzenie instancji URLLoader oraz wywołanie metody URLLoader.load() , która inicjuje żądanie.

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

Poniższy kod zawiera treść dokumentu Adobe ColdFusion® greeting.cfm, który został wykorzystany w poprzednim przykładzie:

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