SOA Guidelines. Service Contract Design mit der Web Service Description Language (WSDL) Guido Schmutz Technology Manager

Transkript

1 SOA Guidelines Service Contract Design mit der Web Service Description Language (WSDL) Guido Schmutz Technology Manager Version 1.0 Seite 1/41

2 Dokument Information Status * Projektname Autor Initiale Bearbeitende Prüfende Abgeschlossen SOA Guidelines Guido Schmutz gus Guido Schmutz Matthias Furrer, Michel Hautle, Markus Zehnder Genehmigende Verteiler * In Arbeit, In Prüfung, Abgeschlossen Änderungskontrolle, Prüfung, Genehmigung Version Datum Beschreibung, Bemerkung Name oder Rolle Draft Version Guido Schmutz Erster Review Guido Schmutz Korrekturen & Erweiterungen Guido Schmutz Finale Version Guido Schmutz Erweiterungen & Korrekturen Guido Schmutz Review-Feedback eingearbeitet Guido Schmutz Version 2.0 Seite 2/41

3 Inhaltsverzeichnis 2 Einführung 6 3 Generelle Konventionen in diesem Dokument Formatierungsarten für zusammengesetzte Wörter bzw. Sätze Entscheidungen, die dieses WSDL Richtlinien Dokument beeinflusst haben WSDL SOAP Messaging Style SOAP Encoding Der Service-Kontrakt Der Entwurf des Service-Kontrakt Web Service Description Language (WSDL) Struktur eines WSDL Dokuments Der abstrakte Teil Der konkrete Teil WSDL Elemente Entwurf des WSDL-Kontraktes Aufteilung in verschiedene Dokumenttypen Namespace Verwendung von Namespaces Definition Sektion Das <definitions> Element Das <documentation> Element Das <import> Element Typen Definitionen Das <types> Element Nachrichten Definitionen Das <message> Element Das <part> Element PortType Definitionen Das <porttype> Element Das <operation> Element Binding Definition Das <binding> Element Service und Port Definition Das <service> und <port> Element Version 2.0 Seite 3/41

4 7.9 Versionierung im WSDL Komplette Definition eines Service ServiceException-v1.0.xsd ServiceContext-v1.0.xsd CreditCard-v1.0.xsd CommonFaults-v1.0.wsdl CreditCardValidation-v1.0.wsdl Referenzen 41 Version 2.0 Seite 4/41

5 Abbildungsverzeichnis Abbildung 1: Die wichtigsten Dokumente, die den technischen Service-Kontrakt definieren und weitere Dokumente für die Beschreibung der SLA Abbildung 2: Der Web Service Contract definiert, WAS der Service anbietet und WIE und WO er aufgerufen werden kann Abbildung 3: Sicht der wichtigsten Elemente des abstrakten Teils des WSDL Abbildung 4: Die wichtigsten Bestandteile des Binding-Elements im konkreten Teils des WSDL Abbildung 5: Die wichtigsten Bestandteile des Service-Elements im konkreten Teils des WSDL Abbildung 6: Das <definitions> Element kapselt den gesamten Service-Kontrakt Abbildung 7: Das <import> Element erlaubt das Importieren von anderen WSDL Dokumenten Abbildung 8: Das <types> Element erlaubt das Definieren bzw. Importieren von XML-Schema Datentypen Abbildung 9: Das <message> Element definiert eine abstrakte Nachricht Abbildung 10: Die Definition der Wrapper-Elemente innerhalb der Types-Sektion des WSDL Abbildung 11: Importieren der Wrapper-Elemente aus einem externen XML Schema Abbildung 12: Die Definition der Wrapper-Elemente im externen XML Schema Abbildung 13: Das <part> Element definiert die Nachricht über das Wrapper-Element Abbildung 14: Das <porttype> Element im WSDL Abbildung 15: Das <operation> Element innerhalb von einem <porttype> im WSDL Abbildung 16: Das <binding> Element im WSDL Abbildung 17: Das <service> Element mit geschachteltem <port> Element für die Definition des Endpoints Version 2.0 Seite 5/41

6 2 Einführung Für die Implementierung einer service-orientierten Lösung ist die Struktur der Service- Schnittstelle sehr wichtig. Eine schlecht entworfene Service-Schnittstelle kann die Entwicklung von Service Konsumenten, die diese Schnittstelle verwenden, wesentlich erschweren und komplexer als notwendig machen. Web Service Description Language (WSDL) ist die Definitions-Sprache mit der Web Service Schnittstellen definiert und beschrieben werden. Diese Schnittstelle ist Bestandteil des Service-Kontraktes und sollte möglichst einfach zu lesen und zu verstehen sein. Das Ziel dieses Richtlinien-Dokumentes ist es, die notwendigen Informationen zur Verfügung zu stellen, damit Web Service Schnittstellen in konsistenter Art und Weise erstellt werden können. Wie bei einem Style Guide üblich gibt es jeweils Bereiche, wo mehrere Möglichkeiten offen stehen würden und jede der Optionen bestimmte Vorzüge aufweist. Dieser Leitfaden behandelt in einer Einführung zuerst die gebräuchlichsten Bestandteile eines WSDL und zeigt Best Practices, immer mit dem Hauptaugenmerk auf Lesbarkeit und Verwendbarkeit der WSDL-Dokumente. Der WSDL-Standard ist nicht abhängig von einem bestimmten Protokoll, obwohl die meisten heutigen Implementierungen von Web Services auf SOAP über HTTP Bindings basieren. Dieser Style Guide konzentriert sich zurzeit auf SOAP über HTTP. Version 2.0 Seite 6/41

7 3 Generelle Konventionen in diesem Dokument Sämtliche Richtlinien werden in einer übersichtlichen, tabellarischen Form beschrieben, die nachfolgend beispielhaft gezeigt ist: <Identifikations-Code> <Beschreibung der Regel> < Regel-Gruppe> Identifikations-Code Jede Regel wird durch einen, innerhalb des Dokumentes eindeutigen Identifikationscode gekennzeichnet. Der Identifikationscode besteht aus einem dreistelligen Präfix und einer vierstelligen Regelnummer, die folgendes Format aufweist: <präfix>- <regel-nummer> Die folgenden Präfixe werden zurzeit verwendet: Präfix GEN NMR BEP IBP Beschreibung Generelle Entwurfsrichtlinie Namenskonvention (File, Tag, Namespace, usw.) Best Practice Regel aus Basic Profile 1.2 [BP-GUIDE-12] der Web Services Interoperability Organization (WS-I). Der Präfix BP ohne Regelnummer wird dabei verwendet, wenn die entsprechende Regel aus dem Text des Basic Profile extrahiert wurde, ohne dass es dazu bereits eine Basic Profile Regel mit Nummer gibt). Die Regelnummern werden übergreifend vergeben (ausser IBP) und sind nicht geordnet. Die nächste freie Regelnummer ist: 0048 Beschreibung der Regel Eine möglichst kurze und prägnante Beschreibung der Regel, mit der Verwendung der unterschiedlichen Regeltypen im Text. Regel Klasse Jede Regel wird nach den Konventionen, die im Request for Comment 2119 [RFC-2119] definiert wurden, klassifiziert. In der Tabelle 1 sind die 5 möglichen Klassen und ihre Bedeutung beschrieben. Tabelle 1: Die 5 Regel-Klassen und deren Semantik Version 2.0 Seite 7/41

