3.9 Tehnilise lahenduse kvaliteet

Kõik X-tee WSDL dokumendid peaks olema inimloetavad. WSDL dokument peab seetõttu olema korrektselt struktureeritud ja dokumenteeritud. X-tee nõuded ei sea reegleid WSDLi loetavusele, kuid järgnevate soovituste järgimine on hea tava, mis lihtsustab ja kiirendab teenustega liidestamist.

Andmeteenuste WSDL kirjelduse loomisel tuleb alati jälgida, et kõik elemendid, kirjeldused ja dokumentatsioonielemendid oleksid korrektse UTF-8 kodeeringuga. Vastasel korral võivad tekkida probleemid dokumendi lugemisel. Üsna tihti juhtub nii, et dokumentatsioonielementides või kommentaarides on tekstid vales kodeeringus. Alati tuleb kasutada tööriistu, mis oskavad seda korrektselt töödelda.

WSDL-vormingus teenusekirjelduse loomisel tuleb järgida järgmisi printsiipe:

  • Kommentaarid

WSDL dokumenti tuleb jätta vaid need kommentaarid, mis võivad olla kasulikud sihtrühmale: arendajatele ja analüütikutele, kes tegelevad andmeteenuste liidestamisega. Kindlasti tuleb lõppversioonist kustutada kõik üleliigsed kommentaarid ning kommentaari sees asuvad koodijupid. Erandiks võivad olla vaid andmeteenuste vanade versioonide kommentaarides olevad kirjeldused, mida siiamaani kasutatakse. Ka sel juhul tuleb siiski kaaluda nende kustutamist, sest üldjuhul on alati soovitatav kasutada uute liidestuste puhul andmeteenuse viimast versiooni.

  • Treppimine

Koodi kirjutades tuleb kasutada treppimist ning vältida ülipikki ridu. Mõned RIHA-s registreeritud alamsüsteemid kasutavad niivõrd pikki ridu, et osad redaktorid ei suuda sellist WSDL faili isegi avada.

  • Elementide nimetused

Elementide nimetused peavad olema lihtsad ja tähenduslikud. Nimetustes tuleb kasutada ASCII sümboleid ning vältida teiste sümbolite kasutamist. Kui andmeteenus omab rahvusvahelist tähendust, on soovitatav kirjeldada elementide nimed inglise keelsetena.

  • Skeemide importimine

Väliste skeemide kasutamine või mittekasutamine võib oluliselt mõjutada WSDL-i loetavust, seetõttu tuleb seda alati väga hoolikalt kaaluda. Väliste skeemide kasutamise eelised on:

    • teeb WSDL dokumendi kompaktseks;
    • võimaldab tüüpide ja elementide taaskasutamist, kui neid kasutavad mitmed alamsüsteemid.
Väliste skeemide kasutamise puudused on:

    • mõned redaktorid ei suuda imporditud skeeme mugavalt näidata;
    • imporditud skeemid nõuavad eraldi majutamist veebiserverites ning kui veebiserver ei tööta, ei ole võimalik töötada ka põhi-WSDLiga;
    • kui imporditud skeemid impordivad omakorda teisi skeeme, siis muutub skeemide hierarhia haldamine keeruliseks.

 

Seega võib väliste skeemide importimist soovitada vaid juhul, kui andmeteenuste arv on suur, andmeteenuseid kirjeldav struktuur on väga mahukas või kui on soov teatud tüüpe ja elemente taaskasutada.

Kui on vaja kasutada skeemide importimist, tuleks pöörata erilist tähelepanu sellele, kus paiknevad imporditud skeemid. Ei ole mõistlik viidata kohalikus arvutis või kohalikus võrgus olevale failile, sest välised arendajad ei pääse sellele ligi. On hea, kui imporditud skeemid on lisatud RIHA-sse. See vähendab riski, et imporditud skeemid ei ole ühel hetkel enam kättesaadavad.

Skeemide importimiseks ei piisa ainuüksi nimeruumi nimetamisest WSDL-kirjelduse <definitions> plokis. Kui skeemi elemendid on kasutatud WSDL-kirjelduse sees, siis peab alati lisama <xsd:import> käsu WSDL dokumendis paikneva skeemi sisse. Näiteks xroad skeemi importimine on vajalik praktiliselt igas X-tee teenuste WSDL-is, sest xroad skeemis on kirjeldatud X-tee dokumentatsioonielemendid ja X-tee päised.

Lisaks tuleb skeemide importimisel pöörata alati tähelepanu sellele, et imporditud skeemides poleks sama nimeruumi elemendid ja tüübid topelt defineeritud. Alati tasub kaaluda, kas importimine on üldse vajalik või saab kõik tüübid ja elemendid panna WSDL faili sisse.

WSDL-kirjelduses paiknevate skeemide puhul tuleb alati üritada vältida olukorda, kus sama  nimeruumi elemendid on paigutatud mitme skeemi alla. Selline skeemide kasutamine on halvasti spetsifitseeritud WSDL-i standardis ning paljudes rakendustes võivad tekkida probleemid.

Ideaalis peaks WSDL dokumendi sees olema ainult üks skeem, mille nimeruum on andmeteenuse nimeruum. Kui aga tüüpide ja elementide arv on väga suur või on soov taaskasutada skeeme mitme erineva andmekogu sees, siis võib kasutada ka skeemide importimist.

  • Üheselt mõistetav struktuur

X-tee päringute struktuur peab olema lihtne ja üheselt mõistetav. Elemendi <any> või tüübi „anyType” kasutamisel ei ole võimalik üheselt aru saada, millist päringut andmeteenus ootab ning millise vastuse võib sellele anda. Kui andmeteenuse päringute või vastuste sisu ei ole võimalik rangelt kirjeldada, siis peab andmeteenus kasutama selliste andmete edastamiseks pigem manuseid. Päringute rangelt määratud struktuur on vajalik näiteks MISP portaalide jaoks, mis võimaldavad WSDL dokumentide põhjal luua veebiliideseid. Viimane MISP portaali versioon on MISP2, mida võib rakendada nii X-tee andmeteenuste kasutamiseks toodangu keskkonnas kui ka andmeteenuste testimiseks. Rohkem informatsiooni MISP2 portaali kohta leiab aadressilt: https://github.com/jointxroad/components/blob/master/component_descriptions.md#x-road-portal-misp2.

Teatud kaalutlustel võib sisu abstraheerimine olla taotluslik (binaarinfo, failid, keerukad alternatiivsed keeled). Sellisel juhul tuleb kasutada mustrit PM3:protokolli tunneldamine (https://moodle.ria.ee/mod/page/view.php?id=375).


Last modified: Tuesday, 24 January 2017, 6:26 PM