2.2 Eigenschaften und Methoden des XMLHTTPRequest-Objekts

Einige Eigenschaften und Methoden des XML-HTTP-Objekts haben wir im Zusammenhang mit unserem Ajax-Kernel bereits kennen gelernt. Hier nun eine systematische Beschreibung aller Eigenschaften und Methoden dieses Objekts.

Eigenschaft: onreadystatechange

Genaugenommen ist dies ein Event-Handler, dem beliebiger JavaScript-Code zugeordnet werden kann, beispielsweise ein Funktionsaufruf: onreadystatechange = tuWas().

Das Ereignis onreadystatechange wird immer dann ausgelöst, wenn sich der Verbindungsstatus einer zuvor abgesetzten HTTP-Anfrage ändert. Bei jedem Auslösen des Ereignisses nimmt die Objekteigenschaft readyState einen anderen Wert an.

Eigenschaft: readyState

Diese Eigenschaft speichert den aktuellen Verbindungsstatus einer zuvor abgesetzten HTTP-Anfrage, und zwar in Form einer Zahl. Folgende Werte sind möglich:

(oder Konstante: UNINITIALIZED): Diesen Wert hat die Eigenschaft, bevor die Methode open() aufgerufen wurde, die eine HTTP-Anfrage einleitet.
1 (oder Konstante: LOADING): Dieser Wert bedeutet, dass die HTTP-Verbindung zum Webserver erfolgreich zustande kam. Diesen Wert hat die Eigenschaft, wenn open() eine Verbindung mit dem Webserver aufnehmen konnte, aber noch keine konkrete Anfrage mit send() gestartet wurde.
2 (oder Konstante: LOADED): Dieser Wert bedeutet, dass der HTTP-Request vollständig übertragen wurde, und dass die Antwort-Header-Zeilen vom Webserver bereits vorliegen. Wenn readyState diesen Wert hat, können bereits die Methoden getAllResponseHeaders() und getResonseHeader() angewendet werden, um die Server-Antwort schon vor der Übertragung der Nutzdaten auszuwerten.
3 (oder Konstante: INTERACTIVE): Diesen Wert hat die Eigenschaft, während die eigentlichen Nutzdaten vom Webserver empfangen werden. Die Eigenschaften responseText bzw. responseXML werden während dieses Zustands nach und nach mit den empfangenen Daten gefüllt.
4 (oder Konstante: COMPLETED): Dies ist der Endzustand und bedeutet, dass die Server-Antwort inklusive aller Header- und Nutzdaten übertragen wurde.

Leider ist die Implementierung der Zustände von readyState in den verschiedenen Browsern nicht zuverlässig und einheitlich implementiert. So wertet beispielsweise der Opera-Browser nur die Zustände 3 und 4 aus. In der Praxis warten die meisten Ajax-Anwendungen deshalb bis readyState == 4 und beginnen dann mit der Verarbeitung der erhaltenen Antwortdaten.

Eigenschaft: responseText

Diese Eigenschaft enthält die vom Server gesendeten Nutzdaten als String. Was die Daten enthalten, hängt davon ab, was angefragt bzw. gesendet wurde. Bei Textdaten ist auch nichts weiter zur Zeichenkodierung festgelegt –- all das sind Dinge, die das aufrufende JavaScript im Zusammenhang mit einem Aufruf vorher wissen muss.

Wenn es sich um Text oder HTML-formatierten Text handelt, werden empfangene Daten in der Regel über innerHTML in die aktuell angezeigte Webseite eingebaut.

Eigenschaft: responseXML

Diese Eigenschaft enthält nur dann einen konkreten Wert, wenn die Serverantwort explizit aus XML-Daten besteht. Gedacht ist diese Eigenschaft als Schnittstelle für das Document Object Model (DOM). Mit Hilfe der DOM-Schnittstelle von JavaScript lassen sich so empfangene Daten gezielt in die Dokumentstruktur der aktuell angezeigten Webseite einbauen. Die Nutzdaten liegen in der Form eines DOM-Objekts vor.

Eigenschaft: status

Diese Eigenschaft speichert den HTTP-Statuscode einer Server-Antwort, sobald diese vorliegt. Nachfolgende Tabelle listet die wichtigsten HTTP-Statuscodes auf:

