Die SOAP-Nachricht

Übersicht:

• Aufbau
• Beispiel
• Der SOAP-Envelope
• Das encodingStyle-Attribut
• Der SOAP-Header
• Das actor-Attribut
• Das mustUnderstand-Attribut
• Der SOAP-Body
• Das Fault-Element
• Vordefinierte SOAP-Fehlercodes

Jede SOAP-Nachricht ist ein XML-Document, das aus drei Teilen besteht: dem SOAP- Envelope, dem SOAP-Header und dem SOAP-Body. Während der SOAP-Header optional ist, müssen die beiden Elemente Envelope und Body in jeder SOAP-Nachricht vorhanden sein. Das eigentliche XML-Dokument ist nun wie folgt aufgebaut:

• Der Envelope ist das oberste Element des XML-Dokuments und umschließt die gesamte Nachricht wie ein Umschlag.
• Der Header ist ein generischer Mechanismus, um eine SOAP-Nachricht um Funktionalität zu erweitern, die vorher von den kommunizierenden Anwendungen nicht abgestimmt worden ist. Dazu werden ein paar Attribute definiert, die angeben, wer diese Aufgaben umsetzen soll und ob das Ganze nun optional ist oder nicht.
• Der Body enthält die Informationen für den eigentlichen Empfänger der Nachricht. Hier ist ein Element vordefiniert, das Fault-Element zum Melden von eventuell aufgetretenen Fehlern.

[ Nach oben ]

POST /Aktien HTTP/1.1
Host: www.aktien.de
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "MeineURI"

<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Body>
			<M:HoleLetztenKurs xmlns:M="MeineURI">
				<Aktie>SUN</Aktie>
			</M:HoleLetztenKurs>
		</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Body>
			<M:LetzterKurs xmlns:M="MeineURI">
				<Kurs>107.0</Kurs>
			</M:LetzterKurs>
		</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

[ Nach oben ]

• Der Name des Elements lautet "Envelope"
• Das Element muß in jeder SOAP-Nachricht enthalten sein.
• Das Element darf Deklarationen von Namensräumen enthalten.
• Das Element darf zusätzliche Attribute enthalten, welche jedoch durch einen Namensraum qualifiziert werden müssen.
• Das Element darf weitere Unterelemente enthalten, die auch durch einen Namensraum qualifiziert werden müssen. Sofern es sich bei ihnen nicht um Header-Elemente handelt, dürfen sie im XML-Dokument auch erst nach dem SOAP Body-Element stehen.

[ Nach oben ]

Das Attribut encodingStyle="..." kann benutzt werden, um auf die Ordnungsregeln, die sog. Serialization zu verweisen, die in der SOAP-Nachricht benutzt werden sollen. Dieses Attribut darf in Zusammenhang mit jedem Element benutzt werden, und hat einen eingeschränkten Sichtbarkeitsbereich, der sich auf das Element und alle Kindelemente, die selbst kein encodingStyle-Attribut besitzen, beschränkt. Es gibt keinen vordefinierten Defaultwert für dieses Attribut.

Der Wert des Attributs ist eine geordnete Liste von URIs, die den jeweiligen Satz von Serialization-Regeln identifizieren, der benutzt werden soll. Die einzelnen URIs sind durch Leerzeichen getrennt. Die Ordnung erfolgt dabei von dem speziellsten Regelsatz zum allgemeinsten. Zum Beispiel:

SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

SOAP-ENV:encodingStyle="http://www.aktien.de/encoding/ http://schemas.xmlsoap.org/soap/encoding/"

SOAP-ENV:encodingStyle=""

Die von SOAP vordefinierten Serialization-Regeln werden durch das erste Beispiel identifiziert. Der im letzten Beispiel gezeigte URI der Länge Null weist explizit darauf hin, dass hinsichtlich des encodingStyles der enthaltenen Elemente keine Angaben gemacht werden.

[ Nach oben ]

SOAP stellt einen flexiblen Mechanismus zum Erweitern einer Nachricht zur Verfügung. Bemerkenswert ist dabei, dass diese Erweiterungen dezentralisiert und modular und ohne vorherige Kenntnisnahme durch den Kommunikationspartner geschehen kann. Typische Anwendungsbeispiele sind unter anderem Authentifizierung und Transaktionsmanagement.

