WSDL omwienie

Aaron Skonnard Northface University

padziernik 2003 roku

Dotyczy: usugi XML Web Service jzyk Web Services Description Language (WSDL) 1.1 WS-I Basic Profile w wersji 1.0 przesyanie komunikatw XML schematy XML

Streszczenie: WSDL jest bardzo wany w caej architekturze usug XML Web Service, poniewa opisuje peny kontrakt komunikacji aplikacji. Definicje WSDL znacznie uatwiaj dostp do usug XML Web Service, pozwalajc na generowanie kodu, ktry umoliwia wspprac aplikacji z opisywan usug bez szczegowego wnikania w odbywajcy si za porednictwem rnych protokow proces wysyania i odbierania komunikatw SOAP. Dugo dokumentu okoo 18 stron drukowanych. Spis treci Wprowadzenie Podstawy WSDL Element types Elementy message Interfejsy (elementy portType) Elementy binding Elementy service Edytory WSDL Gdzie jestemy? Bibliografia Dodatek A WSDL

Wprowadzenie
XML umoliwia programistom udostpnienie cennych zasobw w sposb wysoce interoperacyjny, przy czym zasobem moe by dowolny typ aplikacji lub magazyn danych wykorzystywany w firmie. Architektura usug XML Web Service definiuje standardowy mechanizm udostpniania zasobw za porednictwem komunikatw XML. Moliwo uzyskania dostpu do zasobw poprzez przesyanie komunikatw XML za pomoc jednego ze standardowych protokow transportowych (takich jak TCP, HTTP lub SMTP) znacznie obnia poprzeczk dla

potencjalnych klientw. Termin usuga XML Web Service (lub po prostu usuga) zazwyczaj odnosi si do kodu implementujcego interfejs XML dla zasobu, do ktrego moe by trudno uzyska dostp w inny sposb (ilustracja 1).

Ilustracja 1. Zasoby i usugi

Dziki takiej architekturze dowolny klient, obsugujcy XML, moe zosta zintegrowany z aplikacj udostpniajc usug XML Web Service. Aby to osign, klienci musz z gry precyzyjnie ustali interfejs XML wraz z rnymi szczegami komunikatw. Schematy XML czciowo zaspokajaj t potrzeb, poniewa pozwalaj programistom opisa struktur komunikatu XML. Sam schemat XML nie moe jednak posuy do opisania dodatkowych szczegw dotyczcych komunikacji z t usug.

Definicja schematu okrela, jakie komunikaty XML mog by uyte, ale nie mwi nic o tym, jaki maj ze sob zwizek. Jeli na przykad istnieje element XML o nazwie Add oraz element o nazwie AddResponse, prawdopodobnie elementy te s ze sob jako zwizane, ale nie ma moliwoci zaznaczenia tego w schemacie. Dlatego klient nie tylko powinien zna szczegy dotyczce komunikatw, ale powinien rwnie zna moliwe metody komunikacji, obsugiwane przez dan usug XML Web Service (np. jeli wysany zostanie komunikat Add, to w odpowiedzi otrzymany zostanie komunikat AddResponse).

Wymiana komunikatw jest nazywana operacj. Operacje le w centrum zainteresowania klientw, poniewa to one su do interakcji z usug (ilustracja 2). Ilekro korzystam z nowej usugi XML Web Service, najpierw zapoznaj si z list obsugiwanych operacji aby dowiedzie si, jak funkcjonalno ma ta usuga.

Ilustracja 2. Komunikaty i operacje

Programici s przyzwyczajeni do grupowania powizanych ze sob operacji w interfejsy. Klienci musz zdawa sobie spraw z takiego grupowania, poniewa wpywa ono na sposb, w jaki tworz aplikacje. Jest to przede wszystkim wane dla programistw pracujcych z usugami XML Web Service w rodowisku zorientowanym obiektowo, poniewa interfejsy XML mog by czone z interfejsami programistycznymi (lub klasami abstrakcyjnymi), napisanymi w wybranym jzyku programowania.

