OIOWSDL Vejledning for udvikling og anvendelse af OIOWSDL

Transkript

1

2 OIOWSDL Vejledning for udvikling og anvendelse af OIOWSDL Publikationen kan hentes på It- & Telestyrelsens Hjemmeside: Udgivet af: IT- & Telestyrelsen i samarbejde med Devoteam og Trifork IT- & Telestyrelsen Holsteinsgade København Ø Telefon: Fax:

3 OIOWSDL Vejledning for udvikling og anvendelse af OIOWSDL IT- & Telestyrelsen januar 2008

4 Indhold > Introduktion 6 Målgruppe 6 Mål 6 Hvad er OIOWSDL? 8 Arkitekturelementer 8 Kontraktbaserede services 8 Infostrukturbasen 10 Retningslinier for OIOWSDL 10 [DEF-1] Document literal binding 11 [DEF-2] Krav til datadefinitioner 11 [DEF-3] Krav til message-definitioner 12 [NAV-1] Krav til navngivning af filer, namespaces og elementer 12 [DOK-1] Dokumentation 15 Hvordan fremstilles OIOWSDL? 17 Fremgangsmåde for udvikling af OIOWSDL 17 Eksempel 19 Trin 1: Modellering af datadefinitioner 20 Trin 2: Modellering af beskeddefinitioner 20 Trin 3: Modellering af grænseflade 21 Trin 4: Generér kodeskabelon 22 Hvordan anvendes OIOWSDL? (Værktøjsunderstøttelse) 23 Generelle problemer med imports 24 Løsninger 25 BEA WebLogic Introduktion 26 Klientstubbe 27 Service-skeletons 28 RAD 6.0.0, RAD 6.0.1, RAD Introduktion 29 Klientstubbe 30 Service-skeleton 30 Axis Introduktion 31 Klientstubbe 31 Service-skeleton 32 Axis2 32 Introduktion 32 Klient 32 Service-skeleton 32 Eclipse 33 Introduktion 33 Klientstubbe 33 Service-skeleton 33.NET Introduktion 33 Klientstubbe 34 Service-skeleton 34.Net Introduktion 35

5 Klientstubbe 35 Service-skeleton 36.NET Introduktion 36 Klientstubbe 37 Service-skeleton 38 Ruby 38 Introduktion 38 Klientstubbe 38 Service-skeleton 39 Appendiks: FAQ 40 Appendiks: Referencer 42 Appendiks: Checkliste 43 Appendiks: Begrebsdefinitioner 44 Appendiks: XSD schema er for eksempel 45 DKMA_DosageFormText.xsd 45 DKMA_DrugIdentifier.xsd 46 DKMA_DrugName.xsd 47 DKMA_DrugStrengthText.xsd 48 DKMA_DrugStructure.xsd 49 DKMA_MedicineChestItemChoiceStructure.xs d 50 DKMA_MedicineChestItemDate.xsd 51 DKMA_MedicineChestItemIdentifier.xsd 52 DKMA_MedicineChestItemStructure.xsd 53 DKMA_MedicineChestItemVersionIdentifier.xs d 54 DKMA_MedicineChestRemarkText.xsd 55 DKMA_MedicineChestStructure.xsd 56 DKMA_MedicineChestStructureGet.xsd 57 DKMA_OwnerTypeText.xsd 58 Appendiks: WSDL for eksempel 59 Appendiks: WSDL med indlejrede typer 60

