Skip to content

Akubra

Jump to bottom
ppodsednik edited this page Jan 13, 2026 · 4 revisions

Akubra Repository

Tato stránka poskytuje detailní technický přehled modulu Akubra repository. Slouží jako hlavní referenční dokumentace pro vývojáře, kteří Akubru integrují nebo nad ní staví aplikační logiku.

Akubra je Java knihovna určená pro práci s Fedora/Akubra filesystemovým repozitářem a je navržena pro použití v distribuovaném prostředí s více instancemi aplikace.

1. Účel a role Akubry

Akubra představuje aplikační vrstvu mezi:

  • aplikační logikou (UI, služby, workflow),
  • fyzickým uložením dat na disku,
  • pomocnými infrastrukturními službami (Solr, Hazelcast).

Jejím cílem je:

  • poskytnout jednotné a stabilní Java API,
  • zajistit konzistenci dat při souběžném přístupu,
  • abstrahovat detaily filesystemu a indexace,
  • umožnit efektivní práci se strukturou digitálních objektů.

Akubra není:

  • uživatelské rozhraní,
  • vyhledávací engine pro koncové uživatele,
  • plnohodnotná implementace Fedora Commons.

2. AkubraRepository API

Centrální rozhraní

Veškerá interakce s repozitářem probíhá prostřednictvím rozhraní:

Toto rozhraní představuje jediný oficiální vstupní bod do Akubra repository.

Detailní popis metod, jejich kontraktů a očekávaného chování je udržován přímo ve zdrojovém kódu tohoto rozhraní.

Wiki dokumentace se záměrně soustředí na:

  • architekturu,
  • principy použití,
  • vazby na okolní infrastrukturu.

Aplikační kód by se měl vždy řídit aktuálním API rozhraní.

3. Konfigurace a inicializace

Základní kroky

Pro použití Akubry je nutné:

  1. nakonfigurovat cesty k filesystemovým úložištím,
  2. nastavit připojení k Solr serveru,
  3. nakonfigurovat Hazelcast pro distribuované zamykání,
  4. vytvořit instanci repozitáře pomocí factory.

Inicializace probíhá pomocí:

  • RepositoryConfiguration
  • HazelcastConfiguration
  • AkubraRepositoryFactory

Výsledná instance je obvykle poskytována jako singleton.

Příklad inicializace

Kompletní příklad vytvoření instance AkubraRepository (včetně konfigurace Hazelcastu a Solru) je uveden v README projektu Akubra:

https://github.com/ceskaexpedice/akubra/blob/master/README.md

Referenční implementace je také k dispozici v projektu Kramerius.

Přehled konfiguračních parametrů

Akubra vyžaduje několik konfiguračních oblastí, které jsou typicky poskytovány pomocí aplikační konfigurace (properties, XML, environment proměnné).

Filesystem – object store

Parametr Význam
objectStore.path Kořenový adresář FOXML objektů
objectStore.pattern Vzor adresářové struktury

Filesystem – datastream store

Parametr Význam
datastreamStore.path Kořenový adresář binárních dat
datastreamStore.pattern Vzor uložení datastreamů

Solr – processing index

Parametr Význam
solr.processing.host URL Solr serveru pro processing index

Hazelcast – distribuované zámky

Parametr Význam
hazelcast.server.addresses Adresy locks serveru
hazelcast.instance Název Hazelcast instance
hazelcast.user Identita klienta

Konkrétní názvy a způsob načítání parametrů závisí na hostitelské aplikaci (např. Kramerius).

4. Ukládání dat

Object store

Object store obsahuje:

  • FOXML 1.1 dokumenty,
  • jeden objekt = jeden FOXML soubor,
  • adresování pomocí PID.

FOXML objekt zahrnuje:

  • metadata (DC, MODS),
  • RDF vazby (RELS-EXT),
  • technické a administrativní datastreamy.

Datastream store

Binární data jsou ukládána odděleně:

  • FOXML obsahuje pouze odkazy na binární soubory,
  • fyzická struktura je řízena konfigurovatelnými vzory cest.

Toto oddělení umožňuje:

  • efektivní práci s velkými objemy dat,
  • nezávislé zálohování a migrace.

5. Souběžný přístup a distribuované zamykání

Akubra je navržena pro provoz v prostředí, kde nad jedním repozitářem pracuje více instancí aplikace současně.

Základní principy

  • zamykani se konfiguruje pomoci HazelcastConfiguration
  • pri neuvedeni konfigurace Akubra pracuje bez zamku. Pozor! Ma smysl pouze pro jednoduche aplikace
  • Nasledujici body plati za predpokladu pouziti HazelcastConfiguration:
  • zamykání je povinné pouze pro kritické operace,
  • čtecí operace nejsou obecně zamykány,
  • zápisové operace (ingest, update) mají zamykání vestavěné.

Hazelcast

Pro distribuované zámky Akubra využívá Hazelcast:

  • zámky jsou sdílené mezi JVM a servery,
  • zajišťují konzistenci FOXML i datastreamů,
  • jsou použity automaticky v Akubra core.

Explicitní API pro zámky

Rozhraní AkubraRepository poskytuje metody:

  • doWithReadLock(...)
  • doWithWriteLock(...)

Tyto metody umožňují uživateli:

  • zamykat větší logické celky,
  • řídit rozsah konzistence nad více objekty,
  • bezpečně kombinovat vlastní logiku s core Akubry.

Použité zámky jsou reentrantní.

Podrobný popis je uveden na stránce Locking-Model.md.

6. Processing index (Solr)

Akubra využívá Solr k vytváření tzv. processing indexu – interního technického indexu pro práci s relační strukturou dokumentů.

Processing index slouží k:

  • rychlému zjišťování vztahů mezi objekty,
  • navigaci ve stromové struktuře dokumentů,
  • eliminaci nutnosti parsovat RELS-EXT při každém dotazu.

Typické dotazy:

  • jaké stránky patří k dokumentu,
  • do kterých nadřazených objektů dokument náleží,
  • zda je objekt součástí více dokumentů (sbírky).

ProcessingIndex API

Rozhraní AkubraRepository poskytuje podrozhraní:

  • ProcessingIndex

které je určeno zejména pro:

  • UI aplikace,
  • administrační nástroje,
  • služby pracující se strukturou dokumentů.

7. Vztah k datovému modelu

Akubra je obecně nezávislá na konkrétním datovém modelu, nicméně v Kramerius 7 se používá ve spojení s:

  • FOXML 1.1,
  • RDF vazbami pro hierarchii objektů,
  • definovanými content modely.

Viz:

  • Data-Model.md

8. Kdy Akubru použít

Akubra je vhodná, pokud potřebujete:

  • filesystemový Fedora/Akubra repozitář,
  • bezpečný ingest v distribuovaném prostředí,
  • Java-first API,
  • oddělení perzistence dat od aplikační logiky.

9. Související projekty

Clone this wiki locally