Caricamenti multipli con ActionScript 3 e BulkLoader

Le potenzialità di caricamento di elementi esterni (quali ad esempio video, immagini e suoni) fanno sì che si possano aggiornare facilmente i contenuti e il layout del proprio lavoro senza dover ricompilare il proprio progetto ma semplicemente cambiando i file da esso caricati.

Questo rende necessari alcuni accorgimenti, per esempio può essere necessario creare dei controlli per fare in modo che il filmato parta soltanto una volta completato il caricamento dei dati esterni (specialmente per i progetti in ambito Web dove il tipo di linea influisce sul caricamento), inoltre a seconda del tipo di contenuto da caricare possono essere necessarie azioni diverse; per chi ha a che fare con il caricamento di un buon numero di risorse esterne e vuole semplificare il procedimento di caricamento e controllo degli elementi, un’ottima soluzione è rappresentata dalla classe BulkLoader.

Non si tratta di una classe già presente in Flash, ma è una classe sviluppata da Arthur Debert rilasciata sotto licenza MIT.

Caratteristiche principali della classe

I principali vantaggi dell’uso di una classe già “pronta allo scopo” sono in termini di stesura del codice; usando un minor numero di comandi (dovremo imparare solo quelli previsti dalla classe BulkLoader) risparmieremo tempo, inoltre avremo un codice che già prevede molti controlli e quindi non dovremo effettuare test particolari.

Vediamo alcune delle caratteristiche principali della classe BulkLoader:

• gestione degli eventi per singoli file o per gruppi di file;
• possibilità di impostare la priorità di caricamento;
• possibilità di fermare e riavviare un caricamento;
• gestione della cache;
• statistiche sul caricamento (velocità, velocità media, tempo di latenza);
• indicatori del progresso di caricamento (file caricati, file ancora da caricare, ecc);
• numero configurabili di tentativi di caricare un file;
• log delle operazioni e degli errori.

Le più comuni operazioni di caricamento di file esterni sono completamente gestibili con questa classe, in più sono racchiuse in un numero di comandi ridotto rispetto a quello che ci servirebbe se provassimo a scrivere un codice che si occupi di tutte queste operazioni.

Vediamo allora come utilizzare praticamente questa classe, ovvero come creare un’istanza del BulkLoader, aggiungervi degli elementi da caricare, avviare il caricamento, seguirne il progresso e infine inserire sullo stage uno o più elementi caricati.

Creazione di un’istanza della classe

Per prima cosa è necessario importare la classe BulkLoader: il suo package di default è br.com.stimuli.loading, per cui il nostro codice inizierà con:

In questo modo andiamo a importare tutte le classi presenti nel package e avremo completo accesso a metodi, eventi e proprietà del BulkLoader. Dopo aver importato le classi dobbiamo dichiarare un’istanza del BulkLoader; il costruttore della classe prevede anche un parametro di tipo stringa che sarà il nome del nostro BulkLoader e potremo utilizzarlo per ricavarne un riferimento da altre classi.

Per creare un’istanza di tipo BulkLoader basta il seguente codice:

Dalla classe dove dichiariamo l’istanza basterà usare la variabile caricatore per accedere all’oggetto, mentre da eventuali classi esterne potremo prima creare un riferimento con un codice di questo tipo:

Il nome del loader è l’unico parametro obbligatorio ma abbiamo anche due parametri opzionali: il numero massimo di connessioni da aprire simultaneamente e il livello di log; per impostare un loader con un massimo di 5 connessioni simultanee e un log completo di tutti gli eventi possiamo utilizzare questo codice:

Le opzioni disponibili per il livello di logging sono:

• LOG_SILENT: non verrà memorizzata nessuna operazione;
• LOG_ERRORS: vengono memorizzati il mancato caricamento di un oggetto oppure il mancato reperimento di un elemento;
• LOG_INFO: tiene in memoria le informazioni di LOG_ERRORS e inoltre memorizza l’inizio e la fine del caricamento di ogni elemento, quando tutti gli elementi sono caricati e quando un’operazione di caricamento riceve una risposta dal server;
• LOG_VERBOSE: il log più completo, memorizza tutte le informazioni di LOG_INFO e inoltre memorizza quando un elemetno viene aggiunto alla lista dei file, quando un elemento viene rimosso dalla lista dei file, quando viene fermato o riavviato il caricamento di un elemento e tutte le statistiche di download degli elementi caricati.