8 Schlüsselwort Bedeutung NOT SHOULD SHOULD NOT MAY MUSS oder die Begriffe ERFORDERLICH oder DARF NUR, bedeuten, dass die Definition/Regel eine absolute Forderung innerhalb dieses Dokumentes darstellt, d.h. etwas, das in jedem Fall berücksichtigt werden muss. DARF NICHT oder der Begriff IST NICHT, bedeuten, dass die Definition/Regel ein absolutes Verbot innerhalb des Dokumentes darstellt, d.h. etwas, das auf keinen Fall verwendet werden darf. SOLLTE oder das Adjektiv empfohlen, bedeuten, dass es triftige Gründe geben kann, eine entsprechende Definition/Regel zu ignorieren. Die Auswirkungen müssen verstanden worden und sorgfältig abgewogen werden, bevor der alternative Weg beschritten wird. SOLLTE NICHT oder die Formulierung NICHT EMPFOHLEN bedeuten, dass es triftige Gründe geben kann, bei denen das von der Definition/Regel beschriebe Verhalten akzeptabel oder sogar nützlich sein kann. Die Auswirkungen müssen klar verstanden und sorgfältig abgewogen werden, bevor das entsprechende Verhalten umgesetzt wird. DARF oder das Adjektiv optional, bedeuten, dass eine Definition/Regel wirklich optional ist. Es ist Sache des Lesers, ob er die Definition/Regel anwendet oder nicht. 3.1 Formatierungsarten für zusammengesetzte Wörter bzw. Sätze Folgende Formatierungsarten werden in diesem Dokument verwendet: o o o UpperCamelCase (UCC) eine Art der Repräsentation von zusammengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter ohne Zwischenraum zusammengefügt werden. Der erste Buchstabe jedes einzelnen Wortes wird dabei jeweils in Grossbuchstaben geschrieben: CreditCardValidation LowerCamelCase (LCC) eine Art der Repräsentation von zusammengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter ohne Zwischenraum zusammengefügt werden. Mit Ausnahme des ersten Wortes wird dabei jeweils der erste Buchstabe jedes einzelnen Wortes in Grossbuchstaben geschrieben: creditcardvalidation LowerDashed (LD) eine Art der Repräsentation von zusammengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter durch einem Bindestrich getrennt zusammengefügt werden, wobei alles in Kleinbuchstaben geschrieben wird: creditcard-validation Version 2.0 Seite 8/41

9 4 Entscheidungen, die dieses WSDL Richtlinien Dokument beeinflusst haben Diese Service-Kontrakt-Design Richtlinien wurden unter gewissen Prämissen geschrieben. So wurde zu Beginn entschieden, welche Möglichkeiten des WSDL- und XML Schema Standards genutzt und welche Möglichkeiten ausgeschlossen werden sollen. Einige dieser Entscheide sind technisch bedingt, einige scheinen aus gesundem Menschenverstand so richtig und andere basieren auf einer Vielzahl unterschiedlicher WSDL Dokumente, die umgesetzt wurden. Nicht alle diese Entscheide sind in diesem Dokument einfach ersichtlich, so dass sie hier kurz erklärt werden. 4.1 WSDL 1.1 Dieser Style-Guide basiert auf der Version 1 von WSDL. Die Version 2 von WSDL ist zwar seit längerem publiziert, es fehlt jedoch immer noch an der Unterstützung durch die führenden Hersteller von SOA Plattformen. 4.2 SOAP Messaging Style WSDL 1.x definiert zwei verschiedene Message Styles: document wir normalerweise für den Austausch von Dokumenten gebraucht, die über ein XML Schema definiert sind. rpc wird normalerweise so gebraucht, dass eine Liste von Daten an eine Operation gereicht werden und ein einzelner Wert von der Operation zurückkommt. Aus Interoperabilitätsgründen wird heute das Verwenden von Document Style Web Services bevorzugt und deshalb geht dieser Style Guide nur auf die Definition von Web Services im Document Style ein. GEN-0001 In der WSDL Definition MUSS aus Interoperabilitätsgründen immer der Document/Literal Wrapped Style verwendet werden (siehe auch BEP-0028). 4.3 SOAP Encoding SOAP Encoding stellt einen Mechanismus zur Verfügung, um Daten in kompakter Form innerhalb einer service-orientierten Lösung zu transportieren. Jedoch kann diese Form nicht über ein XML Schema beschrieben werden. Aus Interoperabilitätssicht darf SOAP Encoding nicht verwendet werden. WS-I Basic Profile verbietet daher das Verwenden von SOAP Encoding für Nachrichten komplett, so dass wir in diesem Dokument nicht weiter auf das SOAP Encoding eingehen. 5 Der Service-Kontrakt Version 2.0 Seite 9/41

10 Der Service-Kontrakt ist essentiell für den Service-Entwurf, da er die Schnittstelle zwischen dem Nutzer und dem Anbieter eines Services beschreibt. Jeder einzelne Teil des Service-Kontraktes muss daher sorgfältig geplant und entworfen werden. Ein Service-Kontrakt kann aus den folgenden Dokumenten bestehen, die alle ihren Teil zur Schnittstellenbeschreibung vom Service beitragen: WSDL Definition(en) XML Schema(s) WS-Policy Definition Zusammen bilden diese Dokumente den sogenannten technischen Service-Kontrakt. Nicht alle Informationen, die für den Service-Kontrakt wichtig sind, lassen sich jedoch im technischen Service-Kontrakt beschreiben. Daher sind zusätzliche, nicht standardisierte Dokumente erforderlich, um z.b. Service Level Agreement (SLA) definieren zu können. Diese und die Dokumente des technischen Web Service-Kontraktes machen dabei den Service-Kontrakt aus, wie dies Abbildung 1 darstellt. Service Contract Technical Web Service contract WSDL XML schema WS Policy Service Level Agreement (SLA) Abbildung 1: Die wichtigsten Dokumente, die den technischen Service-Kontrakt definieren und weitere Dokumente für die Beschreibung der SLA. Der Begriff technischer Service-Kontrakt in Abbildung 1 bezieht sich auf Servicebeschreibungs-Dokumente, die sich maschinell interpretieren lassen. Die in diesem Dokument beschriebenen Richtlinien befassen sich ausschliesslich mit den WSDL-Dokumenten des technischen Service-Kontraktes. Ein weiteres Dokument definiert die entsprechenden Richtlinien für den Entwurf von XML- Schemas [XML-SCHEMA-GUIDE-10]. 5.1 Der Entwurf des Service-Kontrakt Für den Entwurf der Service-Schnittstellen haben sich zwei unterschiedliche Ansätze etabliert: Version 2.0 Seite 10/41