Klienci musz take wiedzie, jaki protok komunikacyjny naley stosowa do komunikacji z usug oraz powinni zna mechanizmy zwizane z danym protokoem stosowane polecenia, nagwki i kody bdw. Wizanie do protokou szczegowo okrela transmisj poprzez opisanie sposobu korzystania z interfejsu w poczeniu z konkretnym protokoem komunikacyjnym. Wizanie wpywa take na sposb kodowania abstrakcyjnych komunikatw, poniewa okrela typ zawartoci komunikatu (dokument XML lub wywoanie RPC) oraz mechanizmy kodowania (na podstawie schematu XML lub regu kodowania). Wicej informacji na ten temat mona znale w artykule SOAP omwienie.

Usuga moe obsugiwa kilka wiza dla jednego interfejsu, ale kade wizanie powinno by dostpne pod unikalnym, identyfikowanym za pomoc URI adresem, nazywanym take punktem kocowym usugi XML Web Service (ilustracja 3).

Ilustracja 3. Interfejsy i wizania

Klienci musz zna wszystkie opisane powyej szczegy, zanim zaczn korzysta z usugi XML Web Service. Jzyk Web Services Description Language (WSDL) zapewnia gramatyk XML do opisywania tych szczegw. Tam, gdzie koczy si funkcjonalno schematw XML, zaczyna si funkcjonalno WSDL, zapewniajc moliwo grupowania komunikatw w operacje, a operacji w interfejsy. Zapewnia take sposb definiowania wiza interfejsw do protokow i przypisywania im adresw punktw kocowych. Pena definicja WSDL zawiera wszystkie informacje niezbdne do korzystania z usugi XML Web Service. Programici, ktrzy chc uatwi dostp do swoich usug, powinni udostpni definicje WSDL tych usug.

WSDL odgrywa wan rol w caej architekturze usug XML Web Service, poniewa opisuje peny kontrakt komunikacji aplikacji (ma podobne znaczenie jak IDL dla architektury DCOM). Chocia istniej inne techniki opisywania usug XML Web Service, specyfikacja WS-I Basic Profile Version 1.0 wymaga zastosowania w tym celu WSDL oraz schematw XML (ilustracja 4). Uatwia to zachowanie interoperacyjnoci w warstwie opisu usugi.

Ilustracja 4. Technologie skadajce si na podstawowy profil usug XML Web Service WS-I Basic Profile 1.0

Poniewa WSDL jest jzykiem czytelnym dla urzdze (jest to plik XML), mona w atwy sposb zbudowa dla niego narzdzia i infrastruktur. Programici mog wykorzysta definicje WSDL do wygenerowania kodu komunikujcego si z usug opisywan przez dany plik WSDL. Generowanie kodu pozwala unikn trudnej implementacji wysyania i otrzymywania komunikatw SOAP za porednictwem rnych protokow, co zwiksza dostpno usugi XML Web Service.

W rodowisku Microsoft .NET Framework dostpne jest narzdzie wiersza polecenia o nazwie wsdl.exe, ktre suy do generowania klas na podstawie definicji WSDL. Narzdzie wsdl.exe moe wygenerowa klas umoliwiajc dostp do usugi oraz klas implementujc usug. rodowisko Apache Axis zawiera podobne narzdzie o nazwie WSDL2Java, ktre przeprowadza takie same operacje, tyle e dla klas Java. Klasy wygenerowane z tej samej definicji WSDL powinny by zdolne do komunikowania si ze sob za porednictwem interfejsw zapewnionych przez WSDL bez wzgldu na zastosowany jzyk programowania (ilustracja 5).

Ilustracja 5. WSDL i generowanie kodu

Jzyk WSDL 1.1 uwaany jest de facto za standard ze wzgldu na szerokie wsparcie. Wikszo narzdzi do tworzenia usug XML Web Service obsuguje WSDL 1.1, ale stwierdzono pewne problemy ze wspprac pomidzy rnymi implementacjami. Wielu programistw uwaa, e dua elastyczno WSDL (i wynikajca

z niej zoono) jest podstawowym rdem tych problemw. WS-I pomogo rozwiza kilka problemw, zachcajc programistw do wykorzystania pewnych fragmentw specyfikacji i zniechcajc ich do korzystania z innych fragmentw.