HTTP-Statuscode Erklärung
200 Der Server kann die angeforderten Daten wie gewünscht versenden. Dies ist der Normalfall, wenn keine Probleme auftauchen.
204 Der Server hat die Anfrage erhalten, sendet jedoch keine Daten zurück. Gut verwendbar ist dieser Status-Code bei Verwendung in serverseitigen Scripts, die zwar etwas auf dem Server erledigen, aber keinen neuen HTML-Code senden wollen.
301 Die angeforderten Daten befinden sich nicht mehr unter dem URI, sie wurden dauerhaft auf eine andere Adresse verschoben. In der Statusmeldung (Eigenschaft statusText) wird angegeben, unter welchem URI sich die Daten jetzt befinden.
302 Die angeforderten Daten wurden vorübergehend zu einem anderen URI verschoben. In der Statusmeldung (Eigenschaft statusText) wird angegeben, unter welcher Adresse sich die Daten derzeit befinden.
304 Die angeforderten Daten haben sich gegenüber einer früheren Anfrage nicht geändert und werden deshalb nicht erneut gesendet.
400 Die Anfrage enthält Syntaxfehler. Der Server kann die Anfrage deshalb nicht bearbeiten.
401 Die angeforderten Daten sind zugangsgeschützt. Der Server kann die Daten nur senden, wenn eine gültige Zugangskennung, bestehend aus Benutzername und Passwort, bei der Anfrage mit gesendet wird.
403 Der Server möchte die angeforderten Daten nicht herausgeben. Das passiert zum Beispiel, wenn der Zugriff auf die Ressource von dem IP-Adress-Bereich, aus dem die Anfrage kommt, in der Serverkonfiguration verboten wurde, die Ressource ganz und gar gesperrt wurde oder man versucht, ein Verzeichnislisting zu bekommen, dies jedoch in der Serverkonfiguration abgeschaltet wurde.
404 Der angeforderte URI existiert nicht.
500 Der Server kann die angeforderten Daten nicht senden, weil auf dem Server ein Fehler aufgetreten ist. Beispielsweise konnte das aufgerufene Script auf dem Server nicht gestartet oder korrekt ausgeführt werden.

Eigenschaft: statusText

Diese Eigenschaft ist nur im Zusammenhang mit der Eigenschaft status zu betrachten. Sie enthält die vom Webserver mitgelieferte Textmeldung zu einem Statuscode. In einigen Fällen (z.B. bei den Statuscodes 301 und 302) enthält die Meldung wichtige zusätzliche Angaben.

Methode: abort()

Mit dieser Methode wird eine laufende Kommunikation mit dem Webserver abgebrochen. Der Event-Handler onreadystatechange wird auf 0 zurückgesetzt. Das XML-HTTP-Objekt kann für eine neue Webserver-Anfrage genutzt werden. Sinnvoll ist der Einsatz dieser Methode beispielsweise, wenn der Anwender die Möglichkeit hat, eine Aktion, für die Ajax zum Einsatz kommt, mit Hilfe einer „Abbrechen“-Schaltfläche zu stoppen. Die Abbrechen-Schaltfläche kann in einem solchen Fall die abort()-Funktion starten.

Methode: getAllResponseHeaders()

Diese Methode ist aufrufbar, sobald der Server zumindest seinen Antwort-Header gesendet hat (die Eigenschaft readyState muss mindestens den Wert 2 haben). Sie liefert die gesamten Header-Felder der Server-Antwort als eine Zeichenkette zurück. Um bestimmte Header-Felder abzufragen, ist die Methode getResponseHeader() besser geeignet. Beispiel (ajax ist der Name einer Instanz des XML-HTTP-Objekts):

ajax.getAllResponseHeaders();

erzeugt eine Rückgabe, die so ähnlich aussieht wie:

Date: Tue, 10 Jun 2008 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8

Methode: getResponseHeader(name)

Diese Methode ist ebenso wie getAllResponseHeaders() aufrufbar, sobald der Server zumindest seinen Antwort-Header gesendet hat (die Eigenschaft readyState muss mindestens den Wert 2 haben). Im Parameter name muss die Bezeichnung eines HTTP-Header-Feldes übergeben werden. Die Methode liefert dann den zugehörigen Wert als Zeichenkette zurück, sofern das Feld im HTTP-Antwort-Header überhaupt vorkommt. Beispiel:

httpRequest.getResponseHeader("Content-Type");

erzeugt eine Rückgabe, die so ähnlich aussieht wie:

Content-Type: text/plain; charset=utf-8

Methode: open(method, url[, asyncFlag[, userName[, password]]])

