Obiectul W3C XMLHttpRequest

Obiectul W3C XMLHttpRequest

Obiectul XMLHttpRequest este o interfata de programare a aplicatiilor (Application Programming Interface) care permite scripturilor sa realizeze functionalitati ale unui client HTTP, ca de exemplu trimiterea datelor incluse in formulare sau incarcarea datelor stocate pe un site Web. Obiectul XMLHttpRequest are o serie de metode si proprietati (atribute) definite in specificatia publicata de Consortiul Web.

1 Metode Metodele obiectului XMLHttpRequest sunt urmatoarele:

open(metoda, url[, async[, utilizator[, parola]]]): initializeaza o cerere HTTP catre serverul Web, seteaza proprietatea readyState la valoarea 1(Open), reseteaza proprietatile responseText responseXML status si statusText la valorile lor initiale si reseteaza lista anteturilor cererii. Daca metoda este apelata in situatia in care valoarea proprietatii readyState este 4 (Loaded), atunci obiectul XMLHttpRequest va fi resetat. Primeste ca argumente metoda (metoda, de tip DOMString) care va fi utilizata de cerere, URL-ul (url, de tip DOMString) folosit pentru conexiunea cu serverul si alti parametrii ai cererii curente. Primii doi parametrii sunt obligatorii. Metodele care pot fi utilizate sunt cele ale protocolului HTTP. Cel mai des utilizate sunt GET (daca se intentioneaza obtinerea unor date de pe server), POST (daca se doreste trimiterea datelor pe server sau daca se doreste modificarea sau crearea resurselor pe server) si HEAD (daca se doreste obtinerea anteturilor unei resurse). Al treilea parametru (async, de tip boolean) este optional si precizeaza daca tranzactiile cu serverul trebuie manipulate sincron sau asincron. Ceilalti doi parametrii optionali (avand fiecare valoarea implicita null) sunt numele de utilizator (utilizator, de tip DOMString) si parola (parola, de tip DOMString), utilizati in cazul in care conectarea la server necesita autentificare. Metoda nu genereaza exceptii;

send([data]): transmite cererea catre server. Aceasta poate avea, optional, date incluse ca un parametru (data), sub forma unui sir sau a unui obiect DOM. Daca proprietatea readyState are o valoare diferita de 1 (Open), va fi generata o exceptie INVALID_STATE_ERR. Altfel, proprietatea respectiva trebuie sa fie setata la valoarea 2 (Sent), cererea fiind trimisa. Daca metoda utilizata in cerere este POST sau PUT, datele plasate metodei send() (argumentul data) vor fi utilizate in corpul mesajului HTTP;

abort( : opreste cererea curenta. Cand este invocata, metoda trebuie sa anuleze orice activitate de transmitere de date pentru care este responsabil obiectul si sa il reseteze. Metoda nu primeste parametrii, nu intoarce nicio valoare si nu genereaza exceptii;

getAllResponseHeaders( : intoarce sub forma unui sir de caractere setul complet de anteturi HTTP (nume si valori) ale unei resurse, fiecare antet fiind plasat pe o linie separata de celelalte prin perechea CR si LF. Daca proprietatea readyState are o alta valoare decat 3 (Receiving) sau 4 (Loaded), metoda intoarce null. Aceasta metoda nu primeste argumente si nu genereaza exceptii;

getResponseHeader(antet): intoarce sub forma unui sir de caractere valoarea antetului antet (de tip DOMString) inclus in anteturile HTTP ale raspunsului serverului. Daca au fost primite mai multe valori ale unui antet avand numele precizat, acestea sunt concatenate, separate unul de celalalt prin caracterul virgula urmat de caracterul spatiu. Daca nu exista niciun antet avand numele specificat, metoda intoarce un sir vid. In cazul in care proprietatea readyState are o valoare diferita de 3 (Receiving) sau 4 (Loaded), va intoarce un sir vid. Metoda nu genereaza exceptii;

setRequestHeader(antet, valoare): seteaza un antet HTTP al cererii curente. Daca atributul readyState are o valoare diferita de 1 (Open), va fi generata o exceptie UNKNOWN_ERR. Daca argumentele antet sau valoare contin oricare dintre caracterele CR sau LF, sau daca argumentul antet contine oricare dintre caracterele spatiu sau doua puncte, apelul metodei nu va avea niciun efect. Daca antetul antet a fost deja trimis, noua valoare va fi concatenata cu valoarea existenta, utilizand caracterul virgula urmat de spatiu. Inainte de a fi apelata aceasta metoda, trebuie utilizata metoda open(

2 Proprietati Dupa trimiterea cererii, pot fi utilizate proprietatile instantei obiectului XMLHttpRequest:   

onreadystatechange (Function): ofera o modalitate de tratare a evenimentului readyState la fiecare schimbare a starii acestuia. Astfel, prin intermediul acestei proprietati poate fi precizata o functie pentru procesarea raspunsului serverului (callback). Se pot efectua apeluri multiple ale functiei, daca atributul readyState are valoarea 3 (Receiving);

readyState unsigned short), readonly: se precizeaza ca un intreg care indica starea obiectului XMLHttpRequest. Valorile sale sunt: 0 (Uninitialized; neinitializat: obiectul a fost creat, dar metoda open()nu a fost apelata), 1 (Open; cererea este in curs de incarcare: obiectul afost creat, conexiunea deschisa, dar metoda send()nu a fost apelata), 2 (Sent; cererea a fost trimisa: metoda send()a fost apelata, proprietatea status este disponibila, dar raspunsul serverului inca nu a fost primit), 3 (Receiving; interactiv: o parte din rezultate au fost primite; acestea pot fi obtinute utilizand proprietatea responseText) si 4 (Loaded; cererea este rezolvata: toate rezultatele au fost primite, ele fiind disponibile ca valoare a proprietatii responseText

responseText DOMString): are ca valoare, sub forma unui sir, datele intoarse de server. Daca readyState are o valoare diferita de 3 (Receiving) sau 4 (Loaded), valoarea sa va fi un sir vid. In celelalte cazuri va fi corpul datelor primite, interpretate conform codificarii precizate in raspuns;

responseXML Document): include datele intoarse de server sub forma unui document XML, care poate fi prelucrat ulterior. Daca readyState are o valoare diferita de 4 (Loaded), proprietatea are valoarea null

status unsigned short): daca proprietatea readyState are valoarea 3 (Receiving) sau 4 (Loaded), status contine un cod numeric de raspuns intors de server la cererea emisa de client, acesta fiind chiar codul de stare HTTP. Daca readyState are o alta valoare, proprietatea status nu este disponibila, accesarea ei generand o exceptie INVALID_STATE_ERR

statusText DOMString): daca proprietatea readyState are valoarea 3 (Receiving) sau 4 (Loaded), statusText are ca valoare, sub forma de sir, un mesaj explicativ de raspuns intors de server la cererea emisa de client, in acord cu codul numeric precizat de proprietatea status. Daca readyState are o alta valoare, proprietatea statusText nu este disponibila, accesarea ei generand o exceptie INVALID_STATE_ERR