Konsorcjum W3C aktywnie pracuje nad nastpn oficjaln wersj WSDL WSDL 1.2, ale obecnie jest to tylko wstpny projekt, nieobsugiwany przez aden z gwnych zestaww narzdzi. W pozostaej czci tego artykuu omwiono definicj WSDL 1.1 oraz niektre propozycje dotyczce podstawowego profilu usug XML Web Service.

Podstawy WSDL
Definicja WSDL to dokument XML, ktrego gwny element definitions jest definiowany przez przestrze nazw http://schemas.xmlsoap.org/wsdl/. Cay schemat WSDL jest dostpny pod adresem http://schemas.xmlsoap.org/wsdl/. Element definitions moe zawiera kilka innych elementw w tym types, message, portType, binding, service pochodzcych z przestrzeni nazw http://schemas.xmlsoap.org/wsdl/. W poniszym przykadzie zilustrowano podstawow struktur definicji WSDL: <!-- struktura definicji WSDL --> <definitions name="MathService" targetNamespace="http://example.org/math/" xmlns="http://schemas.xmlsoap.org/wsdl/" > <!-- definicje abstrakcyjne --> <types> ... <message> ... <portType> ... <!-- definicje konkretne --> <binding> ... <service> ... </definitions> W przypadku definicji WSDL tak samo jak w przypadku definicji schematu XML naley poda docelow przestrze nazw. Wszystko, co w definicji WSDL zostanie nazwane (np. message, portType, binding itp.), automatycznie staje si czci docelowej przestrzeni nazw definicji WSDL, zdefiniowanej poprzez atrybut targetNamespace. Dlatego jeli odwoujemy si w pliku WSDL do czego przy uyciu nazwy powinnimy pamita, by uy nazwy kwalifikowanej.

Pierwsze trzy elementy (types, message i portType) s definicjami abstrakcyjnymi interfejsu usugi XML Web Service. Elementy te skadaj si na interfejs programistyczny, do ktrego bdziemy uzyskiwali dostp z naszej aplikacji. Ostatnie dwa elementy (binding i service) szczegowo opisuj sposb, w jaki wywoania abstrakcyjnego interfejsu tumaczone s na przesyane komunikaty. Tumaczenie to zazwyczaj jest obsugiwane przez infrastruktur, a nie przez kod tworzonej aplikacji. W tabeli 1. umieszczono krtkie definicje kadego z tych podstawowych elementw WSDL, a pozostae sekcje artykuu powicono na dokadniejsze ich omwienie.

Tabela 1. Elementy WSDL nazwa elementu types message portType opis zawiera definicje typw abstrakcyjnych zdefiniowanych przy uyciu schematu XML definicja abstrakcyjnego komunikatu, ktry moe skada si z wielu czci, a kada cz moe by innego typu abstrakcyjny zbir operacji obsugiwanych przez jeden lub kilka punktw kocowych (powszechnie nazywany interfejsem); operacje definiowane s poprzez okrelenie wymiany komunikatw specyfikacja konkretnego protokou i formatu danych dla okrelonego portType zbir powizanych punktw kocowych punkt kocowy definiowany jest jako poczenie wizania i adresu (URI)

binding service

Element types
Element types zawiera definicje typw w postaci schematw XML. Do umieszczonych w tym miejscu definicji typw odwouj si definicje wyszego poziomu, okrelajce szczegy strukturalne komunikatw. Oficjalnie WSDL 1.1 pozwala na zastosowanie dowolnego jzyka definicji typw, jednak specyfikacja zaleca stosowanie schematw XML traktowane s one jako wewntrzny system typw. Z kolei WS-I wymaga stosowania schematw XML w podstawowym profilu w wersji 1.0.

Element types moe zawiera dowoln liczb elementw schema z przestrzeni nazw http://www.w3.org/2001/XMLSchema. Podstawowa struktura elementu types (z pominiciem przestrzeni nazw) wyglda nastpujco (znak * oznacza zero lub wicej powtrze): <definitions .... > <types> <xsd:schema .... />* </types> </definitions> Wewntrz elementu schema mona uy dowolnej konstrukcji schematw XML definicji typw prostych, definicji typw zoonych i definicji elementw. Zamieszczony poniej fragment pliku WSDL zawiera definicj schematu XML, ktra okrela cztery elementy typu MathInput (Add, Subtract, Multiply oraz Divide) oraz cztery elementy typu MathOutput (AddResponse, SubtractResponse, MultiplyResponse oraz DivideResponse). <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > <types> <xs:schema targetNamespace="http://example.org/math/types/" xmlns="http://example.org/math/types/" > <xs:complexType name="MathInput"> <xs:sequence>