6 Introduktion > Nærværende dokument indeholder en beskrivelse af OIOWSDL samt vejledninger i, hvordan OIOWSDL skal opbygges og anvendes. Denne struktur vil være afspejlet i dokumentets opbygning. OIOWSDL er en sammenstilling af OIO (Offentlig Information Online) og WSDL (Web Service Description Language). Formålet for OIOWSDL er at fremme Web Service interoperabilitet i Det Digitale Danmark og at ensrette måden at lave OIOWSDL-dokumenter på. Denne vejledning skal medvirke til ovenstående ved at gøre det lettere og overskueligt for serviceaftagere at anvende og for serviceudbydere at frembringe OIOWSDL-dokumenter. Denne vejledning fokuserer entydigt på udviklingen og anvendelsen af WSDLdokumenter i en OIO-kontekst og er ikke en introduktion til WSDL eller andre XML relaterede teknologier/standarder. Vejledningen er baseret på reglerne for WS-I Basic Profile Version 1.1 med enkelte skærpelser. WS-I Basic Profile 1.1 er baseret på WSDL 1.1. Målgruppe Målgrupperne for denne vejledning er de virksomheder, der har behov for: 1) At udbyde Web Services for omverdenen - offentlige myndigheder og samarbejdspartnere. 2) At aftage allerede udviklede og tilgængelige Web Services. Virksomhederne er i denne forbindelse offentlige myndigheder og private virksomheder og deres leverandører af it-løsninger. OIOWSDL-dokumenterne er tilgængelige gennem servicekataloget. Servicekataloget indeholder således faciliteter, så serviceudbyderen kan publicere OIOWSDL-dokumenter, og serviceaftageren kan finde OIOWSDLdokumenter. Figur 1 Rollerne relateret til WSDL-brug Mål Målsætningen for denne vejledning er: At fremme udviklingen af interoperable webservices 6

7 At standardisere brugen af WDSL i OIO regi At lette frembringelsen og brugen af WSDL i OIO regi At lette anvendelsen af OIOXML i arbejdet med WSDL Det forudsættes, at man inden udviklingen af et OIOWSDL-dokument har identificeret servicen, dens operationer, og fundet relevante datastrukturer til operationernes snitflader. 7

8 Hvad er OIOWSDL? > OIOWSDL er WSDL-dokumenter, der følger retningslinierne beskrevet i dette dokument. Retningslinierne for OIOWSDL-dokumenter er, som beskrevet i introduktionen, til for at understøtte Web Service interoperabilitet i det Digitale Danmark. Retningslinierne skal således være med til at udvikle WSDLdokumenter med ensartede strukturer opbygninger, navnepolitikker m.v. Arkitekturelementer OIOWSDL-dokumenterne indgår som et element i OIO Web Service Arkitekturen (OWSA), som er skitseret i Fejl! Henvisningskilde ikke fundet. herunder. Figur 2 illustrerer kun udvalgte arkitekturelementer, som indgår OWSA 1. Figur 2 OWSA grundelementer I dette dokument er der fokuseret på de tre grundelementer fra OWSA: En serviceudbyder, som enten selv eller gennem en leverandør har udviklet en eller flere services og fået dem publiceret i Infostrukturbasen (ISB). En serviceaftager, som finder en relevant service i servicekataloget med henblik på at anvende den. Servicekatalog, som indeholder XML datadefinitioner (XSD er) og web service definitioner (WSDL-dokumenter). Det OIOXML, der udveksles mellem serviceudbyder og serviceaftager, er defineret i OIOWSDL-dokumentet i form af en eller flere meddelelsesdefinitioner (XSD). Kontraktbaserede services En Web Service er beskrevet i en servicekontrakt, som udveksles mellem serviceleverandøren og de aktuelle serviceaftagere. Servicekontrakten består af to dele: 1 En mere detaljeret beskrivelse af OWSA og de sikkerhedsmæssige aspekter er beskrevet i ITST s OWSA model Transportbaseret sikkerhed ver. 1.0 publiceret 5. december

9 Den tekniske, en WSDL, som beskriver eksempelvis, hvor en service findes, hvilke operationer den har samt deres input og output. Den juridiske, en Service Level Agreement (SLA), som eksempelvis beskriver tilgængeligheden for servicen, forbrugsaftale samt kvalitet for servicen. Figur 3 herunder illustrerer de to dele af kontrakten mellem serviceudbyder og serviceaftagerne. Figur 3 Servicekontrakt for en Web Service Serviceanvendelse sker på grundlag af kontrakten (både WSDL og SLA). WSDL-dokumentet er en præcis beskrivelse af servicens interfaces, der indeholder en definition af dels den information, servicen har ansvaret for og manipulerer med, dels den adfærd servicen har. WSDL-dokumentet indeholder også en specificering af, hvordan servicen fysisk skal findes og anvendes samt eventuelle andre infrastrukturmæssige krav. SLA en beskriver de servicekvaliteter, som serviceleverandøren skal leve op til, og dermed også hvilke kvaliteter en serviceaftager kan forvente. Alle aktører er dermed bekendt med deres præcise forpligtigelser, når en service leveres eller anvendes. Dette princip kan være medvirkende til at forbedre kvaliteten i it-løsningerne, da risikoen for fejl og misforståelser bliver reduceret. I praksis stiller dette relativt store krav til beskrivelse, vedligeholdelse og versionering af hele servicekontrakten 2. Dette dokument vedrører kun den del af servicekontrakten, der indeholder WSDL-dokumentet, dvs. den tekniske del af kontrakten. 2 Se OIO Standardaftale om web services: 9