Il valore di default è LOG_ERRORS.

Aggiunta dei file da caricare

A questo punto abbiamo a disposizione un oggetto BulkLoader pronto da popolare, quindi passiamo all’inserimento dei percorsi dei file; va notato che per quanto si ci possa limitare a inserire l’URL della risorsa da caricare, in questa fase possiamo personalizzare un gran numero di opzioni per ogni elemento.

Il comando per aggiungere un file alla lista degli elementi da caricare è add e l’opzione più semplice prevede l’inserimento del solo indirizzo del file da caricare, che possiamo passare sotto forma di stringa oppure come oggetto URLRequest:

Per ogni file eseguiremo un add, quindi per caricare ad esempio i file “file.txt”,”image.jpg”,”video.flv” e “sound.mp3” il nostro codice sarebbe:

Specificare il tipo di file

Normalmente il BulkLoader riconosce il tipo di file da caricare in base all’estensione, tuttavia è possibile utilizzare il parametro type per specificare se il file è un semplice testo, un xml, un’immagine o altro ancora: questo parametro è utile nei casi in cui Flash non può riconoscere il tipo di contenuto dall’estensione, questo potrebbe verificarsi ad esempio se la fonte dei dati fosse un file PHP, che può restituire un testo, un XML o un’immagine, in questo caso è utile comunicare al BulkLoader che tipo di dato vogliamo che venga caricato, in questo modo:

Se la classe non riesce a riconoscere il file dall’estensione e non specifichiamo esplicitamente il tipo di dato, come impostazione di default verrà caricato come testo.

Di default la classe riconosce dall’estensione file di tipo swf, jpg, gif, png, mp3, xml, php, txt, py, asp e flv, è comunque possibile specificare delle nuove estensioni grazie al comando registerNewType, per esempio qualora volessimo rendere riconoscibili i file wmv dovremmo usare:

I tre parametri sono rispettivamente l’estensione, il tipo di Loader e la classe, infatti per le nuove estensioni dovremmo impostare una classe contenente i comandi adatti per quel tipo di file; è tuttavia piuttosto raro che non siano sufficienti i file già riconoscibili dalla classe BulkLoader dato che coprono pressoché completamente la gamma di file caricabili e utilizzabili nel Flash Player.

Evitare la memorizzazione in cache

Spesso si ha la necessità di non memorizzare in cache alcuni elementi, così che vengano caricati sempre “da zero” quando un utente visita la pagina per essere sicuri che vengano aggiornati subito e non capiti invece che ne venga richiamata una vecchia versione dalla cache; solitamente per evitare che l’elemento venga salvato in memoria si aggiunge all’url del file un parametro casuale, per esempio non si richiama “file.php” ma “file.php?r=”Math.random()*9999. La classe BulkLoader gestisce autonomamente questa operazione, basta sfruttare l’opzione preventCache, in questo modo:

Come impostazione predefinita, preventCache è impostato a false e quindi prevede la memorizzazione in cache degli elementi.

Gestire il numero di tentativi di caricamento

In qualche caso può capitare che un file non venga caricato correttamente: è una situazione abbastanza rara se il file è presente e non corrotto, tuttavia magari per colpa di un server sovraccarico oppure di una connessione instabile può capitare che una chiamata vada a vuoto: la classe BulkLoader permette di configurare il numero di tentativi per caricare un file, grazie all’opzione maxTries. Per esempio utilizzando la riga di codice:

Faremo sì che vengano effettuati cinque tentativi prima di considerare fallito il caricamento del file; il valore di default per maxTries è 3, pressoché sufficiente per qualsiasi situazione.

Priorità e ordine di caricamento

