XMLHttpRequest

z Mozilla Developer Center, polskiego centrum programistów Mozilli.

Obiekt XMLHttpRequest jest obiektem JavaScript zaprojektowanym przez firmę Microsoft i zaadaptowanym w programach Mozilla. Służy do pobierania danych przy użyciu protokołu HTTP. Wbrew nazwie może być stosowany do obsługi dokumentów w wielu formatach, nie tylko XML. W silniku Gecko w obiekcie zaimplementowano interfejsy nsIJSXMLHttpRequest i nsIXMLHttpRequest. W najnowszych wersjach Gecko dokonano pewnych modyfikacji tego obiektu — patrz artykuł Zmiany w obiekcie XMLHttpRequest w Gecko 1.8.

[edytuj] Podstawy

Korzystanie z obiektu XMLHttpRequest jest bardzo proste. Należy utworzyć instancję obiektu, otworzyć adres URL, po czym wysłać żądanie. Zwrócony przez serwer kod stanu HTTP, jak również pobrany dokument są następnie dostępne jako własności obiektu żądania.

Uwaga: W wersjach Firefoksa starszych niż 3 żądania są zawsze wysyłane przy użyciu kodowania UTF-8 — dopiero program Firefox 3 wysyła dokument poprawnie przy użyciu kodowania określonego we własności data.xmlEncoding; jeżeli nie określono żadnego kodowania, używane jest kodowanie UTF-8.

[edytuj] Przykład

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', false); 
req.send(null);
if(req.status == 200)
  dump(req.responseText);

[edytuj] Przykład dla protokołu innego niż HTTP

var req = new XMLHttpRequest();
req.open('GET', 'file:///home/user/file.json', false); 
req.send(null);
if(req.status == 0)
  dump(req.responseText);

[edytuj] Zastosowanie asynchroniczne

W przypadku korzystania z obiektów XMLHttpRequest w rozszerzeniu Firefoksa pobierane dane powinny być ładowane asynchronicznie. Po całkowitym pobraniu danych przekazywane jest wywołanie zwrotne (ang. callback), co pozwala na normalną pracę przeglądarki podczas przetwarzania żądania.

[edytuj] Przykład

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.onreadystatechange = function (aEvt) {
  if (req.readyState == 4) {
     if(req.status == 200)
      dump(req.responseText);
     else
      dump("Błąd podczas ładowania strony\n");
  }
};
req.send(null); 

[edytuj] Monitorowanie postępu

Obiekt XMLHttpRequest umożliwia monitorowanie wielu zdarzeń, które mogą wystąpić podczas przetwarzania żądania — służą do tego okresowe powiadomienia o postępie przetwarzania, komunikaty o błędach itp.

Jeżeli na przykład w czasie pobierania dokumentu do użytkownika mają być wysyłane informacje o postępie przetwarzania, można skorzystać z poniższego kodu:

function onProgress(e) {
  var percentComplete = (e.position / e.totalSize)*100;
  ...
}

function onError(e) {
  alert("Podczas pobierania dokumentu wystąpił błąd " + e.target.status + ".");
}

function onLoad(e) {
  // ...
}
// ...
var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.open("GET", url, true);
req.onload = onLoad;
req.onerror = onError;
req.send(null);

Atrybuty zdarzenia onprogress, position i totalSize, wskazują odpowiednio liczbę pobranych dotychczas bajtów i całkowitą liczbę bajtów, które mają zostać pobrane.

Dla wszystkich zdarzeń atrybut target wskazuje powiązany obiekt XMLHttpRequest.

[edytuj] Inne własności i metody

Oprócz własności i metod omówionych powyżej obiekty XMLHttpRequest obsługują również inne przydatne własności i metody.

[edytuj] responseXML

Jeżeli ładowany jest dokument XML, własność responseXML zawiera treść pobranego dokumentu w postaci obiektu XmlDocument, do którego można uzyskać za pomocą metod DOM. Jeżeli serwer wysyła poprawnie sformatowany dokument XML, ale nie jest okreśony nagłówek XML Content-Type, za pomocą metody overrideMimeType() można wymusić przetwarzanie dokumentu jako kodu XML. Jeżeli dokument XML wysyłany z serwera nie jest sformatowany poprawnie, własność responseXML zwraca wartość null, niezależnie od wymuszonego typu danych.