<xs:element name="x" type="xs:double"/> <xs:element name="y" type="xs:double"/> </xs:sequence> </xs:complexType> <xs:complexType name="MathOutput"> <xs:sequence> <xs:element name="result" type="xs:double"/> </xs:sequence> </xs:complexType> <xs:element name="Add" type="MathInput"/> <xs:element name="AddResponse" type="MathOutput"/> <xs:element name="Subtract" type="MathInput"/> <xs:element name="SubtractResponse" type="MathOutput"/> <xs:element name="Multiply" type="MathInput"/> <xs:element name="MultiplyResponse" type="MathOutput"/> <xs:element name="Divide" type="MathInput"/> <xs:element name="DivideResponse" type="MathOutput"/> </xs:schema> </types> ... </definitions> Osoby, ktrym tematyka schematw XML nie jest znana, mog si z ni zapozna czytajc artyku Schematy XML omwienie. Majc ju zdefiniowane typy w schematach XML mona przystpi do kolejnego etapu definiowania logicznych komunikatw skadajcych si na operacje.

Elementy message
Element message definiuje abstrakcyjny komunikat, ktry ma suy jako dane wejciowe lub wyjciowe operacji. Komunikaty skadaj si z co najmniej jednego elementu part i z kadym takim elementem zwizany jest albo atrybut element (gdy tre komunikatu stanowi dokument XML), albo atrybut type (gdy tre komunikatu to wywoanie RPC). Podstawowa struktura definicji komunikatu wyglda nastpujco (znak * oznacza dowoln liczb powtrze, a znak ? oznacza wystpienie opcjonalne): <definitions .... > <message name="nmtoken"> * <part name="nmtoken" element="qname"? type="qname"?/> * </message> </definitions> Elementy message oraz part musz posiada nazwy, aby moliwe byo odwoywanie si do nich z innych miejsc w definicji WSDL. Jeli definiowana jest usuga przesyajca w komunikatach wywoania RPC, to elementy part komunikatw reprezentuj parametry metody. W takim przypadku atrybut name elementu part okrela nazw elementu w konkretnym komunikacie, a struktura tego elementu jest ustalana na podstawie podanego atrybutu type. Jeli definiowana jest usuga przesyajca w komunikatach pene dokumenty XML, elementy part po prostu odwouj si do elementw XML umieszczonych w treci (odwoanie nastpuje poprzez atrybut element). Nastpujcy przykad zawiera kilka definicji komunikatw, ktre odwouj si do elementw po ich nazwie: <definitions xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > ... <message name="AddMessage"> <part name="parameter" element="ns:Add"/> </message> <message name="AddResponseMessage"> <part name="parameter" element="ns:AddResponse"/> </message> <message name="SubtractMessage"> <part name="parameter" element="ns:Subtract"/> </message> <message name="SubtractResponseMessage"> <part name="parameter" element="ns:SubtractResponse"/> </message> ... </definitions> Chocia czci komunikatu zazwyczaj odwouj si do typw XML lub do elementw XML, to mog si take odwoywa do typw nie bdcych typami XML. Dziki temu WSDL moe definiowa komunikaty, ktre zawieraj mieszank rnych formatw danych, tak jak w przypadku wieloczciowych wiadomoci MIME. Uwaga Definicje komunikatu i typu w WSDL s uwaane za definicje abstrakcyjne, dlatego dopki nie zastosuje si do nich wizania nie wiadomo, jak bd wyglday w ostatecznym formacie komunikatu. Jeli na przykad komunikat abstrakcyjny stosowany jest z dwoma rnymi wizaniami, to moliwe jest, e dwa wyjciowe komunikaty bd wyglday inaczej. Jedynie w przypadku wiza typu literal definicje abstrakcyjne gwarantuj dokadne przedstawienie ostatecznego formatu komunikatu. Wicej informacji mona znale w sekcji Elementy binding.