11 Contract-First dabei wird zuerst der Kontrakt in Form von WSDL- und XML- Schema-Dokumenten definiert, bevor mit der Service-Implementierung (Schreiben von Code) begonnen wird. Das Ziel ist dabei, den Kontrakt vollständig zu definieren und erst danach mit der Codierung zu beginnen. Der Code wird dabei an den Kontrakt adaptiert. Contract-Last dabei wird erst der Code entwickelt und die Service-Schnittstelle wird als letzes auf Basis des Codes generiert. Der Kontrakt ist damit direkt vom Code abhängig und eng an diesen gekoppelt. Wir empfehlen den Entwurf mittels des Contract-First Ansatz, da dieser eine viel bessere Entkoppelung von der Implementation erlaubt. Contract-First bedeutet zu Beginn zwar einen Mehraufwand, da der Service-Kontrakt manuell erstellt werden muss. Viele IDE s (Integrated Development Environments) bieten jedoch heute eine gute Unterstützung für das Erstellen der WSDL- und XML-Schema-Dokumente oder aber der Service-Kontrakt wird über einen Model Driven Software Development (MDSD) Ansatz aus einem Model heraus generiert. Dafür hat man die volle Kontrolle über die Schnittstelle und ist nicht vom unterliegenden Code abhängig, wie dies beim Contract-Last Ansatz der Fall ist. Gerade in einer Service- Orientierten Architektur, stellt dies einen nicht zu unterschätzenden Vorteil dar, da es schlussendlich die notwendige Flexibilität für die Weiterentwicklung bringt. Wenn ein WSDL von Hand erstellt wird, dann muss sichergestellt werden, dass das Dokument sowohl gültig als auch korrekt ist und es gewissen Richtlinien genügt. Dieses Dokument soll helfen, mittels dem Contract-First Ansatz, qualitativ hochwertige Service- Schnittstellen zu erstellen. BEP-0002 BEP-0003 Für das Erstellen von Service-Kontrakten für öffentliche Services MUSS der Contract-First Ansatz genutzt werden. Dur damit lassen sich die Regeln, die in diesem Dokument beschrieben sind auch effektiv umsetzen. Für das Erstellen von Service-Kontrakten von privaten Services DARF ein Contract-Last Ansatz gewählt werden. Ein privater Service ist dabei ein Service, der immer von einem öffentlichen Service zusätzlich gekapselt wird und ausser diesem, von keinem weiteren Service-Consumer direkt genutzt wird. D.h. ein privater Service erscheint nicht in einem Service- Inventory. Damit lassen wir zu, dass z.b. Adapter von SOA Plattformen nutzbar sind, die oft Serviceschnittstellen generieren. MAY Version 2.0 Seite 11/41

12 6 Web Service Description Language (WSDL) 6.1 Struktur eines WSDL Dokuments Ein WSDL Dokument ist ein XML Dokument, welches über das Root-Element <definition> definiert ist. Das XML Dokument beschreibt dabei den Service und wie ein Endpoint, welcher diesen Service implementiert, erreicht werden kann. Ein WSDL Dokument hat zwei verschiedene Teile, wie dies Abbildung 2 zeigt: abstrakter Teil - beschreibt den Service in einer implementations-neutralen Art. konkreter Teil - definiert, wie ein Endpoint, der den Service implementiert, den Konsumenten angeboten wird. Abbildung 2: Der Web Service Contract definiert, WAS der Service anbietet und WIE und WO er aufgerufen werden kann Der abstrakte Teil Der abstrakte Teil des WSDL Dokuments umfasst die <types>, die <message> und die <porttype> Elemente. Er beschreibt die Service-Schnittstelle und die Nachrichten, die über diese Service-Schnittstelle ausgetauscht werden. Innerhalb des types Elementes wird die XML-Schema Sprache genutzt, um die Datenstrukturen zu beschreiben, aus denen die Nachrichten gebildet werden. Ein Set von message Elementen wird verwendet, um die Struktur der Nachrichten zu definieren, welche der Service verwendet. Das porttype Element umfasst ein oder mehrere operation Elemente, die die einzelnen Operationen und ihre Nachrichten definieren, welche Version 2.0 Seite 12/41

13 vom Service angeboten werden. Der Aufbau des abstrakten Teils des WSDL ist in Abbildung 3 dargestellt. Abbildung 3: Sicht der wichtigsten Elemente des abstrakten Teils des WSDL Der konkrete Teil Der konkrete Teil des WSDL Dokuments enthält die <binding> und die <service> Elemente. Er beschreibt wie sich ein bestimmter Endpoint eines Service mit der Aussenwelt verbindet. Die <binding> Elemente beschreiben, wie die Dateneinheiten, die durch das <message> Element definiert werden auf konkrete, on-the-wire Datenformate, wie z.b. SOAP gemappt werden. Die wichtigsten Bestandteile des <binding> Elements sind in Abbildung 4 dargestellt. Version 2.0 Seite 13/41

14 Concrete Description Part I Port Type (Interface) Binding Operation Binding Operation Binding WHAT Input Message Binding Input Message Binding HOW Output Message Binding Output Message Binding Policies WHERE Fault Message Binding Abbildung 4: Die wichtigsten Bestandteile des Binding-Elements im konkreten Teils des WSDL Das <service> Element enthält ein oder mehrere <port> Elemente, die die Endpoints definieren, die den Service implementieren. Die wichtigsten Bestandteile des <service> Elementes sind in Abbildung 5 dargestellt. Abbildung 5: Die wichtigsten Bestandteile des Service-Elements im konkreten Teils des WSDL 6.2 WSDL Elemente Ein WSDL Dokument besteht aus den folgenden Bestandteilen: Version 2.0 Seite 14/41

15 <definitions> - das Wurzel-Element eines WSDL Dokumentes. Die Attribute dieses Elementes spezifizieren den Namen des WSDL Dokumentes, den Target- Namespace des Dokuments und eine Definition der Namespaces, die im WSDL Dokument referenziert werden. <types> - die XML Schema Datentypen, die für die Definition von Nachrichten verwendet werden. <message> - Die Beschreibung der Nachrichten, die beim Aufruf einer Serviceoperation ausgetauscht werden. Diese Elemente definieren die Argumente der Operationen eines einzelnen Service. <porttype> - eine Menge von <operation> Elementen, die die logische Schnittstelle des Service beschreibt. <operation> - die Beschreibung einer Aktion, die ein Service anbietet und durchgeführt. Die Operationen sind durch die Nachrichten definiert, die zwischen zwei Endpunkten ausgetauscht werden. <binding> - die Definition des konkreten Datenformates für einen Endpunkt. Ein <binding> Element definiert, wie die abstrakten Nachrichten auf die konkreten Datenformate, die von einem Endpunkt verwendet werden, gemappt werden. Hier werden Dinge wie Parameter-Reihenfolge, Rückgabe-Werte und das unterliegende Transport-Protokoll definiert. <service> - eine Menge von <port> Elementen. Diese Elemente sind Behälter für die Organisation der Endpoint-Definitionen. <port> - der Endpoint wird durch ein Binding und eine physikalische Adresse definiert. Diese Elemente bringen alle abstrakten Definitionen zusammen, kombinieren sie mit der Definition der Transportdetails und definieren die physikalischen Endpunkte an denen der Service angeboten wird. Version 2.0 Seite 15/41