[edytuj] overrideMimeType()

Za pomocą tej metody można wymusić sposób obsługi dokumentu, wskazując określony typ danych. Metoda ta przydaje się w sytuacji, gdy do przetwarzania otrzymanych danych ma być użyta własność responseXML, serwer wysyła dane w formacie XML, ale nie jest wysyłany poprawny nagłówek Content-Type.

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.overrideMimeType('text/xml');
req.send(null);

[edytuj] setRequestHeader()

Za pomocą tej metody można ustawić dowolny nagłówek HTTP żądania przed wysłaniem go.

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.setRequestHeader("X-Foo", "Bar");
req.send(null);

[edytuj] getResponseHeader()

Za pomocą tej metody można pobrać nagłówek HTTP ustawiony w odpowiedzi przesłanej przez serwer.

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.send(null);
dump("Content-Type: " + req.getResponseHeader("Content-Type") + "\n");

[edytuj] Zastosowanie w komponentach XPCOM

W komponentach JavaScript XPCOM niemożliwe jest utworzenie obiektów XMLHttpRequest za pomocą konstruktora XMLHttpRequest() — nie jest on zdefiniowany wewnątrz komponentów i jego wywołanie powoduje wystąpienie błędu. W celu utworzenia i użycia obiektu należy skorzystać z innej składni.

Zamiast kodu:

var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.onload = onLoad;
req.onerror = onError;
req.open("GET", url, true);
req.send(null);

należy użyć:

var request = Components.
              classes["@mozilla.org/xmlextras/xmlhttprequest;1"].
              createInstance();

// Za pomocą metody QueryInterface należy przesłać obiekt  
// do interfejsu nsIDOMEventTarget, aby ustawić procedury obsługi zdarzeń:

request.QueryInterface(Components.interfaces.nsIDOMEventTarget);
request.addEventListener("progress", function(evt) { ... }, false);
request.addEventListener("load", function(evt) { ... }, false);
request.addEventListener("error", function(evt) { ... }, false);

// Za pomocą metody QueryInterface należy przesłać obiekt  
// do interfejsu nsIXMLHttpRequest, aby otworzyć i wysłać żądanie:

request.QueryInterface(Components.interfaces.nsIXMLHttpRequest);
request.open("GET", "http://www.example.com/", true);
request.send(null);

[edytuj] Ograniczona liczba jednoczesnych połączeń nawiązywanych przez obiekty XMLHttpRequest

Maksymalna liczba połączeń, określona w preferencji network.http.max-persistent-connections-per-server (dostępnej w oknie about:config), jest domyślnie ograniczona do 2. Niektóre interaktywne strony internetowe, na których używane są obiekty XMLHttpRequest, mogą podtrzymywać otwarte połączenie. Otwarcie dwóch lub trzech takich stron w osobnych kartach lub oknach może spowodować awarię przeglądarki, w wyniku której zawartość okien nie będzie odświeżana, a sama aplikacja przestanie odpowiadać.

[edytuj] Żądania wysyłane do zewnętrznych witryn

Nowość w Firefoksie 3 Dostępne są zdefiniowane w roboczej wersji specyfikacji W3C Access Control żądania XMLHttpRequest przesyłane między witrynami. Z funkcjonalności tej można skorzystać na dwa sposoby. Pierwszy polega na dodaniu nowego nagłówka new Access-Control (dostępnego dla wszystkich typów danych, lecz wymagającego większego poziomu kontroli nad używanym serwerem WWW). Drugi sposób to instrukcje przetwarzania dotyczące kontroli dostępu (możliwe do zastosowania jedynie w dokumentach XML). Więcej informacji można znaleźć w tym artykule.

[edytuj] Odnośniki

1. AJAX: wprowadzenie
2. Obiekt XMLHttpRequest - architektura REST i zaawansowane interfejsy użytkownika (artykuł w j. ang.)
3. Dokumentacja XULPlanet (artykuł w j. ang.)
4. Dokumentacja firmy Microsoft (artykuł w j. ang.)
5. Materiały dla programistów Apple (artykuł w j. ang.)
6. Korzystanie z obiektu XMLHttpRequest (jibbering.com) (artykuł w j. ang.)
7. Obiekt XMLHttpRequest: robocza wersja specyfikacji W3C (artykuł w j. ang.)