10 Infostrukturbasen Servicekataloget er et vigtigt element i den ovenfor skitserede arkitektur. For at få brugt eller genbrugt de services, der udvikles, skal det være let at publicere og finde services. Der findes allerede en velfungerende infrastruktur til opbevaring af OIOXML schemaer - Infostrukturbasen. Grundet den tætte sammenhæng med OIOXML schemaer er Infostrukturbasen et oplagt sted at opbevare og udstille OIOWSDL-dokumenter. Retningslinier for OIOWSDL En web service består af et eller flere interfaces, der hver kan definere en række operationer. WSDL-dokumentet beskriver disse interfaces. Servicen tilgås via beskeder (messages), som udveksles mellem serviceaftager og -udbyder via en specifik adresse (URI). Koblingen mellem adressen og interfacet (binding) definerer hvilken protokol der anvendes. For OIOWSDL bindings kan udelukkende anvendes HTTP og HTTPS. Figur 4 illustrerer grafisk et WSDL-dokument. Figur 4 - Grafisk illustration af et WSDL-dokument <!-- definition af WSDL struktur --> <definitions xmlns=" <!-- abstrakte definitioner --> <types>... <message>... <porttype>... <!-- konkrete definitioner --> <binding>... <service>... </definition> Figur 5 - Elementer i et WSDL-dokument Figur 5 skitserer elementerne i et WSDL-dokument. De fem elementer er yderligere beskrevet I Tabel 1. 10

11 Elementnavn Types Message porttype Binding Service Beskrivelse En container for abstrakte datadefinitioner beskrevet ved hjælp XML schema En definition af en abstrakt besked, der kan bestå af flere forskellige datadefinitioner En abstrakt samling af operationer, der supporters af et eller flere interfaces. Operationer defineres ved at beskrive forespørgsels- og svarbeskeder En konkret specifikation af protokol og dataformat for en bestemt porttype En samling af relaterede interfaces, hvor ét interface er defineret ved en kombination af en binding og en adresse (URI) Tabel 1 - Elementer i et WSDL-dokument Forbindelsen mellem OIOXML og OIOWSDL opbygges i <type>-elementet. Her inkluderes (<include>) OIOXML-skemaer fra ISB en i modsætning til servicens egne typer, som oftest indlejres, da de ikke nødvendigvis kan genbruges i andre sammenhænge. OIOWSDL-dokumenter skal overordnet følge reglerne for WS-I Basic Profile Version 1.1 3, men for at opnå den ønskede interoperabilitet i Det Digitale Danmark er reglerne tilpasset OIO-konteksten. Dette er beskrevet i nærværende kapitel. [DEF-1] Document literal binding For at en message kan valideres udelukkende ved schema-validering, skærpes R2705 fra WS-I Basic Profile fra MUST be a rpc-literal binding or a document-binding til MUST be a document-literal binding. [DEF-2] Krav til datadefinitioner Datadefinitioner er XML schemaer, som definerer databærende elementer og deres indbyrdes relationer. Datadefinitioner skal som udgangspunkt baseres på OIOXML standarden. Pt., primo 2007, findes der ca schemaer i ISB en; hvilke kan anvendes til udvikling af OIOWSDL-dokumenter. Selvom der allerede findes OIOXML schemaer, dækker de endnu ikke alle områder og segmenter inden for den offentlige sektor. Før dette er tilfældet, vil der ikke kunne stilles krav om, at samtlige datadefinitioner skal være OIOXML