Interfejsy (elementy portType)

Element portType definiuje grup operacji, nazywan w wikszoci rodowisk interfejsem. Niestety termin portType jest dosy niejasny, dlatego lepiej stosowa bardziej zrozumiae okrelenie interfejs. W specyfikacji WSDL 1.2 usunito ju nazw portType i zastpiono j wyraeniem interface.

Element portType zawiera dowoln liczb elementw operation. Podstawowa struktura elementu portType jest nastpujca (znak * oznacza zero lub wicej powtrze): <definitions .... > <portType name="nmtoken"> <operation name="nmtoken" .... /> * </portType> </definitions> Kady element portType musi posiada unikaln nazw, dziki ktrej mona si do niego odwoywa z innych obszarw definicji WSDL. Kady element operation zawiera kombinacj elementw input i output (jeli zawiera elementy output, to moe take zawiera elementy fault). Kolejno tych elementw definiuje wzorzec wymiany komunikatw (MEP) obsugiwany przez dan operacj.

Jeli na przykad po elemencie input nastpuje element output, to definiowana jest operacja danieodpowied. Jeli po elemencie output wystpuje element input, to definiowana jest operacja odwrotna, nazywana operacj zaproszenie-odpowied. Operacja zawierajca wycznie element input to operacja jednokierunkowa, a operacja zawierajca jedynie element output jest operacj powiadomienia. W tabeli 2. opisano cztery podstawowe wzorce komunikacji (MEP) zdefiniowane przez WSDL.

Tabela 2. Wzorce wymiany komunikatw MEP MEP jednokierunkowy danie-odpowied zaproszenie-odpowied powiadomienie Opis punkt kocowy otrzymuje komunikat punkt kocowy otrzymuje komunikat i wysya skorelowany komunikat punkt kocowy wysya komunikat i otrzymuje skorelowany komunikat punkt kocowy wysya komunikat

Elementy input, output i fault, stosowane w elemencie operation, musz odwoywa si do definicji komunikatu (przez podanie nazwy). W poniszym przykadzie zdefiniowano element portType o nazwie MathInterface, skadajcy si czterech operacji matematycznych: Add, Subtract, Multiply oraz Divide. <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > ... <portType name="MathInterface"> <operation name="Add"> <input message="y:AddMessage"/> <output message="y:AddResponseMessage"/> </operation> <operation name="Subtract"> <input message="y:SubtractMessage"/> <output message="y:SubtractResponseMessage"/> </operation> <operation name="Multiply"> <input message="y:MultiplyMessage"/> <output message="y:MultiplyResponseMessage"/> </operation> <operation name="Divide"> <input message="y:DivideMessage"/> <output message="y:DivideResponseMessage"/> </operation> </portType> ... </definitions> Element portType nadal pozostaje definicj abstrakcyjn, poniewa nie wiadomo, jak komunikaty bd reprezentowane, dopki nie zastosuje si wizania.

Elementy binding
Element binding opisuje szczegy dotyczce stosowania konkretnego elementu portType z wybranym protokoem. Dla kadej operacji w opisywanym elemencie portType, element binding zawiera element operation, a take kilka elementw rozszerzenia. Podstawowa struktura elementu binding jest nastpujca (znak * oznacza dowoln liczb powtrze, a znak ? oznacza wystpienie opcjonalne): <wsdl:definitions .... > <wsdl:binding name="nmtoken" type="qname"> * <-- element rozszerzenia zapewniajcy szczegy wizania --> * <wsdl:operation name="nmtoken"> * <-- element rozszerzenia opisujcy szczegy operacji --> * <wsdl:input name="nmtoken"? > ? <-- element rozszerzenia opisujcy szczegy zawartoci --> </wsdl:input> <wsdl:output name="nmtoken"? > ? <-- element rozszerzenia opisujcy szczegy zawartoci --> </wsdl:output> <wsdl:fault name="nmtoken"> * <-- element rozszerzenia opisujcy szczegy zawartoci --> </wsdl:fault> </wsdl:operation> </wsdl:binding> </wsdl:definitions> Wizaniu naley nada unikaln nazw, aby mona byo odwoywa si do niego z innych czci definicji WSDL. W definicji wizania naley take okreli (za pomoc atrybutu type), ktry element portType jest opisywany. Poniej zaprezentowano przykadowe wizanie o nazwie MathSoapHttpBinding, opisujce szczegy elementu portType o nazwie MathInterface: <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > ... <binding name="MathSoapHttpBinding" type="y:MathInterface"> ... <-- element rozszerzenia --> <operation name="Add"> ... <-- element rozszerzenia --> <input> ... <-- element rozszerzenia --> </input> <output> ... <-- element rozszerzenia --> </output> </operation> ... </binding> ... </definitions>

