Úvod
Ukážeme si, ako je možné pomocou Eclipse Web Developer Tools rýchlo vytvoriť WSDL pre webovú službu spolu so schémou pre dokumenty, čím si urobíme výborný základ pre interoperabilitu medzi platformami. Čaká nás tvorba XML dokumentov, písanie XML schém a pozeranie videa s klikaním WSDL v Eclipse!
Inštalácia
- Doinštalujte modul Eclipse Java Web Developer Tools
Webová služba na základe WSDL
Ustanovenie vstupno-výstupných dokumentov
Pri návrhu webových služieb založených na kontrakte (contract-based) sa často vychádza z dokumentov, ktoré sa posielajú do príslušných operácií, resp. sú ich výsledkom.
Ak by sme chceli navrhovať metódu pre prekladový slovník, môžeme do služby poslať nasledovný dokument:
<word lang="sk">pes</dog>
Keďže jazyk je metainformácia (informácia o slove pes), je lepšie ho uviesť do XML atribútu než do samostatného elementu.
Výstupom prekladovej služby by mohol byť dokument s viacerými slovami:
<words lang="en">
<word>dog</word>
<word>hound</word>
</word>
Služba je navyše dostatočne flexibilná, aby mohla perspektívne vracať preklady z ľubovoľného jazyka do ľubovoľného iného.
Návrh XML schémy
Ak máme ujasnené dokumenty, môžeme navrhovať schému. V Eclipse môžeme zvoliť New | File | XML | XML Schema a vytvoriť súbor schema.xsd
.
Vygeneruje sa štandardná prázdna schéma:
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.org/schema"
xmlns:tns="http://www.example.org/schema"
elementFormDefault="qualified">
</schema>
Túto schému môžeme upraviť do klasickejšej podoby a elementy, ktoré v nej definujeme, asociovať s menným priestorom urn:X-kopr
:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:X-kopr"
xmlns="urn:X-kopr"
elementFormDefault="qualified">
</xsd:schema>
Menný priestor urn:X-kopr
je experimentálny menný priestor v zmysle špecifikácie RFC3406.
Schéma pre element pre vstup
Ak chceme v XML schéme deklarovať element s textom a jedným atribútom, použime vzor prevzatý zo Zvon.org:
<xsd:element name="word">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="lang" type="xsd:string" use="required" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
Deklarujeme element word
, ktorý obsahuje jednoduchý obsah cez simpleContent
s dátovým typom reťazec (xsd:string
). Tento dátový typ obohatíme cez extension
o nutnosť (use="required"
) vlastniť atribút lang
typu xsd:string
.
Schéma pre element pre výstup
Element pre výstupné dokumenty bude o niečo jednoduchší. Keďže má obsahovať podelementy, v schéme ho deklarujeme cez complexType
a sekvenciu (sequence
). Jednotlivé elementy word
obsahujú len text, čiže reťazce string
.
Keďže slová sa majú opakovať (viacero elementov word
za sebou), nastavíme maximálny výskyt (maxOccurs
) na neohraničený (unbounded
). Zároveň môžeme zaviesť situáciu, keď sa pre slovo nenájdu žiadne preklady a vrátiť prázdny zoznam slov, čiže umožniť aj situáciu, keď sa element word
nebude vyskytovať v rodičovi words
ani raz: dosiahneme to nulovým minimálnym výskytom (minOccurs="0"
˙):
Na záver zavedieme do schémy povinný atribút lang
s jazykom v podobnom duchu, ako sme to robili pre atribút jedného slova vo vstupnom dokumente.
<xsd:element name="words">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="word"
type="xsd:string"
minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="lang" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
Výsledná schéma
Výsledná schéma môže vyzerať nasledovne:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:X-kopr" xmlns="urn:X-kopr" elementFormDefault="qualified">
<xsd:element name="word">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="lang" type="xsd:string" use="required" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="words">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="word"
type="xsd:string"
minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="lang" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
</xsd:schema>
Návrh WSDL
Ak máme ujasnenú schému, môžeme navrhovať WSDL. V Eclipse môžeme zvoliť New | File | Web Services | WSDL File a vytvoriť súbor words.wsdl
.
V dialógu potrebujeme vyplniť štyri základné veci:
- cieľový menný priestor: reprezentuje jednoznačný menný priestor pre deklarácie v tomto WSDL dokumente. Podľa obyčaje je reprezentovaný URL adresou, na ktorej možno nájsť príslušný WSDL súbor.
- unikátnosť menného priestoru (v celom šírom svete…): pomenovanie URL adresou ju vie automaticky zabezpečiť
- potenciálnu možnosť navštíviť URL adresu a získať z nej autoritatívnu (kanonickú) podobu WSDL súboru. Toto však nie je bezpodmienečne nutné, ani vyžadované, a nie je vôbec vylúčené, že použijeme menný priestor, ktorý nie je URL adresou. Koniec-koncov, to sme robili pri mennom priestore pre XML schému, kde sme využili
urn:X-kopr
.
- prefix menného priestoru:
- vzhľadom na ťažkopádnosť pomenovaní menných priestorov možno využiť skratkový “alias”, alebo prefix. V tomto prípade môžeme radostne použiť prefix
kopr
(alebo akýkoľvek iný).
- vzhľadom na ťažkopádnosť pomenovaní menných priestorov možno využiť skratkový “alias”, alebo prefix. V tomto prípade môžeme radostne použiť prefix
- štýl webovej služby:
- ak chceme zachovať portabilitu a interop, využime jedinú možnosť: document/literal.
- protokol:
- využime možnosť SOAP.
Z Eclipsu vypadne obrovské automatické WSDL. Dávame ho len na ukážku, pretože si ho v ďalších pasážach postupne rozoberieme a primerane upravíme. Urýchliť pochopenie môže samostatný článok “Od WSDL k webovej službe”.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions
xmlns:kopr="urn:kopr"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
name="words"
targetNamespace="urn:kopr">
<wsdl:types>
<xsd:schema targetNamespace="urn:kopr">
<xsd:element name="NewOperation">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="in" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="NewOperationResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="out" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
<wsdl:message name="NewOperationRequest">
<wsdl:part element="kopr:NewOperation" name="parameters"/>
</wsdl:message>
<wsdl:message name="NewOperationResponse">
<wsdl:part element="kopr:NewOperationResponse" name="parameters"/>
</wsdl:message>
<wsdl:portType name="words">
<wsdl:operation name="NewOperation">
<wsdl:input message="kopr:NewOperationRequest"/>
<wsdl:output message="kopr:NewOperationResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="wordsSOAP" type="kopr:words">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="NewOperation">
<soap:operation soapAction="urn:kopr/NewOperation"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="words">
<wsdl:port binding="kopr:wordsSOAP" name="wordsSOAP">
<soap:address location="http://www.example.org/"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Vzájomné prepojenie vidieť na diagrame:
Ak si prepneme zobrazenie na grafické, uvidíme vo finále prepojenie a významy jednotlivých blokov:
Grafický editor v Eclipse
Demonštrácia použitia WSDL editora v Eclipse, vytvorenie ukážkového WSDL na zelenej lúke a prepojenie s existujúcou schémou je znázornená v samostatnom videu.
Literatúra
- Od WSDL k webovej službe, článok vo Wiki o budovaní webovej služby na základe WSDL.
- WSDL Essentials, Chapter 6 in Web Services Essentials [Distributed Applications with XML-RPC, SOAP, UDDI & WSDL], O’Reilly 2002.