O projektu
Specifikace projektu
Tento projekt byl založen jako místo pro vývoj a zpřístupnění standardů umožňujících zapojení knihovních systémů do Centrálního portálu knihoven nebo do jiných portálů založených na podobných principech jako CPK. Všechny informace jsou uloženy na wiki tohoto projektu, připomínky lze vkládat do issues.
Standardy používané projektem
Projekt se zaměřuje na efektivní meziknihovní komunikaci za použití NISO standardu pod názvem NCIP (zde oficiální stránky).
Vývoje a implementace NCIP standardu se ujala organizace eXtensible Catalog. S ohledem na vývojáře knihovních služeb pak na google code založila verzovací systém, kde všechny knihovny, mající zájem na rozvoji a kompatibilitě NCIP, sdílejí svůj postup.
Projekt dostal pod záštitou eXtensible Catalog název "XC NCIP Toolkit version 2.x of NCIP Protocol". Odtud vzniklo zkrácené pojmenování projektu XCNCIP2Toolkit.
XCNCIP2Toolkit je ke stažení zde a prozatím obsahuje 6 konektorů. Konektory (z angl. Connector) slouží k tomu, aby knihovní elektronický systém dokázal rozpoznat NCIP zprávu, správně ji použít a odeslat zpětnou vazbu odesílateli, která se strukturalizuje dle schématu definovaného standardem.
Zde uvádíme příklad, jak by mohla taková meziknihovní NCIP komunikace vypadat:
NCIP dotaz:
V této NCIP zprávě žádáme o informace o knihovně, které dotaz posíláme. To je zřejmé z tagu <ns1:LookupAgency>, která je, jako každá jiná NCIP služba, definovaná v oficiální dokumentaci.
Pomocí tagu <ns1:AgencyId> se představujeme a díky tagu <ns1:AgencyElementType> je možno blíže specifikovat, co si přejeme vědět.
NCIP odpověď:
Knihovna, jíž jsme dotaz poslali, nám poslala odpověď, ve které se zmiňuje o svém úplném názvu v mezinárodním formátu a také o své adrese.
Ačkoliv jsme žádali o mnohem více informací, dotazovaná knihovna uznala za vhodné zveřejnit pouze tyto elementární informace, nutné k navázání kontaktu.
Později se dozvíte, jak lze přímo v toolkitu nastavit informace, které bude spravovaná knihovna na tento dotaz vracet.
Instalace toolkitu
Vzhledem k tomu, že si přejeme, aby byly naše služby k dispozici pokud možno nonstop, měli bychom si obstarat výkonný server, na kterém by XCNCIP2Toolkit běžel. Servery se provozují zejména na linuxovém jádru a proto se zaměříme na instalaci pro Linux.
Stažení prerekvizit
Všechny námi použité programy jsou doporučené. Jistě cesta povede i jinudy, ale zde se zaměříme na postup, který jsme úspěšně použili při vývoji Aleph konektoru.
Aktuální verze xcncip2toolkit
K obstarání toolkitu máte v zásadě dvě možnosti. Buďto si jej stáhnete z google code nebo využijete služeb GitHub, Inc. a naklonujete si aktuální verzi Moravské zemské knihovny v Brně, která je mimo jiné autorem velké části Aleph konektoru.
Apache Maven
Pro správu tohoto Java projektu je použit Maven. (my jsme použili Maven 3.0.4)
Jelikož je zde od toho, aby stahoval další software potřebný k bezproblémovému běhu toolkitu, tak se bez jeho úspěšného buildování neobejdeme a náš toolkit nám s největší pravděpodobností ani nepojede.
Eclipse IDE for Java EE Developers
Aleph konektor jsme vyvíjeli za pomocí Eclipse Luna.
K dosažení nejvyšší efektivity jsme použili několikero zpětně doinstalovaných pluginů, dostupných ke stažení v menu Help -> Install New Software...
Které rozšíření se rozhodnete použít záleží čistě na Vašich osobních/firemních preferencích.
Apache Tomcat
Jako Java Servlet jsme se rozhodli použít Tomcat 8.0, jehož binární soubory jsme pouze stáhli a extrahovali do složky, kam běžně ukládáme software třetích stran. Dobrým zvykem je složka 'opt' v kořenovém adresáři: /opt/tomcat
Konfigurace vývojového prostředí
V této části instalace nás čeká buildování pomocí Maven, import Maven projektu do Eclipse a nastavení Servletu v Eclipse, aby bylo možné elegantně ladit či trasovat chyby.
Maven buildování
Projekt je zapotřebí zbuildovat v adresáři xcncip2toolkit/core/trunk příkazem mvn install. Jestliže build není úspěšný, upravíme příkaz tak, aby Maven přeskočil testy, tedy mvn install -Dmaven.test.skip. V našem případě se build povedl až napotřetí, opětovným spuštěním mvn install.
Toto bylo sestavení NCIP jádra. čeká nás ještě build konektoru (v našem případě Aleph), kterýžto je k nalezení to na adrese xcncip2toolkit/connector/aleph/20/trunk. Postupujeme stejně - zde by měly testy projít bez problémů.
Import do Eclipse
Otevřeme nový workspace, nevytváříme nový projekt, pouze naimportujeme xcncip2toolkit/core/trunk a xcncip2toolkit/connector/aleph/20/trunk.
Po úspěšném importu se objevil problém neustáléno buildování projektu v Eclipse. Je možno jej vyřešit tak, že zavřeme všechny projekty binding-* kromě binding a binding-jar.
Tomcat 8.0 v Eclipse
Po otevření okna Servers (Window -> Show View -> Others -> Servers) zvolte New Server -> Tomcat 8.0, nastavte Vámi při instalaci zvolený adresář a vše potvrďte.
Pro ověření správnosti konfigurace klikněte pravým tlačítkem myši na projekt aleph-web a zvolte Debug As -> Debug on Server. Mělo by se Vám zobrazit 'uživatelské rozhraní' aleph konektoru hojně užívaného při jeho vývoji.
Vývoj konektoru
Chystáte-li se vyvíjet Aleph konektor pro účely dalších knihoven běžících na Alephu, pak byste se měli seznámit s mapováním služeb z Alephu do NCIP formátu a hlavně, s ohledem na budoucí vývojáře, dodržovat předem daný code style a k přenosu užívat pokud možno pouze normalizované hodnoty.
NCIP code style
Je zde několik zvyklostí, se kterými byste se před vývojem vlastního konektoru měli seznámit.
Jsou jimi například jednorodé formátování, ukládání konstant do specifické statické třídy (viz connectors/aleph/20/trunk/util/AlephConstants.java), či používání normalizovaných hodnot a schémat.
Normalizované hodnoty a schémata
Téměř každá třída typu SchemeValuePair má uložené své normalizované hodnoty ve větvi core/trunk/service/src/main/java/org/extensiblecatalog/ncip/v2/service pod názvem Version1*.
Příkazem find . -type f -name "Version*" vypíšete všechny soubory sloužící k normalizaci.
Je vysoce doporučeno používat pouze hodnoty z těchto souborů nejen pro NCIP odpovědi, ale i dotazy. A to z toho důvodu, že NCIP Responder, na který se dotaz posílá, může mít zapnutou validaci dotazu právě dle těchto norem.
Máte-li zájem si tuto službu u svého Responderu zapnout/vypnout, ve složce connectors/aleph/20/trunk/web/src/main/resources si můžete prohlédnout konfigurační soubor Aleph konektoru toolkit.properties. Konkrétně se tedy jedná o tento řádek:
NCIPServiceValidatorConfiguration.ValidateMessagesAgainstSchema=true
Nastavíte-li hodnotu na false, tak Váš Responder již nadále nebude validovat dotaz vůči normalizovaným hodnotám.
Vypnutí validace podle schématu se doporučuje pouze a jen při vývojových potížích.
Mapování Aleph API -> NCIP
V zásadě lze použít Aleph RESTful APIs, Aleph X-Services, či Aleph Web Services.
Aleph RESTful APIs
Dosud napsaný konektor využívá této oblasti alephu co nejvíce z toho důvodu, aby i knihovny, které si nemohou dovolit tak drahé služby, jako jsou X-Services, byly konektorem obsloužitelné.
Nejdůležitější třídou konektoru vzhledem k Aleph RESTful APIs je RestDlfConnector.java, která nejdříve extrahuje data z konfiguračního souboru toolkit.properties a následně se používá k vytváření URL potřebných k vytvoření rest-dlf dotazů na aleph API a jiných potřebných "zprostředkovatelských" funkcí.
Patrons
V této oblasti Alephu se vyskytuje mnoho důležitých informací spojených s uživateli. Jedná se především o jejich práva, blokace/pokuty, půjčené/rezervované položky, stav účtu a v neposlední řadě také kontaktní 'adresy' uživatelů.
Pro zpracování dat použijeme LookupUser službu.
V konfiguraci pak toolkitu sdělíme, jak jsme delegáta LookupUser služby pojmenovali. V našem případě jsme vytvořili třídu AlephLookupUserService.java a proto delegáta definujeme následovně:
LookupUserService.class=org.extensiblecatalog.ncip.v2.aleph.AlephLookupUserService
Od našeho delegáta se očekává, že z dat, která se mu na vstupu dostanou (initiation data, service context, service manager), vytvoří výstup typu response data. Aby toho byl náš konektor schopen dosáhnout, tak za užití již dříve zmiňovaného RestDlfConnector.java dostane předpracovanou odpověď, kterou pak dle požadavků na vstupu zformátuje do LookupUserResponseData (v případě Lookup User služby).
Co všechno NCIP vyžaduje od Response Data můžete nalézt ve schématu. Je dobrým zvykem v něm vyhledávat (Ctrl + F) takto: e="LookupUserRe
Váš prohlížeč Vám již nabídne pouze jedinou shodu. Tvar této vyhledávací syntaxe vychází z toho, že hledáme element s atributem name a jeho přesně danou hodnotou. Mohli bychom zadat name="LookUserResponse", ale vzhledem k vysoké frekvenci dotazů vývojářů na nutnost prezence jednotlivých elementů v odpovědi pro NCIP, doporučujeme používat zkrácený formát, který Vám ušetří mnoho času.
Další otázka vyvstává při zpracování odpovědí Aleph API. Odpovědí je samotné mapování do NCIPu:
Mapování všech uživatelských dat v Aleph konektoru provádí SAX parser (Simple API for XML), jmenovitě AlephUserHandler.java
Výpůjčky uživatele zpracovává AlephItemHandler.java, zatímco uživatelovy požadavky, chcete-li žádosti, má na starosti AlephRequestItemHandler.java.
Kvalitní článek o SAX parsování naleznete na JournalDev.
Patron -> Address
Stávající verze konektoru odtud sbírá adresu uživatele v nestrukturovaném formátu a to z toho důvodu, že málokterá knihovna je opravdu v databázi strukturalizuje, resp. využívá polí z304-address-1 až z304-address-5 k rozeznání uložených dat. Toto rozhodnutí je pochopitelné pakliže vezmeme v úvahu nejednoznačnost označení těchto polí.
Dále je zde možno nalézt telefonní číslo/a, elektronickou adresu, či poštovní směrovací číslo, přičemž lze všechny tyto údaje využít při mapování do NCIP služby LookupUser.
Patron -> Blocks
Zde nalezneme všechny blokace přidělené uživateli. Využití hledejme opět pouze u LookupUser.
Patron -> Registration
Zdejší údaje vypovídají o pravomocích uživatele. Využití - LookupUser.
Patron -> Circulation Actions
Zde se nabízí možnost získat informace o zůstatku na účtu v knihovně, počtu výpůjček, žádostí a detailů pokut, resp. sankcí/poplatků.
Všechny tyto údaje mají tedy využití ve službě LookupUser a CreateUserFiscalTransaction.
Patron -> Loans
Tady jsou k nalezení všechny aktuální i neaktuální výpůjčky. Použití je tedy jednak v získávání půjčených titulů a datumů vrácení, jednak ve výpisu historie výpůjček a onak v prodlužování výpůjční lhůty.
Informace o formátování žádosti na prodloužení výpůjčky hledejte zde.
Patron -> Requested Holds
Toto zákoutí slouží ke sběru informací o nevyřízených žádostech uživatele a k jejich případnému zrušení. Využití je tedy tentokrát u CancelRequestItem a LookupRequest.
Patron -> Records -> Hold
Existence této služby je založena na možnosti poslat sem PUT HTTP request tak, aby se zaevidovala žádost, tedy proběhla služba RequestItem. Více o formátování PUT HTTP requestu zde.
Records
Tato část Alephu se do NCIP mapuje pouze ke službám LookupItem a LookupItemSet.
Record -> Items
Jak již bylo řečeno, využití těchto údajů se, vzhledem k NCIP, nachází ve službách vyhledávání titulů a exemplářů.
Ukládají se zde tedy pouze informace o těchto typech dat.
Aleph X-Services
X-Services se s ohledem na nízkorozpočtové organizace nepoužívá téměř vůbec. Je však použito k ověření uživatelem zadaného hesla, zda je správné. Znát správnost uživatelem zadaného hesla se může hodit například při ověřování jeho identity v jakési front-end aplikaci s grafickým rozhraním (v našem případě je to VuFind).
Více o ověření identity uživatele přes X-Services najdete zde.
Nebo si prostudujte jak to funguje uvnitř toolkitu. Doporučujeme k tomu použít Eclipse a ladit řádek po řádku a snažit se pochopit, proč se na jednotlivých místech ve zdrojovém kódu vyskytují jednotlivé proměnné a proč mají zrovna tu hodnotu, kterou vidíte.
Konfigurace konektoru
Jak již bylo zmíněno dříve, funkci konfiguračního souboru plní příslušný toolkit.properties: core/trunk/service/src/main/java/org/extensiblecatalog/ncip/v2/service/toolkit.properties
Po implementaci nové služby je zapotřebí do tohoto souboru uvést cestu k třídě, která plní danou funkci. My jsme například po implementaci služby Lookup Item zahrnuli tento řádek: LookupItemService.class=org.extensiblecatalog.ncip.v2.aleph.AlephLookupItemService, protože se třída, kterou jsme vyvinuli, jmenuje AlephLookupItemService.java
A na závěr je třeba do konfigurace zahrnout i informace o URL serveru a jeho portu, na kterém poběží Java Servlet, názvech knihoven používaných v API a dalších kustomizačních položkách se sebevysvětlujícími názvy.