12 godkendte. Indtil da kan også non-oioxml schemaer anvendes. Disse schemaer skal opfylde OIOXML Navngivnings- og Designregler (NDR), men behøver ikke at være godkendte. [DEF-3] Krav til message-definitioner Message-definitioner beskriver de beskeder, der sendes mellem serviceudbyder og serviceaftager. En message-definition er et XML schema, som samler de datadefinitioner, der opbygger en konkret besked. Det forventes, at messages, der indgår i et OIOWSDL-dokument, ikke vil blive genbrugt i andre OIOWSDL-dokumenter. Derfor stilles der ikke krav om, at message-definitioner, der indgår i et OIOWSDL-dokument, skal være OIOgodkendte eller på sigt skal godkendes. [NAV-1] Krav til navngivning af filer, namespaces og elementer Overordnet bør NDR benyttes i størst muligt omfang; eksempelvis entalsform af navne, forkortelser og akronymer, bindeord, anvendelse af tegn i navne, anvendelse af danske tegn (æ, ø, å). Mht. sprogvalg følges NDR, dvs. det valgte sprog (dansk eller engelsk) skal anvendes gennemført, og engelsk foretrækkes. Generelt anbefales det ikke at benytte underscore (_), punktum (.) eller bindestreg (-) i opbygningen af navne, men i stedet at benytte UpperCamelCase. Det betyder, at navnet skal begynde med et stort bogstav, herefter begynder hvert nyt ord med et stort bogstav. Hvis en forkortelse består udelukkende af store bogstaver, som f.eks. DK, bør det efterfølgende ord starte med et lille bogstav. [NAV-1a] Navngivning af OIOWSDL-dokumenter I lighed med NDR for OIOXML anbefales det, at navngive sine OIOWSDLdokumenter som følger: <namespace-prefix med store bogstaver>+ _ +<servicenavn>+.wsdl Et OIOWSDL-dokument indeholdende beskrivelse af en service med navnet MedicineChest med prefix DKMA vil således få navnet DKMA_MedicineChest.wsdl

13 [NAV-1b] Navngivning af OIOWSDL namespace Navngivning af namespaces for OIOWSDL-dokumentet bør følge de generelle OIO retningslinier, som er beskrevet i NDR. Dog er der en ændring i forhold til det anbefalede i NDR, nemlig brug af punktum til adskillelse af visse understrukturer samt dato <domæne> + /xml.wsdl/ + <årstal> +. + <måned> +. + <dag> + / Et namespace for OIOWSDL under dkma.dk domænet kan eksempelvis få namespace <definitions xmlns=" targetnamespace=" xmlns:dkma=" xmlns:xsd=" xmlns:tns=" xmlns:soap=" Figur 6 Eksempel på navngivning af namespace [NAV-1c] Navngivning af <message> Der opereres i OIOWSDL regi med to operationstyper: Request-response operationen kan modtage en forespørgsel og vil returnere et svar. One-way operationen kan modtage en meddelelse, men vil ikke returnere et svar. Request-response typen er dog den mest anvendte. En meddelelse (message) bør navngives efter den operation, meddelelsen anvendes i sammenhæng med. Hvis operationen er en request- eller responseoperation, skal navnet efterfølges af hhv. Request eller Response. Hvis operationen er en one-way operation, navngives meddelelsen udelukkende af operationens navn. <operationsnavn> + Request Response To meddelelser, der forespørger hhv. returnerer en samling af medicinoplysninger, kan eksempelvis se ud som følger. Forespørgsel: MedicineChestStructureGetRequest 5 Navngivning af namespace ved brug af punktum mellem xml og wsdl, samt til opdeling af dato følger ikke NRD 3.0, men er en senere anbefaling fra Adam Arndt fra ITST. 13