16 7 Entwurf des WSDL-Kontraktes Der Entwurf eines Service-Kontraktes in Form eines WSDL bedarf folgender Schritte: 1. Definition der Datentypen, welche vom Service verwendet werden 2. Definition der Nachrichten, welche von den Services verwendet werden 3. Definition der Schnittstellen und damit der Operationen, die der Service zur Verfügung stellt 4. Definition des Bindings zwischen der Schnittstelle und der konkreten Daten- Repräsentation bei der Übertragung. 5. Definition des Service-Endpunkts 7.1 Aufteilung in verschiedene Dokumenttypen Diese Service Contract Design Regeln sehen vor, dass die Definition des Service-Kontrakts auf insgesamt 3 verschiedene Dokument-Typen aufgeteilt werden kann. Jedes dieser Dokumente hat eine bestimmte Rolle zu erfüllen und trägt zu dem Ziel bei, den Service-Kontrakt möglichst modular aufzubauen. Dokument Types Definition Shared Faults Service Beschreibung Das Type Definition Dokument enthält die Datentypen Definitionen innerhalb eines Schema-Namespaces. Es handelt sich dabei immer um ein XML Schema Dokument. Dieses Dokument ist optional, da nicht alle Services auch zwingend neue Datentypen definieren. Das Shared Faults Dokument enthält Fault Definitionen, die über mehrere Services hinweg gemeinsam genutzt werden sollen. Dieses Dokument ist optional, da nicht alle WSDL Definitionen Fault Definitionen gemeinsam nutzen werden. Das Service Dokument enthält die abstrakte und die konkrete Beschreibung des Services bzw. Service-Kontraktes. Optional lässt sich das Service Dokument weiter unterteilen in den abstrakten und konkreten Teil: Service Interface Dokument (abstrakt) enthält die Nachrichten und PortType Definitionen. Dieses Dokument kann für verschiedene Service-Binding Dokumente verwendet werden, ohne dass es geändert werden muss. Service Binding Dokument (konkret) enthält sowohl die Binding-Information wie auch die Service Definitionen, die zum Binding gehören. Dieses Dokument importiert ein Service Interface Dokument über ein <wsdl:import> Statement. Version 2.0 Seite 16/41

17 NMR-0004 Für die Filenamen der Dokumente MUSS folgendes Format verwendet werden: Types Definition Shared Faults Service Für Nachrichtendefinitions-Schema: <servicename>-v<major>.<minor>.xsd Für die Definition von Business Objekte: <bizobjectname>-v<major>.<minor>.xsd <name>faults-v<major>.<minor>.wsdl <servicename>-v<major>.<minor>.wsdl oder bei Separierung von Interface und Binding <servicename>-interface-v<major>.<minor>.wsdl <servicename>-binding-v<major>.<minor>.wsdl Wobei: bizobjectname Name des Business Objekts, das im XML-Schema definiert wird servicename - der Name des Services aus dem WSDL (name Attribut), ohne Versionssuffix und konvertiert in die UpperCamelCase Notation. major die Major Versionsnummer minor die Minor Versionsnummer CreditCard-v1.0.xsd CreditCardValidation-v1.0.xsd CreditCardValidation-v1.0.wsdl CreditCardValidation-interface-v1.0.wsdl NMR-0005 Der Buchstabe p KANN als Trennzeichen zwischen major und minor verwendet werden, so dass der. einzig für das Abtrennen der File-Extension gebraucht wird. soabp-common-types-v1p0.xsd credit-card-validation-service-v1p0.wsdl NMR-0006 Alle Namen, die im WSDL vergeben werden, MUESSEN sich an die UpperCamelCase Notation halten, ausser es wird anders definiert. NMR-0007 Alle Namen innerhalb des WSDL MUESSEN aus Kleinbuchstaben des Alphabets [a-z], Grossbuchstaben des Alphabets [A-Z], Zahlen [0-9] und dem Underscore Character [_] gebildet werden. GEN-0008 Shared Faults MUESSEN in einem eigenen Shared Faults Dokument definiert werden. GEN-0009 Ein WSDL Dokument DARF optional in zwei einzelne Dokumente unterteilt werden, so dass der abstrakte und der konkrete Teil unabhängig voneinander gepflegt werden können. KANN MAY Version 2.0 Seite 17/41

18 7.2 Namespace Namespaces werden benutzt, um das Vokabular eines XML-Dokumentes eindeutig identifizieren zu können und damit in einem einzelnen Dokument mehrere XML-Sprachen mischen zu können. Namespaces werden durch URIs dargestellt, meistens durch Webadressen (URLs). Dabei gilt es zu beachten, dass die entsprechende Adresse nicht existieren muss. Sie kann beliebig definiert werden. Wichtig ist dabei, dass bei den Angaben des Namespaces auf Gross- und Kleinschreibung geachtet werden muss Verwendung von Namespaces Die korrekte Verwendung von Namespaces ist zentral für das Erstellen von wiederverwendbaren Schnittstellendefinitionen. Dies sind die wichtigsten Namespaces, die für einen Kontrakt definiert werden: Externe XML Schema Namespaces für die Definition von Datentypen Namespace für gemeinsam genutzte Fault Definitionen WSDL Namespace für Interface- und Binding-Definitionen Lokaler Schema-Namespace für XML Schema Definitionen, die in der WSDL Definition enthalten sind. 7.3 Definition Sektion Sowohl der abstrakte wie auch der konkrete Teil der Service-Schnittstellenbeschreibung werden durch das definitions Element gekapselt. Wobei wie bereits erwähnt, diese Teile auch in unterschiedlichen physischen Dokumenten gehalten werden können. In diesem Fall müssen sie von einem Hauptdokument über einen <wsdl:import> importiert werden Das <definitions> Element Alles was zwischen dem öffnenden und schliessenden <definitions> Element steht, macht den Web Service-Kontrakt aus. <wsdl:definitions name="creditcardvalidation-v1" targetnamespace=" xmlns:tns=" xmlns:wsdl=" xmlns:soap=" </definitions> Abbildung 6: Das <definitions> Element kapselt den gesamten Service-Kontrakt Wie in Abbildung 6 zu sehen, kann das <definitions> Element verschiedene, optionale Attribute enthalten. Neben dem name und dem targetnamespace Attribut sind es mehrere xmlns Attribute, die einem bestimmten Namespace, einen entsprechenden Präfix zuordnen. Version 2.0 Seite 18/41