Element binding jest elementem oglnym. Element ten po prostu definiuje podstawy suce do opisu szczegw wizania. Waciwe szczegy wizania s okrelane dziki elementom rozszerze. Taka konstrukcja umoliwia WSDL ewoluowanie, poniewa w miejscach predefiniowanych moe by zastosowany dowolny element. Specyfikacja WSDL zawiera elementy wiza do opisywania wiza SOAP, chocia znajduj si one w innej przestrzeni nazw. W zamieszczonym poniej przykadzie przedstawiono wizanie SOAP do HTTP dla elementu portType o nazwie MathInterface. <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > ... <binding name="MathSoapHttpBinding" type="y:MathInterface"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="Add"> <soap:operation soapAction="http://example.org/math/#Add"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> ... </binding> ... </definitions> Element soap:binding sygnalizuje, e jest to wizanie w standardzie SOAP 1.1. Atrybut style elementu informuje o domylnym sposobie wykorzystania usugi (moliwe wartoci to document i rpc), a atrybut transport o wymaganym protokole transportowym (w tym przypadku HTTP). Element soap:operation definiuje warto nagwka HTTP SOAPAction dla kadej operacji. Natomiast atrybut use elementu soap:body okrela sposb kodowania poszczeglnych frahmentw komunikatu wewntrz elementu body (moliwe wartoci literal i encoded). W ten sposb mona okreli take inne ustawienia dotyczce wizania.

Uycie stylu document oznacza, e w treci komunikatu jest przesyany dokument XML, a czci komunikatu okrelaj elementy XML w nim umieszczane. Styl rpc oznacza, e tre komunikatu zawiera reprezentacj wywoania metody w postaci XML, a czci komunikatu reprezentuj parametry metody.

Atrybut use okrela, ktry sposb kodowania powinien zosta uyty do tumaczenia abstrakcyjnych czci komunikatu na konkretn reprezentacj. W przypadku uycia wartoci encoded, definicje abstrakcyjne s tumaczone na konkretny format przy zastosowaniu regu kodowania SOAP. Jeli uyta zostanie warto literal, abstrakcyjne definicje typw staj si definicjami konkretnymi (s definicjami dosownymi). W tym

przypadku aby ustali kocowy format komunikatu mona po prostu sprawdzi definicje typw w schemacie XML. W przypadku zdefiniowanej wyej operacji Add, wizanie typu document/literal wyglda nastpujco: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" > <SOAP-ENV:Body> <m:Add xmlns:m="http://example.org/math/types/"> <x>3.14159265358979</x> <y>3.14159265358979</y> </m:Add> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Zauwamy, e element body zawiera instancj elementu Add, zdefiniowan w schemacie wanie dlatego wizanie document/literal jest tak interesujce. Teraz przyjrzyjmy si, jak bdzie wyglda komunikat, jeli zostanie zastosowane wizanie rpc/encoded. Zamieszczony poniej fragment kodu zawiera zweryfikowane wizanie rpc/encoded, a w definicji komunikatw zosta zastosowany atrybut type zamiast atrybutu element: ... <message name="AddMessage"> <part name="parameter" type="ns:MathInput"/> </message> <message name="AddResponseMessage"> <part name="parameter" type="ns:MathOutput"/> </message> ... <binding name="MathSoapHttpBinding" type="y:MathInterface"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="Add"> <soap:operation soapAction="http://example.org/math/#Add"/> <input> <soap:body use="encoded"/> </input> <output> <soap:body use="encoded"/> </output> </operation> ... </binding> Z takimi definicjami operacja Add wyglda zupenie inaczej: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:m0="http://example.org/math/types/" > <SOAP-ENV:Body> <m:Add xmlns:m="http://example.org/math/">

