La lista dei parametri comunemente supportati di vari browsers è la seguente, in ordine alfabetico:
- onreadystatechange
- readyState
- responseText
- responseXML
- status
- statusText
L'unico a non essere pienamente supportato è l'ultimo della lista, statusText, il quale potrebbe non essere assegnato su Opera.
readyState
Il primo e fondamentale parametro da considerare durante uno scambio dati in AJAX è readyState. È una varibile di tipo intero, con valori che vanno da 0 a 4. È un parametro di sola lettura che rappresenta in ogni istante lo stato della richiesta. Gli stati che la richiesta può assumere sono :
- 0 Uninitialized l'oggetto XMLHttpRequest esiste, ma non è stato richiamato alcun metodo per inizializzare una comunicazione
- 1 Open è stato richiamato il metodo
open()ed il metodosend()non ha ancora effettuato l'invio dati - 2 Sent il metodo
send()è stato eseguito ed ha effettuato la richiesta - 3 Receiving i dati in risposta cominciano ad essere letti
- 4 Loaded l'operazione è stata completata
Questo ordine (dalla bozza di lavoro del W3C) non è sempre identico e non è sfruttabile allo stesso modo su tutti i browsers.
L'unico stato supportato da tutti è il quarto, che a prescindere dalla riuscita dell'operazione, comunicherà che l'oggetto non avrà più nulla da fare e che il cambio di stato dello stesso non andrà oltre quel valore.
Quando readyState assume un valore pari a 3, cosa che non sempre accade soprattutto qualora la richiesta dovesse fallire, si possono già conoscere alcuni headers restituiti dal server come la lunghezza del testo (content-length), il tipo di testo restituito (txt, html o xml) e quanto testo è stato ricevuto in quel momento grazie alla lunghezza della stringa responseText che esaminiamo più avanti.
Queste informazioni, purtroppo non reperibili sulle varie versioni di Internet Explorer ma si spera sfruttabili nella prossima versione 7, potrebbero essere utilizzate per creare una sorta di preload, comunicando all'eventuale visitatore a che punto è la sua richiesta e quanto manca alla ricezione completa dei dati, operazione non molto differente da quella presente molto spesso nei siti in Flash, che permette quindi di non lasciare l'utente in balia dell'attesa.
L'ultima considerazione da fare per lo stato 3 è che lo stesso potrebbe essere riassegnato diverse volte, soprattutto durante la lettura di documenti XML. Lo sviluppatore più attento eviterà che eventuali operazioni specifiche da effettuare durante la persistenza o riassegnazione di questo stato non siano sovrapposte o richiamate ogni volta, ad esempio sfruttando una variabile booleana.
Listato 9. Bloccare la comunicazione fino al completamento della lettura
// controllo lo stato ed eseguo eventuali operazioni
// solo se lo stato è uguale a 3 e solo se
// il parametro operazioniInLettura non è stato
// mai assegnato o ha un valore uguale a false
if(ajax.readyState == 3 && !ajax.operazioniInLettura) {
ajax.operazioniInLettura = true;
eventualiOperazioni(ajax);
}
// se invece lo stato è uguale a 4
else if(ajax.readyState == 4) {
// imposto le operazioni in lettura come false
// per poter risfruttare lo stesso oggetto ajax
// alla prossima interazione, superfluo quindi
// se ad ogni chiamata asincrona si ricrea
// un oggetto XMLHttpRequest
ajax.operazioniInLettura = false;
operazioniFinite(ajax);
}
È doveroso conoscere come sfruttare lo stato 3 ma nei prossimi esempi lo ignoriamo poichè non è gestibile allo stesso modo su tutti i browsers, soprattutto sul più usato IE, e non ha l'universalità dello stato 4, l'unico che prendiamo sempre in considerazione.
status
Per sapere effettivamente se lo scambio dati sia avvenuto con successo questa variabile non è comunque sufficiente Il parametro status contiene esattamente il codice HHTP di risposta restituito dal server.
Se l'interazione ha successo status contiene il valore 200 e sebbene in questa guida verrà trattato solo il suddetto valore, in questa pagina di wikipedia sarà possibile leggere la descrizione di tutti gli altri.
statusText
Possiamo trovare la descrizione del codice HTTP ritornato dal server nel parametro statusText. Questo parametro è supportato in quasi tutti i browsers, ma per avere la certezza che questo corrisponda esattamente al codice restituito, sarebbe meglio creare un oggetto apposito contenente un insieme di coppie chiave/valore in grado di fornire sempre il giusto significato dello stato.
Listato 10. Associare lo stato HTTP alla descrizione
... creazione di un oggetto descrizioneStati ...
if(ajax.readyState == 4)
alert(descrizioneStati[ajax.status]);
responseText e responseXML
Il nome dei parametri responseText e responseXML non è stato scelto a caso, questi saranno infatti i dati restituiti dal server ad operazione ultimata.
La differenza principale tra i due è che mentre responseText è un dato di tipo stringa ad interazione ultimata, responseXML potrebbe essere un oggetto null qualora i dati restituiti non dovessero essere un documento XML e quindi un oggetto utilizzabile come tale.
Lo scopo del parametro responseText è infatti quello di poter ricevere comunque informazioni dal server.
Ad esempio, una pagina richiamata ma non più presente genera un errore con status pari a 404 ed il più delle volte il server darà una comunicazione di servizio che informerà l'utente dell'assenza del documento.
Questa risposta potrebbe non essere un documento XML e per questo è utile leggere il responseText contenente il testo restituito dal server.
Sapendo che qualora il testo restituito sia un documento XML, responseText verrebbe comunque assegnato con la sua rappresentazione testuale, molti sviluppatori sfruttano quest'ultimo parametro per ricevere dei contenuti a prescindere dalla natura degli stessi, semplificando le operazioni di parsing necessarie per un XML ed avendo subito a disposizione quanto letto.