Das Header-Element ist das erste direkte Kindelement des SOAP-Envelope-Elements. Alle direkten Kindelemente des SOAP-Header-Elements werden im folgenden als Header- Entries bezeichnet werden. Die Syntax-Regeln für den SOAP-Header lauten:

• Jeder Header-Entry wird durch sein Namen identifiziert, der aus dem Namespace-URI und dem lokalen Namen besteht.
• Das encodingStyle-Attribut darf benutzt werden, um die Ordnungsregeln der Header- Entries festzulegen.
• Die Attribute mustUnderstand und actor können benutzt werden, um zu beschreiben, wie ein Header-Entry verarbeitet werden soll und von wem.

[ Nach oben ]

Eine SOAP-Nachricht kann eventuell auf dem Weg vom Sender zu dem endgültigen Empfänger noch mehrere Zwischenstationen passieren. Eine Zwischenstation ist hier eine SOAP-Anwendung, die sowohl Nachrichten empfangen und verarbeiten als auch weiterleiten kann. Beide, die Zwischenstation und der endgültige Empfänger, werden durch URIs eindeutig identifiziert.

Es kann durchaus vorkommen, das nicht alle Teile der SOAP-Nachricht für den endgültigen Empfänger bestimmt sind, sondern nur für einen oder mehrere Zwischenstationen auf dem Weg, den die Nachricht zurücklegt. Daher muss eine Zwischenstation die Teile der Nachricht, die nur für sie bestimmt sind, aus der Nachricht entfernen, bevor sie sie weiterleitet.

Um den Empfänger eines Teils der Nachricht zu identifizieren, wird das globale SOAP- actor-Attribut eingesetzt. Der aktuelle Wert des actor-Attributs ist dabei ein URI, die den Empfänger identifiziert. Der spezielle URI "http://schemas.xmlsoap.org/soap/actor/next" weist darauf hin, das dieser Teil der Nachricht für die nächste Anwendung bestimmt ist, die die Nachricht verarbeiten wird. Wird zu einem Element des SOAP-Headers kein actor-Attribut angegeben, impliziert dies, das nur der endgültige Empfänger dieser Nachricht das Element verarbeiten soll.

[ Nach oben ]

Mit dem mustUnderstand-Attribut wird festgelegt, ob der jeweilige Empfänger, der durch das actor-Attribut festgelegt wird, diesen Header-Entry verarbeiten muss oder die Verarbeitung optional ist. Der aktuelle Wert des mustUnderstand-Attributs kann dabei 1 oder 0 sein, wobei 0 der Default-Wert ist, der auch bei Abwesenheit des mustUnderstand- Attributs angenommen wird.

Ein mustUnderstand-Attribut mit dem aktuellen Wert 1 bedeutet für den Empfänger des so ausgezeichneten Elements, dass er entweder den Semantiken des Elements Folge zu leisten hat und das Element damit korrekt verarbeiten muss, oder andernfalls im Verarbeiten der Nachricht versagt und einen Fehler zurückgeben muss.

Der Zweck dieses Attribut ist ein vorhersagefähiges Verhalten beim Verarbeiten von Elementen durch eine SOAP-Anwendung zu erzwingen. Es soll sichergestellt werden, dass eine Anwendung nur Elemente verarbeitet, die sie kennt, und andererseits essentiell wichtige Elemente, die für sie bestimmt, aber ihr unbekannt sind, nicht einfach ignoriert. Ein wichtiges Einsatzgebiet für das mustUnderstand-Attribut öffnet sich dort, wo mehrere Header-Entries in Beziehung miteinander stehen, und nicht ein Element ohne das andere ausgewertet werden darf.

[ Nach oben ]

Das Body-Element einer SOAP-Nachricht stellt einen einfachen Mechanismus zum Austausch der eigentlich der Nachricht zugrundeliegenden Informationen zur Verfügung. Das Body-Element entspricht einem Header-Element mit einem aktuellen mustUnderstand-Wert von 1 und dem endgültigen Empfänger der Nachricht als actor. Typische Einsatzbereiche sind etwa Remote Procedure Calls und Fehlerdiagnose.