<parameter xsi:type="m0:MathInput"> <x xsi:type="xsd:double">3.14159265358979</x> <y xsi:type="xsd:double">3.14159265358979</y> </parameter> </m:Add> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Stosowanie dosownych definicji jest duo bardziej przejrzyste i atwiejsze do implementowania w narzdziach. Stosowanie regu kodowania doprowadzio do znacznych problemw z interoperacyjnoci pomidzy poszczeglnymi narzdziami. Doprowadzio take do tak dziwnych sytuacji, jak niemoliwo sprawdzenia kocowego komunikatu z oryginaln definicj schematu (ze wzgldu na abstrakcyjn, a nie prawdziw reprezentacj komunikatu). Aby temu zapobiec i zwikszy interoperacyjno, WS-I w podstawowym profilu 1.0 zabrania stosowania wszelkich metod kodowania, wcznie z kodowaniem SOAP. Oznacza to, e w celu zachowania zgodnoci z podstawowym profilem 1.0 naley stosowa wycznie definicje dosowne. Wicej informacji na ten temat mona znale w artykule The Argument Against SOAP Encoding.

Najpopularniejsz kombinacj wartoci dla atrybutw style oraz use s odpowiednio wartoci dokument oraz literal (zastosowaem je w pierwszym z powyszych przykadw). S to wartoci domylne w wikszoci obecnie stosowanych zestaww narzdzi i sprawiaj najmniej problemw z interoperacyjnoci. Drugim najczciej stosowanym poczeniem wartoci jest odpowiednip RPC oraz encoded, ale ze wzgldu na to, e WS-I zakazao stosowania wartoci encoded, z opcji tej nie naley ju korzysta. Jedyn inn moliw kombinacj jest RPC oraz literal. W artykule RPC/Literal and Freedom of Choice omwiono kombinacj wartoci rpc/literal i podsumowano, dlaczego dokument/literal jest kombinacj lepsz.

Oprcz wiza SOAP, specyfikacja WSDL definiuje jeszcze dwa inne wizania dla HTTP GET i POST oraz dla MIME. Wicej na ten temat mona dowiedzie si z przykadw zamieszczonych w specyfikacji.

Elementy service
Element service definiuje kolekcj elementw port i endpoint, ktre udostpniaj poszczeglne wizania w sieci. Podstawowa struktura elementu service jest nastpujca: <definitions .... > <service .... > * <port name="nmtoken" binding="qname"> * <-- element rozszerzenia definiuje szczegowy adres --> </port> </service> </definitions> Kademu portowi trzeba nada nazw i przypisa do niego wizanie (atrybut binding). Nastpnie wewntrz elementu port naley uy elementu rozszerzenia, aby zdefiniowa adres wizania. W zamieszczonym poniej przykadzie zdefiniowano usug o nazwie MathService, ktra udostpnia wizanie MathSoapHttpBinding pod adresem http://localhost/math/math.asmx: <definitions xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/" > ... <service name="MathService"> <port name="MathEndpoint" binding="y:MathSoapHttpBinding"> <soap:address location="http://localhost/math/math.asmx"/> </port> </service> </definitions> Element service jest ostatnim elementem w definicji WSDL. Na podstawie takiej definicji mona teraz w prosty sposb wygenerowa kod implementujcy peny interfejs w wybranym jzyku programowania. Pen definicj WSDL, ktrej fragmenty wykorzystywaem w przykadach, zamieciem w Dodatku A.

Edytory WSDL
Przedstawione w przykadach definicje WSDL utworzyem za pomoc narzdzia XML Spy 5.0 (ilustracja 6). Obecnie istnieje kilka edytorw, dziki ktrym tworzenie plikw WSDL jest niemal przyjemnoci. Z opiniami na temat rnych narzdzi mona zapozna si w jednym z moich wczeniejszych artykuw w magazynie MSDN Magazine.

Ilustracja 6. Definicja WSDL usugi MathService wygenerowana za pomoc XML Spy 5.0