Per quanto comunemente sia consigliato attendere il caricamento di tutti gli elementi, e quindi non faccia grossa differenza quale file sia caricato per primo, in alcuni casi (magari se abbiamo molti elementi caricati esternamente) potremmo voler avviare il nostro filmato mentre il loading dei file è ancora in corso. In questo caso vorremo essere sicuri che siano già stati caricati gli elementi che ci servono almeno nelle prime schermate, lasciando poi che gli altri oggetti si carichino mentre il filmato è partito. In questo caso torna molto utile l’opzione priority, che permette appunto di stabilire l’ordine di caricamento dei file. Nel seguente codice verranno caricati prima file4.txt, poi file3.txt e infine file1.txt e file2.txt.

Nel caso in cui due elementi abbiano lo stesso valore di priority, assume la precedenza quello inserito prima nella lista di elementi da caricare (infatti tra file1.txt e file2.txt, entrambi con priority uguale a 0, verrà caricato prima file1.txt).

Assegnazione di eventi a un singolo file

Sempre in un’ottica per cui vogliamo caricare inizialmente solo alcuni elementi, è molto utile la possibilità di assegnare uno o più eventi a un singolo file: in questo modo è possibile ricavare ad esempio il caricamento completo di uno specifico file, senza attendere che siano stati caricati anche tutti gli altri. Per esempio con il seguente codice:

Potremo ricavare a parte rispetto a tutto il resto il completo caricamento dell’immagine “image.jpg”. Gli eventi disponibili sono onComplete e onProgress e questo vale anche per l’intero BulkLoader e non solo per i suoi singoli file.

Invio di header al file

Qualora avessimo la necessità di inviare degli header al file da caricare, possiamo utilizzare l’opzione headers, che richiede come valore un array contenente degli URLRequestHeader. Con il seguente esempio inviamo un header personalizzato al file PHP da caricare:

Assegnare un ID al file

Normalmente per recuperare i dati di un file caricato all’interno del BulkLoader si può utilizzare il path che abbiamo passato alla classe, come vedremo in seguito, tuttavia può essere molto utile utilizzare un ID, sicuramente più semplice da ricordare specialmente nel caso di file con URL particolarmente lunghi. La sintassi è molto semplice, basta usare l’opzione id:

In questo modo non dovremo fare riferimento al path per richiamare l’oggetto, ma basterà fare riferimento a immagine.

Assegnare un peso al file

Il parametro weight permette di assegnare un “peso” al nostro file. Ha utilità esclusivamente nel processo di caricamento e risulta utile nel caso in cui volessimo creare un preload che informi ad esempio sulla percentuale di caricamento basata sui bytes caricati: purtroppo la proprietà bytesLoaded della classe non è disponibile finché non è stato avviato il caricamento di tutti gli oggetti, quindi ci ritroveremmo con un valore “0” per diverso tempo e solo a caricamento ormai quasi completo riceveremmo un valore utilizzabile; ecco allora che entra in gioco l’opzione weight, grazie a cui possiamo associare un “peso” ai vari file e usare poi la proprietà weightPercent.

Avendo, ad esempio, un file swf da 1.5 MB, un XML da 100 KB e un’immagine da 300 KB, potremmo usare la proprietà weight come di seguito:

Ovviamente non è importante che il valore corrisponda esattamente ai kilobyte del file, l’importante è che sia mantenuta la proporzione tra i pesi dei vari elmenti così da avere un responso affidabile dalla proprietà weightPercent, difatti potremmo anche utilizzare il seguente codice (dove il rapporto tra weight è peso è 1 = 100 KB):

Sono comunque disponibili altri indicatori di progresso per il caricamento e quindi si può evitare questa opzione anche nel caso di caricamenti molto corposi.

Avvio e controllo del caricamento

Una volta completata la lista di elementi da caricare, è sufficiente utilizzare il comando start per dare il via alle operazioni di caricamento. Ovviamente è consigliabile associare dei listener all’oggetto così da poter controllare il progresso e il completo caricamento della lista di elementi; come abbiamo detto in precedenza i due eventi disponibili per il caricamento sono COMPLETE e PROGRESS, quindi possiamo aggiungere due listener al nostro oggetto in questo modo:

Possiamo poi tenere traccia degli eventuali errori usando l’evento ERROR in questo modo:

Avviamo quindi le operazioni con: