Webové služby v systéme ABRA - všeobecne

V tejto kapitole nájdete výklad nasledujúcich tém:

Nevyhnutnou podmienkou pre prevádzkovanie webových služieb je, aby bola táto časť systému nainštalovaná a licencovaná.

Systém ABRA Gen by mal byť nainštalovaný ako sieťový (tzn. s aplikačným serverom). (ABRA WS server je klientom aplikačného servera, ako bolo povedané vyššie, takže po jeho spustení už systém ABRA Gen nie je možné spustiť nainštalovaný ako single a naopak (systém nahlási pokus o opakované spustenie rovnakej jednoužívateľskej verzie).

Ďalej je na prevádzku potrebné:

  • Mať splnené podmienky pre používanie skriptovania, viď čo je potrebné na prevádzku skriptovania.
  • Mať nadefinované operácie a web. služby v ABRA Gen
  • Mať správne nastavené parametre pre WS server v súbore WS.cfg.

  • Následne zabezpečiť chod ABRA WS servera a jeho komunikáciu s aplikačným serverom, tzn.:

    • mať nainštalovanú službu ABRA Server webových služieb a mať ju spustenú (ak ho prevádzkujete ako službu (odporúčané)),

      Pro správné fungování musí být služba spuštěna pod uživatelem, který má přidělenou a nastavenou tiskárnu Tedy služba nesmí běžet pod Lokálním účtem. Důvod je ten, že se ovladače přidělené tiskárny používají pro generování tiskových sestav.

    • mať spustenú aplikáciu (ak ho prevádzkujete ako Win aplikáciu),
    • zabezpečiť spustenie aplikačného servera (aplikačný server sa ale dokáže spustiť automaticky v prípade inštalácie na rovnakom PC, z ktorého sa spustí klientska časť ABRA Gen (tu ABRA WS server)).

  • Potom zabezpečiť chod externého webového servera (napr. Apache), tzn.:

    • mať nainštalovaný Apache,
    • mať v ňom v adresári \modules nakopírovaný ABRA WSDLdoinštalovaný ABRA WSDL modul zodpovedajúci verzii Apache a OS, na ktorom beží,
    • mať v ňom v adresári \conf nakopírovaný konfiguračný súbor abraws.conf,
    • mať Apache správne nakonfigurované (viď popis ABRA WSDL modulů), ide v prvom rade o úpravu konfiguračného súboru httpd.conf,
    • zabezpečiť spustenie Apache
  • Po update ABRA Gen aktualizovať príslušné súbory. Viď Web. služby a update.

Poradie spustenia a zastavovania služieb ABRA WS servera a Apache nie je dôležité. Apache po spustení nahráva ABRA modul, ktorý sa snaží spojiť s ABRA WS serverom, aby si načítal poskytované služby. Spojenie nie je udržiavané nepretežite, akonáhle si poskytované služby k sebe načíta, spojenie sa rozpojí. Toto spojenie sa samo obnovuje, resp. sa vždy znovu vytvára, keď je to potrebné, a to len na nevyhnutne dlhú dobu, následne sa opäť ukončí. Z toho plynie, že prípadný reštart ABRA WS servera nie je na závadu, nie je potrebné zastavovať a znovu spúšťať Apache a WS server v nejakom definovanom poradí.

Systém ABRA Gen od verzie 8.03 plne podporuje štandard webových služieb a umožňuje externým systémom pripojiť sa, načítať či uložiť dáta plne konzistentne, a to pomocou ľubovoľného programovacieho prostredia, ktoré webové služby (WS) podporuje.

Operácia - Operácia je v podstate základnou stavebnou jednotkou webových služieb. Je to funkcia, ktorá vykonáva určitú (požadovanú) činnosť. Napr. "označ túto objednávku ako potvrdenú" alebo "povedz mi, či je táto objednávka už vyfakturovaná" a pod. (Viď na obrázku 1 bod 2). V systéme ABRA Gen sa jednotlivé operácie definujú v agende Operácie.

Webová služba - Je to skupina jednej alebo viacerých operácií združených do akejsi logickej skupiny. Môžu to byť napríklad všetky operácie súvisiace s určitou konkrétnou činnosťou (napr. v systéme ABRA Gen operácie ovládajúce adresár) (Viď na obrázku 1 bod 1). V systéme ABRA Gen sa webové služby definujú v agende Webové služby.

Obrázok 1.  Body 1 a 3 sú Webové služby, bod 2 je operácia vo vybranej službe.

Každá operácia je vlastne metóda, ktorá má meno, vstupné (voliteľne i výstupné) parametre a môže mať i návratovú hodnotu. Vlastné operácie sú definované v agende Operácie. Každá operace má název, což je jméno, pod kterým se tato operace zobrazuje v prohlížeči (viz Obrázek 1, bod 2) a zároveň je to jméno, kterým se tato operace volá. Ďalej je nutné špecifikovať, či ide o "procedúru" alebo o "funkciu". V prípade funkcie je potrebné špecifikovať návratovú hodnotu funkcie, čo je možné zabezpečiť zaradením parametra s menom Result medzi parametre operácie. Ku každej operácii je možné definovať vstupno/výstupné parametre. Každý parameter má meno, typ parametra (číslo, reťazec, ...) a príznak parametra, pomocou ktorého sa špecifikuje, či ide len o vstupný alebo o vstupno/výstupný parameter. Tzn. parameter môže byť buď bez príznakov, v tom prípade ide len o vstupný parameter, alebo môže mať hodnotu Var, čo znamená, že ide o vstupno/výstupný parameter, ktorý sa odovzdá ako vstup, ktorého hodnota môže byť operáciou modifikovaná a upravená hodnota sa vráti späť.

Požadovaná funkcionalita (to, čo má daná operácia vlastne vykonať) je realizovaná pomocou skriptovania, tzn. ku každej operácii musí byť definovaná zodpovedajúca metóda v nejakom balíčku v agende Balíčky skriptov. Každá operácia musí mať preto ďalej nastavené odkazy na vyvolanie obsluhy do skriptovania, tzn. meno balíčka, meno knižnice a meno metódy vyvolávanej v knižnici, ktorá požadovanú funkcionalitu implementuje. Pokiaľ daná metóda ešte neexistuje, je možné si hlavičku pre ňu priamo z agendy Operácie založiť.

Webové služby sa definujú v agende Webové služby. Služba ponúka jednotlivé operácie, ktoré spolu nejako súvisia (viď Obrázok 1, kde body 1 a 3 sú Webové služby, bod 2 je operácia vo vybranej službe). Každá webová služba má vo svojej definícii názov, ktorý sa zobrazuje v prehliadači (viď Obrázok 1, bod 1) a ktorý sa používa i pri vyvolávaní operácií v nej obsiahnutých. Pre každú službu je špecifikovaný zoznam operácií, ktoré budú v rámci tejto služby dostupné. Operáciu je možné použiť i niekoľkokrát v rámci rôznych služieb. To je dôležité, keďže celá webová služba vykonáva všetky svoje operácie pod jediným špecifikovaným užívateľom. Viacnásobné použitie umožňuje vyvolať tú istú operáciu vždy ako iný užívateľ. Užívateľ sa zadáva v definícii webovej služby.

Implementáciou sa myslí samotné naprogramovanie toho, čo má operácia vykonávať. To sa deje v skriptovaní. Tu je potrebné vytvoriť nový balíček, v ňom knižnicu a v nej funkciu alebo procedúru, presne podľa mien, ktoré ste zadali v definícii operácie, vrátane všetkých parametrov a v prípade funkcie i vrátane návratovej hodnoty.

Pozor, každá metóda obsluhujúca v skriptovaní určitú webovú operáciu preberá ako prvý parameter hodnotu Self, ktorá je typu TNxWebServicesHelper. Tento parameter sa nikde v definícii operácie neuvádza, nie je ho ani potrebné zasielať pri vyvolaní operácie zo vzdialeného systému. Musí sa s ním akurát počítať pri písaní kódu v skriptovaní. Jeho vytvorenie i správne umiestnenie na prvú pozíciu medzi parametrami v definícii danej metódy zabezpečí systém ABRA Gen sám, ak si necháte hlavičku skriptu pre vami zadávanú operáciu predvyplniť funkciou Vytvoriť hlavičku (v opačnom prípade ho musíte uviesť sami).

Tento objekt (Self) má dve vlastnosti (property) a to:

  • Context (TNxContext) – ide o klasický kontext, kde je už prihlásený užívateľ, pod ktorým sa operácia vykonáva. Umožňuje získať interné ABRAOLE, získať či prípadne "zahodiť" číselník, vykonať SQL príkaz atď.

  • ObjectSpace (TNxCustomObjectSpace) – ide o objektový priestor odvodený od kontextu. Slúži na vytváranie nových business objektov, riadenie transakcií, vykonanie SQL príkazu atď.

    Ponuka triedy TNxWebServiceHelper v Class exploreri v skriptovaní

Príklad skriptu:

Ukážka jednoduchej implementácie operácie, ktorá vytvorí business objekt Firma, načíta z databázy zadanú firmu (v našom prípade firmu ABC s.r.o.) a ako výsledok celej operácie vráti TNxSOAPBusinessObject reprezentujúci túto firmu.

TNxSOAPBusinessObject je štruktúra, ktorá umožňuje prenášať business objekty systému ABRA Gen prostredníctvom webových služieb. Štruktúra TNxSOAPBusinessObjectje nasledujúca:

TNxSOAPBusinessObject
property Fields: TNxSOAPBusinessObjectFields
end;

TNxSOAPBusinessObject obsahuje o. i. vlastnosť Fields (typu TNxSOAPBusinessObjectFields), čo je pole obsahujúce jednotlivé položky (fields) v business objekte:

TNxSOAPBusinessObjectFields = array of TNxSOAPBusinessObjectField;

TNxSOAPBusinessObjectField je objekt obsahujúci informácie o jednom "fielde" business objektu (BO). Štruktúra TNxSOAPBusinessObjectField je nasledujúca:

TNxSOAPBusinessObjectField
property FieldName: String
property FieldDataType: TNxDataType
property FieldDataKind: TAWSDataKind
property FieldValueAsString: String
property FieldValueAsInteger: Integer
property FieldValueAsFloat: Extended
property FieldValueAsDateTime: TDateTime
property FieldValueAsBoolean: Boolean
property BusinessObject: TNxSOAPBusinessObject
property Collection: TNxSOAPBusinessObjectCollection
end;

TNxDataType = (dtUnknown, dtString, dtSmallint, dtInteger, dtWord, dtBoolean,
 dtFloat, dtCurrency, dtBCD, dtDate, dtTime, dtDateTime, dtBytes,
 dtVarBytes, dtAutoInc, dtBlob, dtMemo, dtGraphic, dtFmtMemo,
 dtTypedBinary, dtCursor, dtGuid, dtList);

TAWSDataKind = (adkData, adkBusinesObject, adkCollection);

Význam jednotlivých vlastností:

  • FieldName – meno fieldu (napr. ID je vlastná identifikácia)
  • FieldDataType – typ dát, ktoré field BO obsahuje. Jednotlivé hodnoty sú vymenované vyššie, ale v praxi sa používajú len dtString, dtSmallint, dtInteger, dtWord, dtBoolean, dtFloat, dtCurrency, dtDate, dtTime, dtDateTime, dtMemo, dtFmtMemo
  • FieldDataKind – upresňuje, o aký druh fieldu ide

  • adkData – ide o dáta, ktorých typ je špecifikovaný vo FieldDataType. Príslušná hodnota je uložená vo FieldValueAs... – jedná se o data, jejichž typ je specifikovaný v FieldDataType. Príslušná hodnota je uložená vo FieldValueAs...

    • dtString, dtMemo, dtFmtMemo FieldValueAsString
    • dtSmallint, dtInteger, dtWord FieldValueAsInteger
    • dtFloat, dtCurrency FieldValueAsFloat
    • dtDate, dtTime, dtDateTime FieldValueAsDateTime
    • dtBoolean FieldValueAsBoolean
  • adkCollection – ide o kolekciu jedného alebo viacerých business objektov. Typicky sú tu uložené napr. riadky dokladu. V tomto prípade je v Collection instance TnxSOAPBusinessObjectCollectionrep reprezentujúca kolekciu.
  • adkBusinessObject – field je typu odkaz na iný business objekt. V tomto prípade je v property BusinessObject ďalšia inštancia TNxSOAPBusinessObject reprezentujúca odkazovaný business objekt.

V této části naleznete princip ABRA WS serveru, jak jej zprovoznit, nakonfigurovat a jak řešit rozložení zátěže.

Pojmom ABRA WS server (skrátene AWS server) budeme označovať ABRA server webových služieb, ktorý vykonáva všetko potrebné v systéme ABRA Gen. ABRA WS server môže byť realizovaný viacerými spôsobmi:

  • WSServer.exe - ABRA WS serverom je Windows aplikácia (exe).
  • WSServerS.exe - ABRA WS serverom je Windows služba (service). Odporúčané.

Oba súbory sú po inštalácii ABRA Gen k dispozícii v roote adresára, do ktorého bola ABRA Gen inštalovaná.

ABRA WS server sa správa ako klientska časť aplikácie ABRA Gen, ktorá komunikuje s aplikačným serverom (tzn. rovnako ako akýkoľvek iný klient ABRA Gen (Pojem klientska časť viď v kap. Technológia spracovania dát.) Ak je spustený, "počúva" na definovanom TCP/IP porte 3121 (je možné nastaviť aj iný, viď konfiguračný súbor abraws.conf) a robí, "čo sa mu povie", tzn. prostredníctvom aplikačného servera pristupuje k ABRA Gen, načítava si služby, ktoré sú v nej nadefinované, tie sprístupňuje von a vykonáva požiadavky, ktoré dostáva z externej aplikácie, ktorá s ním komunikuje prostredníctvom internetového webového servera (napr. Apache).

Nezamieňajte "server webových služieb" (v systéme ABRA Gen ABRA WS server) a "webový server", tzn. web server (napr. Apache).

Registrácia, ďalšie podmienky spustenia atď.

WSserver.exe sa spustí štandardným spôsobom ako exe súbor, ak je spustený, je na toolbare zobrazený ako iné bežiace aplikácie.

WSserverS.exe je Windows služba, ktorá vykonáva všetko potrebné v systéme ABRA Gen. Aby bolo možné ABRA WS server používať ako službu, je nutné túto službu najskôr zaregistrovať spustením dodávaného exe súboru z príkazového riadka (na to je potrebné mať administrátorský prístup). Tzn. pod administrátorským účtom nainštalovať servis z príkazového riadka jeho vyvolaním s parametrom /INSTALL (resp. -INSTALL) z adresára, kde je WS server umiestnený:

<cesta>\WSserverS.exe /INSTALL

Pokud se instalace služby zdaří, zobrazí se zpráva potvrzující úspěšné nainstalování a v přehledu služeb ve Windows se objeví nová služba nazvaná ABRAGenWebServices (zobrazovaný název ABRA Gen® WebServices).

Nainstalovaná služba ve Windows.

Pre odinštaláciu to isté, ale s parametrom /UNINSTALL (resp. -UNINSTALL).

  • ABRA WS server musí byť umiestnený v rovnakom adresári ako systém ABRA Gen. (Využíva balíčky systému ABRA Gen). Bežať však môže inde, viď ďalší bod.

  • ABRA WS môže bežať na inom počítači, ako na ktorom beží aplikačný server a na ktorom je inštalovaný systém ABRA Gen. To bude typický prípad v praxi (kvôli rozdeleniu záťaže).

    Aplikačný server beží na jednom počítači, server webových služieb na inom počítači, pričom fyzicky ležia na treťom v adresári, kde je ABRA nainštalovaná.

    V takom prípade sa WSServerS.exe musí inštalovať s UNC cestou (nie z namapovanej cesty). Tedy např. \\GxAppServer\AbraGen\WSServerS -install. Instalace s cestou zadanou přes mapovaný disk, tj. např. W:\AbraGen\WSServerS -install sice půjde nainstalovat, ale nepůjde spustit. Dôvodom je to, že služba nebeží pod profilom aktuálne prihláseného užívateľa. Nemá jeho prostředí (plochu, různá nastavení atd. a mimo jiné ani mapování síťové cesty \\GxAppServer\AbraGen\ na písmenko W).

  • ABRA WS server musí byť správne nakonfigurovaný. Viď ďalej Konfigurácia ABRA WS servera.
  • ABRA WS server môže byť zaregistrovaný aj viacnásobne.

Logovanie

O priebehu akcií ABRA WS servera resp. jeho kernelov (viď ďalej) si je možné zobraziť log. Logovanie udalostí v kerneli webových služieb sa konfiguruje ako ostatné logovanie v konfiguračnom súbore Nexus.cfg v sekcii [WS~Group]. Konfiguračný súbor Nexus.cfg systém hľadá v rovnakej ceste, ako je AbraGen.exe.

[Log.WS~Group]
Enabled=1
Level=6

Vzhľadom k tomu, že WS server je nevizuálny, v prípade problémov je potrebné logovať viac vecí a logovanie týkajúce sa webových služieb tým pádom prebieha viacerými triedami. Ich vzájomná konfigurácia môže byť zložitá, navyše logovanie len jednej z nich môže byť v praxi na odhalenie problému nedostatočné, ak súčasne nebude k dispozícii aj log inej z nich. Preto je k dispozícii logovacia skupina WS~Group. Zapnúť "rozumné" logovanie je možné pridaním práve tejto skupiny do Nexus.cfg. Pozor, bude vznikať množstvo log súborov, ktoré je nutné rozumne odsúvať.

Webové služby umožňujú vybavovať viacero požiadaviek naraz. ABRA WS server WSServer.exe resp. WSServerS.exe je len akási "obálka", ktorá zabezpečuje spúšťanie procesov na vybavovanie jednotlivých požiadaviek od klientov. Každú takúto požiadavku vykonáva tzv. jadro (resp. kernel) ABRA WS servera (WSServerKernel.exe). Samotný server teda požiadavky nevykonáva, ale len prijíma požiadavky od klientov a radí ich do zástupu, z ktorého si ich vyzdvihujú jadrá (kernely) a vykonávajú ich. Každé jadro dokáže vykonávať naraz len jednu požiadavku, čo v podstate znamená, že počet práve spustených jadier (kernelov) sa rovná max. počtu súčasne vybavovaných požiadaviek. Maximálny počet súčasne bežiacich kernelov (tzn. súčasne vybavovaných požiadaviek) je možné nastaviť v konfiguračnom súbore WS.cfg.

Užívateľ sám WSServerKernel.exe žiadnym spôsobom nespúšťa. ABRA WS server si tieto svoje kernely spúšťa a ukončuje automaticky sám podľa vyťaženosti služieb. Tzn. keď zástup požiadaviek na ABRA WS serveri vyžaduje spustenie ďalšieho kernela, ABRA WS server si ho spustí. (Spustenie nenastane okamžite, kernel potrebuje určitý čas na nadviazanie spojenia (cca desiatky sekúnd), pričom existuje timeout (cca 3 min), počas ktorého ABRA WS server čaká na jeho spustenie a ďalšie kernely nespúšťa. Ak kernel spojenie z nejakého dôvodu nenadviaže, ABRA WS server ho po tomto timeoute ukončí a spustí iný kernel.

Podobne, ak dôjde pri vykonávaní požiadavky v jadre (kernel) k nejakej fatálnej chybe (napr. k výpadku siete, keď sa stratilo spojenie na aplikačný server a jadro nie je schopné ďalej pokračovať), jadro to serveru oznámi a ukončí sa. Server spustí iné jadro (kernel), na ktoré požiadavku odovzdá. Chyba, ku ktorej môže pri vykonávaní požiadavky dôjsť, nemusí byť iba v spojení, môže byť tiež priamo vo vyvolávanom skripte, pričom môže byť natoľko fatálna, že spôsobí ukončenie jadra. Aby sa potom nestalo, že server bude danú požiadavku odovzdávať na ďalšie a ďalšie jadrá do nekonečna, platí:

Požiadavka sa odovzdáva na ďalšie jadrá, ak jedno z nich požiadavku nevyrieši, pričom maximálny počet odovzdaní na ďalšie jadro sa rovná Maximálnemu počtu súčasne bežiacich jadier (kernelov). Tým je zabezpečená kompletná obnova jadier a v prípade, že to nepomôže, spracovávanie požiadavky sa preruší a chyba sa prepošle na vyvolávajúcu stranu.

Na správu bežiacich kernelov je možné využívať napr. Telnet, viď konfigurácia ABRA WS servera.

V inštalačnom adresári sú v podadresári ..\Doc\webservices dve šablóny konfiguračných súborov, ktoré slúžia na konfiguráciu webových služieb. Jedna pre komunikáciu WS servera so serverom Apache, druhá pre samotnú konfiguráciu WS servera:

Šablóna slúžiaca pre konfiguráciu modulov servera Apache a konfiguráciu komunikácie medzi serverom Apache a WS serverom ABRA. Všetky prípadné moduly (aj tie prípadne premenované pre obsluhu viacerých spojení) sa konfigurujú z tohto súboru. Šablónu stačí len premenovať (resp. odstrániť koncovku tmpl) a nahrať do inštalačného adresára servera Apache a v ňom do podadresára conf. V tomto umiestnení je konfiguračný súbor očakávaný! Konfiguračný súbor obsahuje sekciu [WebServices], ktoré ďalej obsahujú parametre, ktoré sú v základnom stave okomentované (je pred nimi uvedený znak #) a v tomto stave sa preberá vyplnená východisková hodnota parametra. Ak je daný parameter nutné zmeniť, je potrebné znak # odstrániť.

abraws.conf.tmpl obsahuje tieto parametre:

Názov Popis
WSServerIP IP adresa, na ktorej bude webový server komunikovať s ABRA WS serverom. Východisková hodnota je localhost.
WSServerPort Číslo TCP/IP portu, na ktorom bude webový server komunikovať s ABRA WS serverom. Východisková hodnota je 3121.
MaximumProcessingTime Max. doba na vykonanie požiadavky. Čas vyhradený na spracovanie požiadavky. Hodnota môže byť v rozmedzí <1..MaxInt>. Hodnota je v sekundách. Východisková hodnota je 1800.
HTTPInterfaceVersion

Speciální parametr pro HTTP modul, který určuje jaká verze volání skriptů bude použita pro obsluhu požadavků z tohoto modulu Hodnoty mohou být tyto:

  • 1=Pôvodné skripty s 5timi parametrami.
  • 2=Nové rozhranie metód v skriptingu, kedy sú okrem SELF odovzdané 2 objekty: Request a Response

Východisková hodnota je 1

Za základnou sekciou [WebServices] môžu nasledovať ďalšie sekcie. Tieto sekcie využijete v prípade, že máte viac spojení a chcete prevádzkovať viac ABRA WS serverov (pre obsluhu jednotlivých spojení) z jednej inštalácie Apache, tzn. máte skopírované a premenované so súbory pre obsluhu ďalších spojení. Mená týchto sekcií musia zodpovedať premenovaným so súborom. Napr. [mod_abra_wsserver2_2_01], za ktorým bude nasledovať parameter s hodnotou pre toto spojenie. Typicky sa volí minimálne WSServerPort. Viac viď popis v samotnej šablóne abraws.conf.tmpl.

Stejným způsobem je možné postupovat i v případě využívání RESTful rozhraní (několik různě pojmenovaných kopií Apache modulu mod_abra_wsserver_http_2_2.so, pro každý sekce v abraws.conf).

Šablóna slúžiaca pre konfiguráciu servera webových služieb. Šablónu stačí len premenovať (resp. odstrániť koncovku tmpl) a nahrať do inštalačného adresára systému ABRA Gen V tomto umiestnení je konfiguračný súbor očakávaný! Konfiguračný súbor obsahuje sekciu [WebServices], ktoré ďalej obsahujú parametre, ktoré sú v základnom stave okomentované (je pred nimi uvedený znak #) a v tomto stave sa preberá vyplnená východisková hodnota parametra. Ak je daný parameter nutné zmeniť, je potrebné znak # odstrániť.

ws.cfg.tmpl obsahuje tyto parametry:

Názov Popis
ConnectionName Názov spojenia, na ktoré sa má ABRA WS server pripojiť. Východisková hodnota nie je nastavená, je ju vždy nutné vyplniť.
ConcurrentProcessesCount Maximálny počet súbežne spustených "kernelov". Hodnota definuje, koľko požiadaviek môže server webových služieb spracovávať paralelne. Podľa záťaže sa budú dynamicky spúšťať ďalšie dcérske procesy až do nastavenej hodnoty. Hodnota môže byť nastavená v rozmedzí <1..20>. Východisková hodnota je 3.
ModulePort Číslo TCP/IP portu, na ktorom má ABRA WS server komunikovať s webových serverom, tzn. na ktorom prijíma preposlané požiadavky z modulu Apache. Pozor, ak na 1 PC potrebujete spúšťať niekoľko WS serverov, musí každý z nich načúvať na inom porte. Východisková hodnota je 3121.
KernelPort Číslo TCP/IP portu, na ktorom má ABRA WS server komunikovať so svojimi kernelmi (jadrami). Využijete vtedy, keď na 1 PC potrebujete spúšťať viacero WS serverov. "Port kernelov" potom umožnuje, aby každý ABRA WS server používal pre svoje kernely iný TCP port. Východisková hodnota je 3546.
KernelInactivityTime Interval, za ktorý bude nepotrebný kernel ukončený. Ak nebude kernel po stanovený interval vyťažený (neobslúži počas tejto doby žiadnu požiadavku), bude ukončený. Hodnota môže byť v rozmedzí <30..MaxInt>. Hodnota je v sekundách. Východisková hodnota je 120.
WaitingRequestsCountTreshold Ak sa požiadavky hromadia vo fronte a ich počet prekročí stanovenú hranicu, server web.služieb aktívne spustí nový kernel, aby zvýšil priepustnosť spracovania. Hodnota môže byť v rozmedzí <1..MaxInt>. Východisková hodnota je 3.
WaitingRequestTimeTreshold Max. čakacia doba požiadavky. Stanovuje dobu čakania v zástupe. Ak požiadavka čaká vo fronte dlhšie, ako stanovený interval, ABRA WS server aktívne spustí ďalší dcérsky proces (za predpokladu, že nie je prekročený max. počet "kernelov"), aby zvýšil priepustnosť spracovania. Hodnota môže byť v rozmedzí <100..MaxInt>. Hodnota je v milisekundách. Východisková hodnota je 500.
MaximumProcessingTime Max. doba na vykonanie požiadavky. Čas vyhradený na spracovanie požiadavky. Hodnota môže byť v rozmedzí <1..MaxInt>. Hodnota je v sekundách. Východisková hodnota je 1800.
ChildProcessStartUpThreshold Čas vyhradený na štart dcérskeho procesu. Hodnota môže byť v rozmedzí <1..MaxInt>. Hodnota je v sekundách. Východisková hodnota je 180.
ServiceNameSuffix

Parametr, jehož odnota ovlivňuje název služby Windows webového serveru. Používa sa v prípade, kedy je nutné prevádzkovať viacero WS serverov. Uvádza sa za základnou sekciou [WebServices].

Do verzie 11.05 bola v systéme pri užívaní parametra chyba, ktorá bola vo verzii 11.06 opravená (hodnota parametra v konfiguračnom súbore abraws.conf sa musela zhodovať s hodnotou rovnakého parametra v súbore nexus.cfg). Ak vykonávate update zo staršej verzie ako 11.06 na novšiu a využívate parameter ServiceNameSuffix, bude potrebné službu preregistrovať.

Za základnou sekciou [WebServices] môžu nasledovať ďalšie sekcie. Tieto sekcie využijete v prípade, že máte viac spojení a chcete prevádzkovať viac ABRA WS serverov (pre obsluhu jednotlivých spojení) z jednej inštalácie ABRA Gen, tzn. máte skopírované a premenované exe súbory ABRA WS servera pre obsluhu ďalších spojení. Meno týchto sekcií musí zodpovedať premenovanému exe súboru ABRA WS servera. K dispozici je zde navíc i parametr ServiceNameSuffix, jehož hodnota ovlivňuje název služby Windows WS Serveru. Viac viď popis v samotnej šablóne WS.cfg.tmpl.

Ako už bolo spomenuté v popise konfiguračného súboru, v praxi môže pre jeden systém ABRA Gen bežať niekoľko ABRA WS serverov naraz a to:

  • vtedy, keď máte viacero spojení na databázu ABRA Gen a chcete používať web. služby pre každé z nich
  • alebo vtedy, keď potrebujete rozložiť záťaž na niekoľko PC

To vedie k nasledujúcim riešeniam:

  • na 1 PC beží niekoľko rôznych WS serverov
  • niekoľko "rovnakých" WS serverov beží na niekoľkých PC
  • ľubovoľná kombinácia predchádzajúcich

Ako bolo povedané vyššie v popise sprevádzkovania ABRA WS servera, ABRA WS server musí byť spúšťaný z PC a adresára, kde je ABRA Gen nainštalovaná (ale bežať môže na inom PC). V inštalačnom adresári sú v podadresári ..\Doc\webservices  je aj šablóna konfiguračného súboru. Ze šablony je možné vytvořit soubor, který po nahrání do kořenového adresáře systému ABRA Gen (a odstranění přípony tmpl) může být společný pro více současně běžících WS serverů.

  • Na 1 PC je možné službu "ABRA webových služieb" zaregistrovať viacnásobne.Všetky ABRA WS servery sa registrujú s prefixom WSServerS_%nazevexe% (napr. WSServerS_WSServerS pro WSSErverS.exe alebo WSServerS_WSServerS2 pro WSSErverS2.exe atď.). Zároveň i popis služby obsahuje názov príslušného *.exe. Tým pádom je možné skopírovať napr. WSServerS.exe do WSServerS2.exe a obe služby na danom PC zaregistrovať.
  • . Pokud jsme zkopírovali WSServerS.exe do WSServerS2.exe, tak tento druhý WS server bude po svém spuštění hledat v konfiguračním souboru WS.cfg sekci nazvanou [WSServerS2].

Na 1 PC beží niekoľko rôznych WS serverov - riešenie viacerých spojení na 1 PC

V konfiguračnom súbore je možné o.i. nastaviť, aké spojenie na databázu ABRA Gen daný ABRA WS server obsluhuje.

Na jednom PC môže bežať niekoľko WS serverov naraz. Vďaka tomu je možné obe služby zaregistrovať na rovnakom PC. Potom na 1 PC pobežia 2 rôzne WS servery, ktoré budú čítať z konfiguračného súboru, ktoré spojenia majú obsluhovať.

Pretože samotný ABRA WS server je možné prevádzkovať len na OS Windows a naopak webové servery, ktoré sprístupňujú samotné webové služby, bývajú prevádzkované často na linuxových OS alebo na samostatných strojoch, kde nie je nainštalovaný systém ABRA Gen), je celé riešenie webových služieb v systéme ABRA Gen rozdelené do dvoch častí:

Prvou časťou je ABRA WS server a druhou časťou sú ABRA_WSDL moduly, ktoré sú riešené ako pluginy najbežnejších webových serverov (Apache, IIS, ale i CGI -exe použiteľné prakticky v akomkoľvek webovom serveri). Tieto pluginy sa spoja s ABRA WS serverom. Adresa a port servera, s ktorým sa má modul spojiť, sa nachádzajú v textovej podobe v príslušnom konfiguračnom súbore, viď ďalej.

Moduly dodávané pro server Apache v. 2.2:

  • mod_abra_wsserver2_2.so
  • mod_abra_wsserver_http_2_2.so - určený pre rozhranie REST

Moduly dodávané pro server Apache v. 2.4:

  • mod_abra_wsserver2_4.so
  • mod_abra_wsserver_http_2_4.so - určen pro rozhraní REST

Moduly dodávané pro server Apache v. 2.4 64-bit:

  • mod_abra_wsserver2_4_64.so
  • mod_abra_wsserver_http_2_4_64.so - určen pro rozhraní REST

V případě použití 64-bitových modulů je nutné odstranit suffix _64 z jejich názvů. Vše ostatní zůstává stejné jako u 32-bitové verze

Zatiaľ nie je k dispozícii modul pre Apache bežiaceho na Linuxe. Z tohto dôvodu je zatiaľ webové služby možné prevádzkovať len v kombinácii s Apachom bežiacim na Windows. Avšak vzhľadom k tomu, že minimálne kvôli ABRA WS serveru (ktorý je z princípu rozbiehania a "zostreľovania" klientskych kernelov len Win) musí byť v systéme Windows stroj a tento je možné využiť i na chod win Apache, i za cenu, že by bol využívaný len špeciálne pre tento účel.

Vyššie uvedené knižnice sú určené pre server Apache (názov modulov do Apache začína na mod_). Zda jsou aktuálně k dispozici knihovny i pro jiné webové servery (např. IIS), příp. pro vyšší verze se informujte v obchodním oddělení výrobce. Avšak sa úpravy v tomto smere nepredpokladajú a skôr sa predpokladá rozvoj Web API.

Po update ABRA Gen nezabudnite vykonať aktualizáciu príslušných súborov. Viď Web. služby a update.

Adresa servera, s ktorým sa má modul spojiť, a port, na ktorom majú komunikovať, sú dané v konfiguračnom súbore webového servera. Pro Apache se jedná o soubor abraws.conf v podadresáři conf (tedy tak, jak je běžné u jiných modulů Apache). Formát nastavení uloženého v tomto souboru je

WSServerIP=AdresaIP (nebo jméno serveru web. služeb)

WSServerPort=Port. Port nie je povinný, pokiaľ nie je zadaný, použije sa východiskový port 3121.

Pokud je zapotřebí, aby Apache obsluhoval služby několika WS serverů najednou, je možné v souboru abraws.conf nadefinovat několik sekcí s názvy odpovídající názvům modulů (soubory .so nebo .dll). Viz sekce abraws.conf.tmpl, respektive popis použití uvedený přímo v souboru abraws.conf.tmpl.

Do konfiguračného súboru je možné zapísať viacero WS serverov. Tzn. viac riadkov v syntaxi AdresaIP (alebo meno servera web. služieb):Port a modul vždy používa prvý dostupný server. Modul nadväzuje nové TCP spojenie pre každú jednotlivú požiadavku na vykonanie služby a vždy pri nadväzovaní spojenia hľadá prvý fungujúci webserver z konfigurácie. To umožňuje prejsť počas chodu na záložný server v prípade výpadku primárneho servera a potom naspäť na primárny server pri obnovení činnosti primárneho servera.

Príklad inštalácie modulu pre webový server Apache pre obsluhu jedného ABRA WS servera:

Dodávaný modul (napr. mod_abra_wsserver2_2.so) nakopírujeme do adresára, kde má Apache moduly. Typicky je to podadresár \modules v adresári, kde je Apache nainštalovaný. V adresári, kde je konfigurácia Apache (\conf), by mal byť vytvorený konfiguračný súbor abrawsserver.conf (do neho zapíšeme IP adresu, kde beží ABRA WS server, napr. 192.168.1.1:3121). Ďalej je potrebné upraviť konfiguračný súbor Apache httpd.conf, ktorý sa nachádza v podadresári \conf. Tu je potrebné zabezpečiť nahranie nášho modulu. Za miesto, kde sa pridávajú jednotlivé moduly (LoadModule), umiestníme text:

LoadModule abra_wsserver2_2_module modules/mod_abra_wsserver2_2.so
<Location /AWS>
SetHandler mod_abra_wsserver2_2-handler
</Location>

<Location /AWS> určuje, v akej ceste sa budeme na naše webové služby odkazovať. Tzn. zjednodušene povedané "namapujeme" modul na nejakú url adresu resp. jej časť. Konkrétne tento príklad znamená, že naše služby budú dostupné na adrese http://menoservera.sk/AWS. (V predchádzajúcej url adrese je menoservera.sk identifikácia servera, kde je Apache nainštalovaný.) Keď máme všetko nastavené, môžeme spustiť webový server. Na http://menoservera.sk/AWS sa zobrazí stránka našich webových služieb, kde si môžeme prehliadnuť, aké všetky služby ponúkame a sú tu i odkazy na WSDL.

Ak Apache nainštalujeme na vlastný lokálny počítač s názvom napr. moje-ntb a modul abra_wsserver2_2_module namapujeme napr. takto: <Location /MojeAWS>, tak naše služby budú dostupné na http://java-ntb/MojeAWS.

Od verze 24.1 je nutné do modulů Apache nakopírovat spolu se soubory mod_abra_wsserver2_*.so i knihovnu NxSystemD.dll, která je také umístěná v hlavním adresáři ABRA Gen pre Firebird.

Ďalší postup sa líši podľa toho, aké programovacie prostredie alebo nástroj na pripojenie k ABRA Gen použijeme. Je možné použiť klasické nástroje, napr. Delphi, C++, Java alebo skriptovacie jazyky s podporou webových služieb, napr. PHP.

Poznámka k oprávneným prístupom k dátam prostredníctvom Webových služieb ABRA Gen:

  1. V systéme ABRA Gen je odporúčané zaviesť si fiktívnych užívateľov na vygenerovanie WSDL a užívateľa na spustenie služby (a im zodpovedajúce roly bez prístup. práv). Viď odporúčania uvedené v spomenutých položkách.
  2. Koncová aplikácia - Koncovú napr. webovú aplikáciu by si mal autor zabezpečiť vo vlastnej réžii. Autor konc. aplikácie si teda zariadi zaregistrovanie užívateľa a
    prihlásenie k serveru Apache. V rámci tejto koncovej aplikácie bude autor riešiť, ktoré funkcie komu povolí vyvolávať.
  3. WSDL - Ďalej je potrebné mať na pamäti, že WSDL je "verejné", tzn. Apache poskytuje informácie o funkciách, ktoré dokáže vyvolať, verejne. Proti obídeniu Apache a vyvolaniu funkcií WSservera zvonku je možné sa zabezpečiť pomocou firewallu.

Po update ABRA Gen je tiež potrebné vykonať aktualizáciu súborov potrebných pre prevádzku webových služieb. Ide o jednu z ďalších akcií spojených s inštaláciou novej verzie (update) ABRA Gen. Tzn. je potrebné z aktuálnej inštalácie ABRA Gen zobrať aktuálne súbory a nahrať ich do cieľových ciest.

Odporúčaný postup:

  • Zastaviť Apache

  • Nahrať do príslušnej cieľovej cesty aktuálny modul

  • Nahrát do příslušné cílové cesty aktuální knihovnu NxSystemD.dll, která se nachází v adresáři s instalací ABRA Gen.

  • Spustiť Apache
  • Overiť chod webových služieb