Gdzie jestemy?
WSDL rozszerza funkcjonalno schematw XML o moliwo penego opisania usugi XML Web Service za pomoc terminw takich jak komunikaty, operacje, interfejsy (portType), wizania i punkty kocowe usugi. Definicje WSDL umoliwiaj generowanie kodu implementujcego dany interfejs zarwno dla klienta jak i dla serwera. Dziki temu usugi XML Web Service staj si powszechnie dostpne. WSDL ma znacznie wicej moliwoci ni te, ktre zostay opisane w tym artykule. Jeli jednak zaley nam przede wszystkim na interoperacyjnoci, powinnimy przestrzega wytycznych profilu podstawowego WS-I Basic Profile 1.0, ktre zostay tu omwione.

Bibliografia
Essential XML Quick Reference: A Programmer's Reference to XML, XPath, XSLT, XML Schema, SOAP, and More, Aaron Skonnard and Martin Gudgin, DevelopMentor Books, Addison-Wesley Pub. Co., 2001

Web Services Description Language (WSDL) 1.1

Web Services Description Language (WSDL) Version 1.2 Part 1: Core Language

WS-I Basic Profile Version 1.0

XML Schema Part 1: Structures

XML Schema Part 2: Datatypes

Dodatek A WSDL
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:y="http://example.org/math/" xmlns:ns="http://example.org/math/types/" targetNamespace="http://example.org/math/"> <types> <xs:schema targetNamespace="http://example.org/math/types/" xmlns="http://example.org/math/types/" elementFormDefault="unqualified" attributeFormDefault="unqualified"> <xs:complexType name="MathInput"> <xs:sequence> <xs:element name="x" type="xs:double"/> <xs:element name="y" type="xs:double"/> </xs:sequence> </xs:complexType> <xs:complexType name="MathOutput"> <xs:sequence> <xs:element name="result" type="xs:double"/> </xs:sequence> </xs:complexType> <xs:element name="Add" type="MathInput"/> <xs:element name="AddResponse" type="MathOutput"/> <xs:element name="Subtract" type="MathInput"/> <xs:element name="SubtractResponse" type="MathOutput"/> <xs:element name="Multiply" type="MathInput"/> <xs:element name="MultiplyResponse" type="MathOutput"/> <xs:element name="Divide" type="MathInput"/> <xs:element name="DivideResponse" type="MathOutput"/> </xs:schema> </types> <message name="AddMessage"> <part name="parameters" element="ns:Add"/> </message>

<message name="AddResponseMessage"> <part name="parameters" element="ns:AddResponse"/> </message> <message name="SubtractMessage"> <part name="parameters" element="ns:Subtract"/> </message> <message name="SubtractResponseMessage"> <part name="parameters" element="ns:SubtractResponse"/> </message> <message name="MultiplyMessage"> <part name="parameters" element="ns:Multiply"/> </message> <message name="MultiplyResponseMessage"> <part name="parameters" element="ns:MultiplyResponse"/> </message> <message name="DivideMessage"> <part name="parameters" element="ns:Divide"/> </message> <message name="DivideResponseMessage"> <part name="parameters" element="ns:DivideResponse"/> </message> <portType name="MathInterface"> <operation name="Add"> <input message="y:AddMessage"/> <output message="y:AddResponseMessage"/> </operation> <operation name="Subtract"> <input message="y:SubtractMessage"/> <output message="y:SubtractResponseMessage"/> </operation> <operation name="Multiply"> <input message="y:MultiplyMessage"/> <output message="y:MultiplyResponseMessage"/> </operation> <operation name="Divide"> <input message="y:DivideMessage"/> <output message="y:DivideResponseMessage"/> </operation> </portType> <binding name="MathSoapHttpBinding" type="y:MathInterface"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="Add"> <soap:operation soapAction="http://example.org/math/#Add"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> <operation name="Subtract"> <soap:operation soapAction="http://example.org/math/#Subtract"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/>

</output> </operation> <operation name="Multiply"> <soap:operation soapAction="http://example.org/math/#Multiply"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> <operation name="Divide"> <soap:operation soapAction="http://example.org/math/#Divide"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="MathService"> <port name="MathEndpoint" binding="y:MathSoapHttpBinding"> <soap:address location="http://localhost/math/math.asmx"/> </port> </service> </definitions>