19 Obwohl optional, ist das targetnamespace Attribut sehr wichtig, da es den Namespace der Elemente bestimmt, die direkt im WSDL-Dokument definiert werden. Das Verwenden eines adäquaten Namespaces für die WSDL Definition ist ebenso wichtig, wie bei der Definition eines XML Schemas, daher muss das targetnamespace Attribut zwingend verwendet werden. Version 2.0 Seite 19/41

20 NMR-0010 Jede WSDL Definition MUSS über das name Attribut benennt werden. Dem Name muss als Suffix die Major-Versionsnummer angehängt werden: <service-name> v<major>. <wsdl:definitions name="creditcardvalidation-v1"...> NMR-0011 Ein WSDL Namespace MUSS dem folgenden Pattern gehorchen: URN urn:<organization>:<organization hierarchy>[:<organization hierarchy level>]*:<wsdl document type>[:<package>]+[:<status>]:v<major-version> URL hierarchy>[/<organization hierarchy level>]*/<wsdl document type>[/<package>]+[/<status>]/v<major-version> wobei: organization ein Identifier der Organisation, welche den Service- Kontrakt zur Verfügung stellt organization hierarchy die erste Stufe einer Hierarchie innerhalb der Organisation, welche den Service-Kontrakt zur Verfügung stellt organization hierarchy level 0 oder mehrere Hierarchiestufen der Organisation, welche den Service-Kontrakt zur Verfügung stellt wsdl document type ein Token, welcher den Typ des WSDL- Dokumentes identifiziert: contract fault documentation package - eine oder mehrere Stufen von Packages getrennt durch ein / Zeichen status der optionale Status des WSDL-Dokumentes: draft standard major die Major Versionsnummer Beispiele: NMR-0012 Für den Präfix (Alias) im xmlns Attribut der Namespace-Deklaration MUSS das Lower- CamelCase Format verwendet werden. <wsdl:definitions name="creditcardvalidation-v1" xmlns:tns=" NMR-0013 Für die allgemein gütigen Namespaces von Standards und Spezifikationen SOLLTEN folgende Präfixe (Alias) im xmlns Attribut verwendet werden: xsd wsdl soap soap12 wsa wsa SHOULD Version 2.0 Seite 20/41

21 GEN-0014 Jedes WSDL MUSS über das targetnamespace Attribut einen Target Namespace definieren. GEN-0015 Der Präfix tns MUSS über das xmlns Attribut mit dem Target Namespace verbunden werden (xmlns:tns=...) Das <documentation> Element Jeder Teil der WSDL Dokumentation kann über das documentation Element mit Kommentaren versehen werden. Das documentation Element wird häufig verwendet, um: Das Ziel und den Zweck des Services zu beschreiben Die Funktionalität zu beschreiben, die die einzelnen Service-Operationen zur Verfügung stellen Die einzelnen Nachrichten bzw. die Message Exchange Patterns zu beschreiben Den fachlichen Kontext zu beschreiben, unter welchem der Service oder eine der Operationen verwendet werden darf. Kontaktinformationen zum Service-Besitzer (service owner) und des technischen Supports, die für den Betrieb des Services verantwortlich sind, anzugeben Um Versionierungs-Informationen (Versionsnummern) anzugeben Das <import> Element Das import Element kann verwendet werden, um WSDL Definitionen aus einem anderen Dokument zu importieren. Es ähnelt damit dem xsd:import Element, das es bei der XML Schema Sprache gibt und ist in Abbildung 7 dargestellt. <wsdl:import location="commonfaults-v1.0.wsdl" namespace=" Abbildung 7: Das <import> Element erlaubt das Importieren von anderen WSDL Dokumenten Das import Element muss zu Beginn des WSDL Dokumentes stehen, gleich nach dem öffnenden definitions Element. Nur ein documentation Element kann davor verwendet werden. Version 2.0 Seite 21/41

22 IBP-2001 Ein Service-Kontrakt DARF NUR das wsdl:import Element nutzen, um andere WSDL Definitionen zu importieren. IBP-2803 Das Namespace-Attribut vom wsdl:import DARF NICHT eine relative URI sein. NOT IBP-2007 IBP-2022 IBP-2008 Ein WSDL Beschreibung MUSS im wsdl:import für das location Attribut mit einem gültigen Wert verwenden. Wenn ein wsdl:import im WSDL vorkommt, dann MUSS dieses vor allen anderen Elemente des WSDL-Namespaces stehen (ausser wsdl:documentation) Ein Konsument DARF über die URI, die im location Attribut vom wsdl:import definiert ist, auf das WSDL zugreifen. Das location Attribut ist nur ein Hint, ein WSDL Prozessor kann andere Mittel haben, um die WSDL Beschreibung zum entsprechenden Namespace aufzufinden. BEP-0043 Wir empfehlen für das location Attribut eine relative URI zu verwenden. MAY MAY 7.4 Typen Definitionen Ein XSD Schema wird für die Definition der Datentypen der zu übermittelnden Daten verwendet. Diese Datenmodelle sollten separat von den Serviceeigenschaften (Operationen) durch externe XML Schema Dokumente definiert und implementiert werden. Schemas sollten so zentralisiert werden, dass für jede Kernentität ein XML Schema Dokument definiert wird (z.b. Bestellung, Kunde, usw.) Für das Modellieren in XML gelten die im Dokument [XML-SCHEMA-GUIDE-10] beschriebenen XML Schema Richtlinien Das <types> Element Beim Beschreiben der Services in einem WSDL Kontrakt werden komplexe Datentypen als logische Einheiten mit Hilfe eines XML Schemas definiert. Das erste, über das man sich bei der Definition eines Service Gedanken machen muss, ist wie die Daten repräsentiert werden sollen, die als Nachricht den angebotenen Operationen übergeben werden. Die Datentypen, welcher der Service verwendet, sollten immer in einem separaten XSD-File gehalten werden, anstatt diese direkt in der Types Sektion des WSDL Dokumentes zu definieren. Diese XSD Files können dann über das <xsd:import> Tag in der Types Sektion des WSDLs importiert werden, wie dies Abbildung 8 zeigt. <wsdl:types> <xsd:schema targetnamespace=" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:import namespace=" schemalocation="../xsd/creditcard-v1.1.xsd" /> <xsd:import namespace=" schemalocation="../xsd/servicecontext-v1.0.xsd"/> Version 2.0 Seite 22/41