Das Body-Element ist ein direktes Kindelement des SOAP-Envelope-Elements, und steht damit entweder direkt nach dem Header-Element (wenn eins vorhanden ist), oder ist das erste Kindelement des Envelope-Elements.

Alle direkten Kindelemente des Body-Elements werden als Body-Entries bezeichnet, wobei jeder Body-Entry ein unabhängiges Element im SOAP-Body darstellt. Die Syntaxregeln sind wie folgt:

• Ein Body-Entry wird durch seinen Elementnamen, der aus dem Namespace und dem lokalen Namen besteht, eindeutig identifiziert.
• Das encodingStyle-Attribut darf benutzt werden, um die Serialization-Regeln, nach denen dieses Element kodiert wurde, festzulegen.

Im SOAP ist ein Body-Element vordefiniert, das Fault-Element, welches zur Fehlerdiagnose dienen kann.

[ Nach oben ]

Das Fault-Element wird benutzt, um Informationen über eventuell aufgetretene Fehler in einer SOAP-Nachricht zu übermitteln. Falls es in einer Nachricht vorhanden ist, muss das Fault-Element ein Body-Entry sein und darf nur höchstens einmal in der gesamten Nachricht vorkommen.

• faultcode: Vorgesehen, um einen eindeutigen Identifier für den aufgetretenen Fehler aufzunehmen. Das faultcode-Element muss in jedem Fault-Element vorhanden sein. SOAP bietet einige vordefinierte Werte, die das faultcode-Element annehmen kann.
• faultstring: Vorgesehen, um eine durch Menschen lesbare Fehlermeldung zu liefern. Auch dieses Element muss in jedem Fault-Element vorkommen, und sollte zumindest etwas Informationen zum Verstehen des Fehlers enthalten.
• faultactor: Vorgesehen, um die Fehlerquelle auf dem Weg der Nachricht zurückverfolgen zu können. Dabei wird ähnlich dem actor-Attribut im Header vorgegangen, aber anstatt den Empfänger der Nachricht identifizieren, wird die Quelle des Fehlers durch einen URI lokalisiert. SOAP-Anwendungen, die nicht der eigentliche Empfänger der Nachricht sind, müssen beim Produzieren eines Fehlers das faultactor- Element in die Fehlermeldung einfügen.
• detail: Vorgesehen, um Detailinformationen über den Fehler zu übermitteln für den Fall (und nur diesen!), dass das Body-Element der SOAP-Nachricht nicht ordnungsgemäß verarbeitet werden konnte. Das detail-Element darf nicht benutzt werden, wenn beim Verarbeiten eines Header-Entries ein Fehler aufgetreten ist. Daher kann sein Vorhandensein allein schon als sicheres Zeichen genommen werden, dass der endgültige Empfänger der Nachricht das Body-Element nicht ordnungsgemäß verarbeiten konnte. Das detail-Element darf mehrere Kindelemente enthalten, die Detail-Entries genannt werden. Jeder Detail-Entry ist ein unabhängiges Element innerhalb des detail-Elements.

[ Nach oben ]

• VersionMismatch: Der die Nachricht verarbeitende Prozeß ist auf einen ungültigen Namensraum gestoßen.
• MustUnderstand: Ein Header-Entry konnte durch den Prozeß, der ihn verarbeiten sollte, nicht identifiziert werden, obwohl er einen mustUnderstand-Attributwert von 1 besaß.
• Client: Das Benutzen der Client-Fehlerklasse weist darauf hin, dass die Nachricht den Empfänger in einem ungültigen Format erreicht hat oder nicht die zum Verarbeiten notwendigen Informationen enthielt.
• Server: Das Benutzen der Server-Fehlerklasse weist darauf hin, dass die Nachricht aus Gründen, die nichts mit dem eigentlichen Inhalt der Nachricht selbst zu tun haben, nicht verarbeitet werden konnte.

[ Nach oben ]