14 Retursvar: MedicineChestStructureGetResponse Bemærk, at vi har valgt at modellere Fault beskeden direkte på operationsnavnet, hvilket betyder at alle typer af fejl vil retunere samme Fault. Dette er ikke et generelt krav af flere årsager; dels giver det en 1:1 kobling mellem fejltype og operation, og dels vil det i mange situationer bryde med ideen om at mappe Exceptions fra implementationen direkte til Faults. <message name="medicinecheststructuregetrequest">... </message> <message name="medicinecheststructuregetresponse">... </message> <message name="medicinecheststructurefault">... </message> Figur 7 Eksempel på navngivning af message elementet Der er ikke set behov for navngivningsregler af message parts. [NAV-1d] Navngivning af <operation> En operation bør navngives efter ObjektHandling navngivningsmodellen. Der er ingen fast definition af navngivning af handlinger. En operation som returnerer en medicinprofil ved en forespørgsel kan eksempelvis navngives: MedicineChestStructureGet En operation som ændrer på en medicinprofils indhold kan eksempelvis navngives: MedicineChestStructureUpdate. <operation name="medicinecheststructureget"> <input name="medicinecheststructuregetrequest" message="tns:medicinecheststructuregetrequest"/> <output name="medicinecheststructuregetresponse" message="tns:medicinecheststructuregetresponse"/> <fault name="medicinecheststructurefault" message="tns:medicinecheststructurefault"/> </operation> Figur 8 Eksempel på navngivning af operation elementet [NAV-1e] Navngivning af <porttype> (interface) Det anbefales at navngivning af porttype elementet svarer til service navnet. For WSDL-dokumenter med flere interfaces kræves dog en unik navngivning af samtlige interfaces. <servicenavn> + <unik identifikation> En porttype for servicen MedicineChest, der kun indeholder én porttype hedder således blot: MedicineChest. <porttype name="medicinechest">... </porttype> 14

15 Figur 9 Eksempel på navngivning af porttype elementet [NAV-1f] Navngivning af <binding> Det anbefales at navngivning af binding svarer til servicenavnet. Findes der mere end ét binding element i WSDL-dokumentet, kræves dog en unik navngivning af samtlige binding elementer: <servicenavn> + <unik identifikation> [NAV-1g] Navngivning af SOAP-actions SOAP-actions navngives efter følgende model: <namespace> + # + <operationsnavn> Hvor namespace refererer til det targetnamespace, der er angivet i WSDLdokumentet. Eksempel på en SOAP-action kan være: et <binding name="medicinechestbinding" type="tns:medicinechesttype"> <soap:binding transport=" style="document" /> <operation name="medicinecheststructureget"> <soap:operation soapaction= " #MedicineChestStructureGet" style="document" />... </operation> </binding> Figur 10 Eksempel på navngivning af binding elementet [NAV-1h] Navngivning af <service> Det anbefales at benytte et dækkende begreb for navngivning af service elementet, der dækker over servicens operationer. Det frarådes at anvende operationstyper i navnet, eksempelvis medicineget, ligesom det frarådes at anvende ordet service i navngivningen af servicen. Eksempel på det anbefalede: <service name="medicinechest"> Eksempel på ikke anbefalet: <service name="medicinechestgetservice"> <service name="medicinechest">... </service> Figur 11 Eksempel på navngivning af service elementet [DOK-1] Dokumentation Det anbefales, at der tilføjes et <documentation> element til <service>, <operation> og <message> elementerne i WSDL-dokumentet, som tilsammen giver en dækkende beskrivelse af den funktionalitet, som servicen udbyder. 15

16 16 >