23 ... </wsdl:types> Abbildung 8: Das <types> Element erlaubt das Definieren bzw. Importieren von XML-Schema Datentypen Das <xsd:include> Element verlangt, dass das eingefügte Schema denselben Target- Namespace besitzt, wie das Schema, welches das <xsd:include> Element enthält. Das <xsd:import> Element besitzt diese Restriktion nicht und ist daher die bevorzugte Lösung für dieses Szenario. GEN-0016 GEN-0017 GEN-0018 GEN-0019 IBP-2002 IBP-2003 IBP-2004 IBP-2010 IBP-2011 BEP-0044 BEP-0045 Wiederverwendbare Datentypen SOLLEN in einem eigenen, externen XML Schema Dokument definiert werden und nicht in der Types-Sektion in der WSDL Beschreibung. Das xsd:elementformdefault Attribut MUSS verwendet werden und der Wert auf qualified gesetzt sein. <xsd:schema... elementformdefault="qualified"> Das xsd:attributeformdefault Attribut MUSS verwendet werden und der Wert auf unqualified gesetzt sein. <xsd:schema... attributeformdefault="unqualified"> Der xsd Präfix MUSS auf Stufe WSDL-Definition gesetzt werden und auf referenzieren. Um XML Schema Definitionen zu importieren, MUSS das WSDL den XML Schema xsd:import verwenden. Ein WSDL Beschreibung DARF das xsd:import Statement NUR innerhalb des xsd:schema Elements der Types Sektion verwenden. Das schemalocation Attribut von einem xsd:import Element MUSS ein Dokument referenzieren, bei dem das Root-Element schema aus den Namespace ist. Ein XML-Schema, das direkt oder indirekt von einem WSDL importiert wird, MUSS entweder UTF-8 oder UTF-16 Encoding verwenden. Ein XML-Schema das direkt oder indirekt von einem WSDL importiert wird, MUSS Version 1.0 der XML W3C Recommendation verwenden. Es wird empfohlen, für das targetnamespace Attribut den gleichen Wert wie beim Target-Namespace des Service zu verwenden. Es wird empfohlen, für die Typen der Nachrichten Wrapper-Typen zu definieren und diese direkt in der Types-Sektion zu definieren, da diese nicht wiederverwendbar sind (GEN-0016 nicht gilt). SHOULD MAY SHOULD Version 2.0 Seite 23/41

24 7.5 Nachrichten Definitionen Ein Service ist durch die Nachrichten definiert, die ausgetauscht werden, wenn eine Operation aufgerufen wird. In einer WSDL Beschreibung werden diese Nachrichten über die <message> Elemente definiert. Die Nachrichten werden dabei durch eine oder mehrere Teile beschrieben, die über das <part> Elements definiert werden Das <message> Element Das message Element repräsentiert eine abstrakte Nachricht, die ein Service mit den Konsumenten austauscht. <wsdl:message name="validatecardrequestmsg"> <wsdl:part.../> </wsdl:message> Abbildung 9: Das <message> Element definiert eine abstrakte Nachricht Eine Service-Operation ist definiert durch die Definition der logischen Nachrichten, die beim Aufruf der Operation ausgetauscht werden. Diese Nachrichten definieren die Informationen, die über die Netzwerk-Verbindung als XML Dokumente übertragen werden. Die Nachrichten enthalten all die Informationen, die Teil des Aufrufs und optional Teil der Antwort sind. Logische Nachrichten werden über das <message> Element definiert. Jede einzelne Nachricht besteht aus einem oder mehreren Einheiten, die durch <part> Elemente definiert werden. Abbildung 9 zeigt das <message> Element. Jede Operation, die von einem Service angeboten wird, kann nur eine Input- und eine Output-Nachricht besitzen. Die Input-Nachricht definiert dabei die Informationen, welche der Service erhält, wenn die Operation aufgerufen wird. Die Output-Nachricht definiert die Daten, die der Service zurückgibt, wenn die Operation endet. Zusätzlich kann eine Operation mehrere Fault-Nachrichten benutzen. Eine Fault-Nachricht definiert die Daten, welche der Service zurückgibt, wenn ein Fehler auftritt. Diese Nachrichten haben üblicherweise nur genau einen <part>, der die Informationen zurückliefert, welche der Service-Konsument braucht, um den Fehler abzuhandeln. Version 2.0 Seite 24/41

25 GEN-0020 Eine wsdl:message Nachrichtendefinition in der WSDL Definition DARF NUR von einer Operation verwendet werden. GEN-0021 Eine wsdl:message Nachrichtendefinition MUSS einen Namen im Attribut name verwenden, der eindeutig innerhalb des WSDL und des Target-Namespace ist. NMR-0022 Der Name einer Input-Nachricht im name Attribut MUSS aus dem Namen der Operation in UpperCamelCase (UCC) und dem Suffix RequestMsg gebildet werden. <wsdl:message name="validatecardrequestmsg" NMR-0023 Der Name einer Output-Nachricht im name Attribut MUSS aus dem Namen der Operation in UpperCamelCase (UCC) und dem Suffix ResponseMsg gebildet werden. <wsdl:message name="validatecardresponsemsg" NMR-0024 Der Name einer Fault-Nachricht in UpperCamelCase (UCC) MUSS möglichst genau den Grund für den Fehler beschreiben und das Suffix FaultMsg benutzen. <wsdl:message name="invalidcardnumberfaultmsg" Das <part> Element Das message Konstrukt kann ein oder mehrere (falls SOAP Header explizit definiert werden) part Elemente enthalten, die zusammen die Nachricht, bzw. die Informationen, die über die Nachricht ausgetauscht werden, definieren. Die part Element beschreiben die Dateneinheiten einer logischen Nachricht. Die SOA Community favorisiert heutzutage den sogenannten Document/Literal Wrapped Style. Dies bedeutet, dass die Nachrichten so definiert werden, dass jede Nachricht nur genau durch einen einzelnen Part definiert wird, der die gesamte Nachricht enthält und beschreibt (zusätzliche Parts sind möglich, falls Informationen über SOAP-Header ausgetauscht und diese explizit beschrieben werden sollen). Das <part> Element selbst referenziert dabei ein einzelnes Element (Wrapper-Element), welches innerhalb des Kontraktes definiert werden muss. Das Wrapper-Element kann dabei direkt in der <types> Sektion vom WSDL definiert werden (Abbildung 10) oder aber in einem externen XML Schema, das über das <import> Element ins WSDL eingebunden wird (Abbildung 12). Wird das Element wie in Abbildung 10 dargestellt definiert, befindet es sich im Namespace vom Service-Kontrakt. <wsdl:types> <xsd:schema> <xsd:import namespace=" schemalocation="../xsd/creditcard-v1.0.xsd"/> <xsd:import namespace=" schemalocation="../xsd/servicecontext-v1.0.xsd"/> <xsd:element name="validatecardrequest" type="tns:validatecardrequesttype"/> <xsd:element name="validatecardresponse" type="tns:validatecardresponsetype"/> Version 2.0 Seite 25/41