Die open()-Methode öffnet eine HTTP-Verbindung zu einem Webserver. Dabei müssen mindestens die beiden Parameter method und url übergeben werden.

Der Parameter method bestimmt die Übertragungsmethode. Üblich sind die Angaben "GET" und "POST" (gemäß den HTTP-Regeln ist es besser, die Bezeichnung der Übertragungsmethode in Großbuchstaben zu notieren). Weitere mögliche HTTP-Methoden sind "PUT" und "HEAD", die jedoch in der Praxis seltener verwendet werden. Die Standardmethode ist "GET". Die Methode "POST" wird dann verwendet, wenn das Script Nutzdaten an den Server senden will. Typischer Anwendungsfall sind Formulardaten, die bereits während der Eingabe und vor dem Absenden des Formulars auf dem Server zwischengespeichert, überprüft oder anderweitig verarbeitet werden sollen.

Der Parameter url ist keine vollständige HTTP-Adresse, sondern nur eine Pfadangabe. Denn wie bereits erwähnt, kann ein Ajax-Script nur Adressen auf demjenigen Webserver aufrufen, von dem aus es selbst an den Browser übertragen wurde. In aller Regel handelt es sich bei der Adresse, die mit url übergeben wird, um ein für den Webserver ausführbares Script, also z.B. um ein PHP-Script oder um ein CGI-Script in Perl.

Wenn Sie für den Parameter asyncFlag explizit einen Wert übergeben wollen, müssen Sie true oder false übergeben. Mit true erzwingen Sie einen asynchronen Scriptablauf, und mit false einen synchronen Scriptablauf.

Ein asynchroner Scriptablauf bedeutet, dass JavaScript nicht wartet, bis die Antwort des Webservers vollständig übertragen wurde, sondern dass der Rest des JavaScripts sofort abgearbeitet wird. Bei einem synchronen Scriptablauf verhindert der Aufruf der Methode send() den weiteren Ablauf des JavaScripts so lange, bis die Serverantwort vollständig eingetroffen ist.

Der Default-Wert ist true, also ein asynchroner Scriptablauf. Der Vorteil davon ist, dass JavaScript seine Aufgaben erledigen kann und weitere Anwenderaktionen beispielsweise nicht blockiert sind. Dabei entsteht jedoch das Problem, dass die Daten des Webservers erst eintreffen, wenn das JavaScript bereits fertig durchgelaufen oder zumindest im Ablauf schon weiter ist. Aus diesem Grund wird bei asynchonem Scriptablauf eine sogenannte Callback-Funktion definiert, die dann aufgerufen wird, wenn die Serverantwort vorliegt. Der Event-Handler dafür ist onreadystatechange.

Die Parameter username und password sind nur dann von Bedeutung, wenn der Webserver für die über Ajax aufgerufene URL eine Identifizierung verlangt. Es ist jedoch nicht empfehlenswert, solche Inhalte über Ajax aufzurufen, da dann Benutzername und Passwort im JavaScript-Quelltext stehen, der für Web-Benutzer leicht einsehbar ist.

Methode: send([content])

Diese Methode sendet eine HTTP-Anfrage an den Webserver. Zuvor muss die Verbindung zum Webserver mit der Methode open() erfolgreich hergestellt worden sein. Wenn Sie als Anfragemethode get verwenden, übergeben Sie send() keinen Parameter. Wenn Sie dagegen post verwenden, müssen Sie send() eine Zeichenkette übergeben, welche die zu postenden Daten enthält. Diese Daten müssen in der Form www-form-urlencoded vorliegen, also so kodiert sein wie ein GET-Parameterstring (Felder durch & trennen, Feldname und Feldwert durch = trennen, www-form-url-eigene Zeichen hexadezimal kodieren –- für letzteres stellt JavaScript die Funktionen encodeURI() und encodeURIComponent() zur Verfügung).

Methode: setRequestHeader(name, value)

Mit dieser Methode können Sie der HTTP-Anfrage gewünschte HTTP-Header übergeben. So können Sie beispielsweise gewünschte Zeichensätze angeben –- im Prinzip kann name alles sein, was in HTML an <meta http-equiv=… zugewiesen werden kann, und value alles, was im gleichen HTML-Tag content= zugewiesen werden kann.

Sofern nicht anders angegeben, steht der Inhalt dieser Seite unter Lizenz Creative Commons Attribution-ShareAlike 3.0 License