17 Hvordan fremstilles OIOWSDL? > Fremstillingen af OIOWSDL filer følger den generelle OIO-tankegang, og bør følge Kontrakt Først udviklingsmetoden (KF-metoden), som beskrives nærmere nedenfor. Filosofien bag OIO er blandt andet at fremme genbrug og deling af datadefinitioner samt at hæve kvaliteten af data. Det skal være muligt at genbruge allerede udviklede elementer for herved at mindske kompleksiteten og antallet af elementer. For at udnytte genbrugsprincippet opstilles der en række regler for navngivning og design af datadefinitionselementer (XSD er) 6, som letter, at datadefinitionselementerne kan kombineres efter behov. Når man ønsker at udstille noget funktionalitet som en Web Service, er det derfor udviklerens ansvar at kombinere sine meddelelsesdefinitioner på baggrund af tilgængelige datadefinitioner, som er udstillet i det fællesoffentlige serviceregister. Er der brug for yderligere datadefinitioner, må disse nødvendigvis udvikles 7. Den beskrevne fremgangsmåde er baseret på, at data- og besked-definitioner er på plads, før den endelige service defineres med interfaces og operationer. Herved opnås muligheden for genbrug af allerede udviklede OIOXML schemaer. Herefter kan koden til den konkrete implementering genereres ud fra WSDL-dokumentet. Fremgangsmåde for udvikling af OIOWSDL KF-metoden kan beskrives ved følgende fire trin: 1. Finde/modellere datadefinitioner: Dette trin definerer, hvilke forretningsdata der skal anvendes i web servicen. Forretningsdata er beskrevet i OIOXML schemaer. De aktuelle OIOXML schemaer hentes eksempelvis i Infostrukturbasen (ISB en). 2. Modellere beskeddefinitioner: Her modelleres de beskeder, der skal udveksles mellem service-aftager og -udbyder. Beskederne beskrives i XML schemaer og anvender datadefinitionerne fra trin 1. I forbindelse med modellering af beskeder skal der også beskrives, hvorledes fejlmeddelelser returneres fra web servicen. Fejl returneres vha. soap fault. 3. Modellere grænsefladen: Dette trin definerer, hvilke operationer web servicen skal tilbyde. Operationerne grupperes i interfaces. Trinet afsluttes eventuelt med at teste den frembragte OIOWSDL-dokument 6 Disse regler findes i ITST s Navngivnings og Design Regler (NDR). 7 Udvikling af datadefinitioner ligger uden for denne vejlednings rammer. Der henvises til ITST s NDR og sektorstandardiseringsarbejde. 17

18 op imod WS-I Basic Profile Version 1.1 med WS-I tools8. Det skal bemærkes, at disse tools ikke kan afgøre, om alle profilens retningslinier er overholdt. 4. Generere kodeskabelon: Ud fra OIOWSDL-dokumentet genereres kodeskabeloner til henholdsvis klient (serviceaftager) og service (serviceudbyder). De fire trin er illustreret i Figur 12, hvor et antal datadefinitioner kombineres til beskeddefinitioner, som anvendes til grænsefladebeskrivelsen. På baggrund af grænsefladebeskrivelsen genereres koden til det aktuelle miljø, hvor Web Servicen implementeres. 8 Se 18

19 Da tadefinitio ner OIOXML Schema OIOXML Schema OIOXML Schema Non OIOXML Schema B eskeddefinitioner XML Schema XML Schema XML Schema G ræ nseflade OIO WSDL K odeskabeloner C# Java Ruby Figur 12 schematisk fremstilling af kontrakt-først fremgangsmåden Eksempel Lad os prøve at se på et realistisk eksempel. I forbindelse med projektet Hjemmesygeplejens adgang til Medicinprofilen under Lægemiddelstyrelsen (se er der udviklet en web service, der tillader registrering af håndkøbsmedicin, der er observeret i medicinskabet hos klienter i forbindelse med besøg fra hjemmeplejen. Dette er tiltænkt som en hjælp til at foregribe evt. interaktion med ordineret medicin. Web servicen gør det muligt at registrere observeret håndkøbsmedicin på klientens CPR-nr. samt at hente tidligere registreringer. Der vises kun operationen til at hente registreringer i det følgende. Det anvendte eksempel er vedlagt i appendiks bagest i dette dokument og kan desuden downloades fra sammen side som nærværende dokument. 19