26 <xsd:element name="invalidcardnumberfault" type="tns:invalidcardnumberfaulttype"/> <xsd:element name="cardexpiredfault" type="tns:cardexpiredfaulttype"/> <xsd:complextype name="validatecardrequesttype"> <xsd:sequence> <xsd:element name="requestnr" type="xsd:string" minoccurs="1"/> <xsd:element name="creditcard" type="credit:creditcardtype" minoccurs="1" maxoccurs="1"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="validatecardresponsetype"> <xsd:sequence> <xsd:element name="transactionid" type="xsd:string" minoccurs="1"/> </xsd:sequence> </xsd:complextype> Abbildung 10: Die Definition der Wrapper-Elemente innerhalb der Types-Sektion des WSDL Wird ein Wrapper-Element hingegen in einem externen XML Schema definiert und in der <types> Sektion vom WSDL referenziert, wie in Abbildung 11 dargestellt, dann sollte dies vorzugsweise mit einem <include> geschehen. <wsdl:types> <xsd:schema> <xsd:include schemalocation="../xsd/creditcardvalidationmsgwrp-v1.0.xsd"/> </xsd:schema> Abbildung 11: Importieren der Wrapper-Elemente aus einem externen XML Schema Damit ist der Unterschied lediglich die Paketierung der Wrapper-Elemente, einmal sind sie in der Types-Sektion eingebettet (Abbildung 10) und einmal über eine externe Definition included (Abbildung 11). Bei beiden Varianten gehören die Wrapper-Elemente jedoch zum Namespace des Service-Kontraktes. Werden die Wrapper-Elemente, wie in Abbildung 12 dargestellt, im externen XML Schema definiert, dann darf dieses Schmema nur für die Definition der Nachrichten Wrapper- Elemente verwenden werden und nicht mit der Definition von Business-Objekten gemischt werden. Die Business Objekte müssen zwingend in einem eigenen, dedizierten XML Schemas definiert werden, wie dies in Abbildung 12 mit dem CreditCard Objekt gezeigt ist, welches aus dem CreditCard-v1.0.xsd importiert und referenziert wird. <xsd:schema xmlns:tns=" targetnamespace=" xmlns:xsd=" > <xsd:import namespace=" schemalocation="../xsd/creditcard-v1.0.xsd"/> <xsd:import namespace=" schemalocation="../xsd/servicecontext-v1.0.xsd"/> <xsd:element name="validatecardrequest" type="tns:validatecardrequesttype"/> <xsd:element name="validatecardresponse" type="tns:validatecardresponsetype"/> <xsd:element name="invalidcardnumberfault" type="tns:invalidcardnumberfaulttype"/> <xsd:element name="cardexpiredfault" type="tns:cardexpiredfaulttype"/> <xsd:complextype name="validatecardrequesttype"> <xsd:sequence> Version 2.0 Seite 26/41

27 <xsd:element name="requestnr" type="xsd:string" minoccurs="1"/> <xsd:element name="creditcard" type="credit:creditcardtype" minoccurs="1" maxoccurs="1"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="validatecardresponsetype"> <xsd:sequence> <xsd:element name="transactionid" type="xsd:string" minoccurs="1"/> </xsd:sequence> </xsd:complextype> Abbildung 12: Die Definition der Wrapper-Elemente im externen XML Schema Jeder Part wird durch das <part> Element beschrieben, wobei mit dem name Attribut der Namen definiert und über ein element der Datentyp spezifiziert wird. <wsdl:message name="validatecardrequestmsg"> <wsdl:part name="versionheader" element="ctx:serviceversion" /> <wsdl:part name="validatecardrequest" element="tns:validatecardrequest" /> </wsdl:message> Abbildung 13: Das <part> Element definiert die Nachricht über das Wrapper-Element Das Beispiel zeigt ferner die zusätzliche Definition eines SOAP Header Elements. Dieses wird ebenfalls über ein externes XML Schema importiert und über den ctx Alias referenziert. Version 2.0 Seite 27/41

28 GEN-0025 NMR-0026 BEP-0027 Das name Attribut von wsdl:part MUSS innerhalb des WSDL Target-Namespace eindeutig sein. Das name Attribut von wsdl:part MUSS aus dem Namen der Operation in UpperCamelCase (UCC) und dem Suffix Request (bei Input-Nachricht) oder Response (bei Output-Nachricht) gebildet werden. <wsdl:part name="validatecardrequest"...> Um den Document/Literal Wrapped Style umzusetzen, MUSS in der <types> Sektion im WSDL oder im importierten XML Schema für jede Nachricht ein Wrapper- Element definiert werden. Die Typen können dabei eigenständig definiert sein, oder aber direkt bei der Wrapper-Elementdefinition als anonymer Typ definiert werden. Beispiel (eigener Type): <xsd:schema...> <xsd:import.../> <xsd:element name="validatecardrequest" type="tns:validatecardrequesttype"/> <xsd:complextype name="validatecardrequesttype">... </xsd:complextype> Beispiel (anonymer Type) <xsd:schema...> <xsd:import.../> <xsd:element name="validatecardrequest"> <xsd:complextype>... </xsd:complextype> </xsd:element> BEP-0028 BEP-0029 BEP-0047 Es wird EMPFOHLEN, das Wrapper-Element und die zugehörige Typen-Deklaration immer zusammen und im gleichen Artefakt zu definieren, entweder in der <types> Sektion des WSDL oder im eingebetteten XML Schema. Werden die Wrapper-Elemente und -Typendeklarationen in einem externen Schema definiert, dann SOLLTEN diese über eine <include> Anweisung in die Types- Sektion eingebettet werden. Werden die Wrapper-Elemente über ein externes XML Schema eingebettet ( included ), dann DARF das entsprechende XML Schema NUR für die Definition der Wrapper-Elemente genutzt werden, nicht aber auch für die Definition von Business Objekten. Diese sollen in einem eigenen, dedizierten XML Schema definiert werden. <xsd:schema...> <xsd:import SHOULD SHOULD Version 2.0 Seite 28/41

29 namespace=" schemalocation="../xsd/creditcard-v1.0.xsd"/> <xsd:element name="validatecardrequest" type="tns:validatecardrequesttype"/> <xsd:complextype name="validatecardrequesttype"> <xsd:sequence> <xsd:element name="creditcard" type="credit:creditcardtype" minoccurs="1" maxoccurs="1"/> NMR-0030 NMR-0046 IBP-2204 IBP IBP IBP-2206 IBP-2306 Werden die Wrapper-Elemente über ein externs XML Schema eingebettet ( included ), dann SOLLTE der Filename des entsprechenden XML Schemas, wie in NMR-0004 beschrieben, aus dem Service-Namen bestehen. CreditCardValidation-v1.0.xsd Die Namen der Wrapper-Elemente SOLLTE nach folgendem Pattern aufgebaut werden: <Operation Name>Request Response und <Fault Name>Fault ValidateCardRequest oder ValdiateCardResponse Für ein Document Literal Binding MUSS ein wsdl:part Element immer über ein element Attribut definiert sein. <wsdl:part name="..." element="tns:validatecardrequest"> Eine Nachricht DARF NUR maximal ein part Element enthalten, welches auf das SOAP Body Element gebunden wird. Zusätzliche part Elemente sind nur zulässig, wenn diese Header oder Headerfault Typen repräsentieren. Eine wsdl:message KANN auch ohne part Elemente definiert werden, um Nachrichten mit leeren soap:body empfangen und versenden zu können. Eine wsdl:message in einem WSDL mit einem wsdl:part Element MUSS im element Attribut auf eine globale Element Deklaration referenzieren. Global bedeutet dabei, dass das Element im XML Schema direkt unterhalb des Root Schema Elementes definiert ist. <wsdl:part name="validatecardrequest" element="tns:validatecardrequest" /> Im gleichen wsdl:part Element DUERFEN NICHT das type Attribut und das element Attribut zusammen verwendet werden. SHOULD SHOULD COULD NOT Version 2.0 Seite 29/41

30 7.6 PortType Definitionen Das logische Service-Interface wird durch das porttype Konstrukt definiert. Das Element porttype stellt dabei einen Container für verschiedene Operationen zur Verfügung Das <porttype> Element Das porttype Konstrukt kann aus einem oder mehreren operation Konstrukten bestehen, wie dies Abbildung 14 zeigt. <wsdl:porttype name="creditcardvalidationporttype"> <wsdl:operation...>... </wsdl:operation/> <wsdl:operation...>... </wsdl:operation/> </wsdl:porttype> Abbildung 14: Das <porttype> Element im WSDL NMR-0031 GEN-0032 GEN-0033 Das name Attribut von wsdl:porttype MUSS aus dem Service-Namen (aus dem name Attribut in wsdl:definitions) ohne Versionssuffix und dem Suffix PortType gebildet werden. <wsdl:porttype name="creditcardvalidationporttype"> Jeder Service SOLLTE nur genau ein wsdl:porttype Element enthalten. Es SOLL ein neues WSDL erstellt werden, wenn ein zweiter, zusätzlicher Kontrakt erforderlich ist. Ein wsdl:porttype MUSS mindestens eine Operation, d.h. ein wsdl:operation Element enthalten. SHOULD Das <operation> Element Jedes WSDL braucht mindestens eine Operation, damit der Service von einem externen Konsumenten verwendet werden kann. Mit jedem operation Konstrukt wird daher die technische Schnittstelle um einen Teil erweitert. Abbildung 15 zeigt die Definition der ValidateCard Operation mit der Definition von einer Input-, einer Output- und zwei Fehler- Nachrichten. <wsdl:porttype name="creditcardvalidationporttype"> <wsdl:operation name="validatecard"> <wsdl:input name="validatecardrequest" message="tns:validatecardrequestmsg"/> <wsdl:output name="validatecardresponse" message="tns:validatecardresponsemsg"/> <wsdl:fault name="invalidcardnumberfault" message="tns:invalidcardnumberfaultmsg"/> <wsdl:fault name="cardexpiredfault" message="tns: CardExpiredFaultMsg"/> <wsdl:fault name="serviceexceptionfault" Version 2.0 Seite 30/41

31 message="common-faults:serviceexceptionfaultmsg"/> </wsdl:operation> </wsdl:porttype> Abbildung 15: Das <operation> Element innerhalb von einem <porttype> im WSDL Message Exchange Patterns (MEP) Ein Operation Konstrukt kann jede Kombination von input, output und fault Elementen enthalten. Bei WSDL 1.1 definiert die Verwendung und Reihenfolge vom input und output Element das Message Exchange Pattern (MEP) zwischen dem Service-Anbieter und dem Service-Nutzer. Die WSDL 1.1 Spezifikation definiert insgesamt 4 MEPs, wobei nur zwei davon durch WS-I Basic Profile unterstützt werden: Request-Response eine Operation empfängt eine Input-Nachricht und gibt eine Antwort- oder Fehler-Nachricht zurück. Eine Operation, welche dieses Pattern implementiert sieht syntaktisch folgendermassen aus: <operation...> <input.../> <output.../> </operation> One-Way eine Operation empfängt eine Input-Nachricht und gibt nichts zurück. Dies bedeutet, dass nur genau ein Input-Element verwendet wird, wie nachfolgend zu sehen: <operation...> <input.../> </operation> Solicit-Response eine Operation sendet eine Nachricht und bekommt eine Antwort oder einen Fehler zurück. Die Struktur ist im Wesentlichen eine umgekehrte Request- Response: <operation...> <output.../> and/or <fault.../> <input.../> </operation> Notification eine Operation sendet eine Nachricht und empfängt nichts: <operation...> <output.../> and/or <fault.../> </operation> Aus Interoperabilitätsgründen können und dürfen nur die beiden MEP s Request-Response und One-Way verwendet werden. Version 2.0 Seite 31/41

32 NMR-0034 IBP-2303 IBP-2304 Der Name der Operation im name Attribut von wsdl:operation MUSS so definiert sein, dass möglichst gut umschrieben wird, was die Operation anbietet. <wsdl:operation name="validatecard"> Eine WSDL Definition DARF NICHT Operationen vom Typ Solicit Response und Notification verwenden. Eine wsdl:operation Definition MUSS einen Name verwenden, der eindeutig innerhalb des wsdl:porttype ist. Ein Operation Overloading ist damit nicht zulässig. Version 2.0 Seite 32/41

33 7.7 Binding Definition Das <binding> Element Die Struktur des binding Konstrukts lehnt sich an die Struktur vom porttype Konstrukt an, wie dies Abbildung 17 zeigt. <wsdl:binding name="creditcardvalidationhttpsoap11binding" type="tns:creditcardvalidationporttype"> <soap:binding style="document" transport=" /> <wsdl:operation name="validatecard"> <soap:operation soapaction=" /> <wsdl:input> <soap:body parts="validatecardrequest" use="literal"/> <soap:header message="tns:validatecardrequestmsg" part="versionheader" use="literal"/> </wsdl:input> <wsdl:output> <soap:body parts="valdiatecardresponse" use="literal"/> <soap:header message="tns:validatecardresponsemsg" part="versionheader" use="literal"/> </wsdl:output> <wsdl:fault name="invalidcardnumberfault"> <soap:fault name="invalidcardnumberfault" use="literal"/> </wsdl:fault> <wsdl:fault name="cardexpiredfault"> <soap:fault name="cardexpiredfault" use="literal"/> </wsdl:fault> </wsdl:operation> </wsdl:binding> Abbildung 16: Das <binding> Element im WSDL Mehrere binding Konstrukte können in der gleichen WSDL Definition existieren. Gründe dafür sind: Eine abstrakte PortType Definition soll mit mehreren Binding Definitionen assoziiert werden, um unterschiedliche Arten der Kommunikation anzubieten (SOAP über HTTP, SOAP über JMS, usw.). Eine WSDL Definition kann mehrere PortType Definitionen enthalten, die einzeln über Binding Definitionen definiert werden müssen. Version 2.0 Seite 33/41