20 Bemærk at eksemplets schema og WSDL-dokumenter er modificerede i forhold til Medicinprofilens i de tilfælde, hvor der er afvigelser fra nærværende vejledning. Dette er en konsekvens af, at Medicinprofilen er lavet før nærværende vejledning Trin 1: Modellering af datadefinitioner XML schema til web servicen består af en blanding af et antal nyudviklede, NDR kompatible schema er samt et enkelt schema fra OIO kerne-klassen (CPR-nr.). De anvendte schema er kan generelt deles op i: Basale databærende elementer, der via en eller flere simple typer - evt. med restriktioner - repræsenterer en enkelt type, f.eks. DKMA_DosageFormText.xsd (Appendiks: XSD schema er for eksempel). Sammensatte elementer, der kombinerer de basale elementer til kombinationer og sekvenser af elementtyper, f.eks. DKMA_DrugStructure.xsd (Appendiks: XSD schema er for eksempel) Generelt kan man sige, at mere sammensatte elementtyper er mere tilbøjelige til at være specifikke til en given webservice (f.eks. som et resultat, der består af en unik sammensætning af basale typer), mens de basale elementer vil være mere stabile på tværs af webservices. Det kan derfor give god mening at indlejre de mest sammensatte elementer i selve WSDL-dokumentet i stedet for at lave selvstændige XSD schema er på alle niveauer. Schemadefinitionerne er dog ikke indlejret i det WSDL-dokument, der vises her (se afsnittet nedenfor), men er i stedet refereret via et include- eller import-direktiv. Schema-definitionerne kan ses i deres helhed i Appendiks 9. Trin 2: Modellering af beskeddefinitioner I dette trin defineres en requestbesked, en responsebesked samt et fault detail element. Request-beskeden er baseret på elementtypen MedicineChestStructureGet (se Appendiks: XSD schema er for eksempel) og response-beskeden er defineret via elementypen MedicineChestStructure (se Appendiks: XSD schema er for eksempel). Fault-beskeden er defineret via elementtypen MedicineChestFault, hvis definition er indlejret i WSDLdokumentet. Beskeddefinitionerne kan findes i WSDL-dokumentet som de 3 <message> elementer, med name = hhv. "MedicineChestStructureGetRequest", "MedicineChestStructureGetResponse" samt "MedicineChestStructureFault". 20

21 Trin 3: Modellering af grænseflade I dette trin defineres et interface rummende en operation. Operationen er defineret ved den ovenfor beskrevne requestbesked, responsebesked samt fault detail elementet, og ser ud som følger: <operation name="medicinecheststructureget"> <input name="medicinecheststructuregetrequest" message="tns:medicinecheststructuregetrequest" /> <output name="medicinecheststructuregetresponse" message="tns:medicinecheststructuregetresponse" /> <fault name="fault" message="tns:medicinecheststructurefault" /> </operation> Det resulterende OIOWSDL-dokument bliver hermed som vist nedenfor: <?xml version="1.0" encoding="utf-8"?> <definitions xmlns=" targetnamespace=" xmlns:xsd=" xmlns:tns=" xmlns:soap=" <types> <xsd:schema elementformdefault="qualified" targetnamespace=" rep.oio.dk/dkma.dk/homecare/xml.schema/ "> <xsd:include schemalocation="../xsd/dkma_medicinecheststructureget.xsd"/> <xsd:include schemalocation="../xsd/dkma_medicinecheststructure.xsd"/> <xsd:element name="medicinecheststructurefault" type="xsd:string"/> </xsd:schema> </types> <message name="medicinecheststructuregetrequest"> <part name="cpr" element="tns:medicinecheststructureget"/> </message> <message name="medicinecheststructuregetresponse"> <part name="arg2" element="tns:medicinecheststructure"/> </message> <message name="medicinecheststructurefault"> <part name="fault" element="tns:medicinecheststructurefault"/> </message> <porttype name="medicinechest"> <operation name="medicinecheststructureget"> <input name="medicinecheststructuregetrequest" message="tns:medicinecheststructuregetrequest"/> <output name="medicinecheststructuregetresponse" message="tns:medicinecheststructuregetresponse"/> <fault name="medicinecheststructurefault" message="tns:medicinecheststructurefault"/> </operation> </porttype> (fortsættes på næste side) 21

22 <binding name="medicinechest" type="tns:medicinechest"> <soap:binding transport= style="document"/> <operation name="medicinecheststructureget"> <soap:operation soapaction= " rep.oio.dk/dkma.dk/homecare/xml.schema/ /#medicinecheststructureget" style="document"/> <input name="medicinecheststructuregetrequest" > <soap:body use="literal"/> </input> <output name="medicinecheststructuregetresponse"> <soap:body use="literal"/> </output> <fault name="medicinecheststructurefault"> <soap:fault name="medicinecheststructurefault" use="literal"/> </fault> </operation> </binding> <service name="medicinechest"> <documentation>wsdl file for MedicineChest</documentation> <port name="medicinechest" binding="tns:medicinechest"> <soap:address location= " </port> </service> Trin 4: Generér kodeskabelon Service udbyder Service udbyderen implementerer den Web Service, som er specificeret af WSDL-dokumentet. Det generelle mønster for server-side implementeringen af en WSDL baseret Web Service er, at det valgte værktøj med WSDLdokumentet som input genererer skeleton og data-binding klasser/kode i det anvendte programmeringssprog. Derefter er det op til udvikleren at skrive serverside kode, der kan aktiveres via de genererede skeletons. Data-binding klasserne afspejler de XSD typer, som WSDL-dokumentet er baseret på og bruges til at repræsentere de overførte beskeder. Service aftager En service aftager vil generelt vha. det valgte client-side værktøj generere stub og data-binding klasser/kode. Udvikleren kan så anvende disse stubbe til at kalde web servicen. Det efterfølgende kapitel Hvordan anvendes OIOWSDL? rummer referencer til en række af de mest udbredte udviklingsværktøjer. 22

23 Hvordan anvendes OIOWSDL? (Værktøjsunderstøttelse) > Nærværende afsnit beskriver, hvorledes man på baggrund af et OIOWSDLdokument kan generere kode til klient og server. Det vil sige dels at implementere en web service (service-skeleton), der overholder OIOWSDL beskrivelsen, dels generere kode, der kan kalde web servicen (klientstubbe).. oiowsdl Generering af serviceskabelon/- skeleton til web servicen Generering af proxy klasse til klientapplikation Serviceskabelon Kommunikerer via OIOWSDL interface Proxy klasse De pt. (primo 2007) mest udbredte udviklingsværktøjer er blevet undersøgt for at se, hvordan de håndterer OIOWSDL-dokumenter, udviklet efter kontraktførst metoden. De undersøgte værktøjer er: BEA WebLogic 9.2 Axis 1.3 og 2 Eclipse 3.2 IBM Rational Application Developer 6.0, og 7.0.Net 1.1, 2.0 og 3.0 Ruby Der er ikke lavet udførlige beskrivelser for, hvordan man laver web services med de enkelte værktøjer. Udgangspunktet har i stedet været, at man følger værktøjets generelle fremgangsmåde for fremstilling af web services, og for hvert værktøj er gennemgået, hvad der dukker op i forbindelse med arbejdet med OIOWSDL-dokumenter. 23

24 Der vil således i den følgende gennemgang i høj grad være links til referencedokumentationen for det enkelte værktøj. I visse tilfælde vil femgangsmåden være at følge værktøjets dokumentation direkte. For hvert værktøj, der bliver gennemgået, følger en generel introduktion og derefter et afsnit for hhv. klientstubbe og service-skeleton. Som eksempel bruges medicinskabet (MedicineChest) omtalt i foregående kapitel. Det forudsættes at WSDL- og XSD-eksemplerne fra medicinskabet er kopieret ud i filer på den lokale disk. I praksis skal XSD-filer til udvikling af WSDLdokumenter hentes i det fælles servicekatalog, men under udviklingsarbejdet vil det ofte være en fordel at have kopier liggende lokalt; ikke mindst hvis man kombinerer XSD erne fra ISB en med egne/nyudviklede XSD er. Generelle problemer med imports Inden vi går i gang, er det vigtigt at identificere en meget udbredt implementations-detalje i værktøjerne. Visse XML-parsere tolker nemlig XSDspecifikationen meget hårdt og giver derfor fejl, når samme namespace importeres flere gange med forskellige schemalocations. Specifikationen siger følgende: "Note: The above is carefully worded so that multiple <import>ing of the same schema document will not constitute a violation of clause 2 of schema Properties Correct ( ), but applications are allowed, indeed encouraged, to avoid <import>ing the same schema document more than once to forestall the necessity of establishing identity component by component. Given that the schemalocation [attribute] is only a hint, it is open to applications to ignore all but the first <import> for a given namespace, regardless of the actual value of schemalocation, but such a strategy risks missing useful information when new schemalocations are offered." Med andre ord betyder det, at parsere der tolker specifikationen efter ovenstående, vil kun hente den først refererede XSD-fil og derefter gå ud fra, at den indeholder den komplette definition af det givne namespace. Denne parsning giver imidlertid problemer i forhold til OIOs NDR-standard, der siger, at et namespace splittes op, så hver type ligger i hver sin fil (afsnit 3.5 i NDR). I tilfælde, hvor der laves import af flere typer fra samme namespace, kan nogle parsere komme med fejl om, at alle andre typer end den første er udefineret. 24