.. _comm_zpusob:

====================
Způsob komunikace
====================

Komunikaci na základě :ref:`případů užití <metodika_usecase>` lze rozdělit 
na několik hlavních oblastí:

 - :ref:`informace o balíčcích <comm_zpusob_pkgs>`
 - :ref:`přístup k balíčkům a jejich obsahu <comm_zpusob_content>`
 - :ref:`zobrazení komponent balíčku <comm_zpusob_view>`
 - :ref:`ukládání změn v balíčcích <comm_zpusob_update>`

Jednotlivé oblasti jsou pokryty k tomu určenou sadou funkcí. Tyto
funkce jsou realizovány pomocí dvou typů rozhraní:

 - :ref:`comm_baseapi`
 - :ref:`comm_batchapi`

Komunikace u obou typů rozhraní vychází vždy ze strany softwaru 
pro zpracování archiválií a digitální archiv reaguje na jednotlivé
příchozí požadavky.

.. _comm_zpusob_pkgs:

Informace o balíčcích
======================

Informacemi o :term:`balíčcích <balíček>` rozumíme předání 
seznamu dostupných balíčků v :term:`digitálním archivu <digitální archiv>` 
do :term:`software pro zpracování` archiválií. 
Jedná se o balíčky, které mají nebo mohou být pomocí softwaru 
:term:`zpracovávány <zpracování>` a k nimž má uživatel (technický účet), 
resp. :term:`archiv` přístup.

Druhou částí tohoto rozhraní je možnost periodického dotazování na změny v balíčcích.
Změnami rozumíme nové přírůstky (přidané informační balíčky) a také informační 
balíčky, v nichž došlo ke změně. Změna balíčku je indikována jeho novou verzí, 
podrobněji viz :ref:`pkgs_version`.

.. plantuml::
    :caption: Zjištění informací o balíčcích
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++: Zjištění prvotního seznamu balíčků
    return Seznam ID AIPů, token pro další dotaz

    group Opakování dotazů na změny
      elza -> da ++: Zjištění dalších změn (předání tokenu pro další dotaz)
      return Seznam změn (i prázdný), token pro další dotaz
    end


.. _comm_zpusob_content:

Přístup k balíčkům a jejich obsahu
====================================

Přístupem k :term:`balíčkům <balíček>` a jejich obsahu je chápána sada funkcí, které 
umožňují zjistit souhrnné informace o balíčku. Těmi jsou 
například informace o dataci uložených archiválií, příslušnost 
k archivnímu souboru, identifikace přejímky a další.

Následně je možné začít zpracovávat jeden nebo více vybraných 
balíčků. Za tímto účelem je nutné načíst inherentní popisná metadata,
zjistit jaké :term:`komponenty <komponenta>` jsou uloženy v archivním balíčku a jakým 
způsobem jsou popsány v archivním popisu.

Archivář v závislosti na povaze uložených dat v balíčku má 
možnost vyžádat nejen metadata balíčku, ale i obsah 
vybraných nebo všech datových komponent. Vyžádané komponenty 
lze dále prohlížet a na základě jejich obsahu archiválie 
zpracovávat.

Následující diagramy zobrazují uvedené tři dílčí funkcionality:

Zjištění souhrnných metadat balíčku
-------------------------------------

Cílem funkcionality je získat pro jeden nebo více balíčků soubor 
:file:`PACKAGE-INFO.xml`. Ten obsahuje souhrnná metadata balíčku.

.. plantuml::
    :caption: Zjištění souhrnných metadat balíčku
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++ : Žádost o souhrnná metadata balíčku
    return Vrací číslo dávky

    group Čekání na připravení metadat balíčku
      elza -> da ++ : Zjisti stav dávky (předání čísla dávky)
      return Vrací stav dávky
    end

    elza -> da ++ : Vyžádání připravené dávky (předání čísla dávky)
    return Vrací PACKAGE-INFO.xml
    note over elza, da: PACKAGE-INFO.xml obsahuje souhrnná metadata balíčku



Zjištění popisných metadat balíčku
-------------------------------------

Cílem funkcionality je získat pro jeden nebo více balíčků jejich 
metadata, a to minimálně v rozsahu: :file:`METS.xml`, :file:`popisná metadata (EAD)`, 
:file:`metadata o uchovávání (PREMIS)`. 
Na základě znalosti těchto metadat je možné zobrazit náhled na obsah 
balíčku.

.. plantuml::
    :caption: Zjištění popisných metadat balíčku
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++ : Žádost o úplná metadata balíčku
    return Vrací číslo dávky

    group Čekání na připravení balíčku s metadaty
      elza -> da ++ : Zjisti stav dávky\n(předání čísla dávky)
      return Vrací stav dávky
    end

    elza -> da ++ : Vyžádání připravené dávky\n(předání čísla dávky)
    return Vrací složku s metadaty
    note over elza, da: METS.xml + všechny metadatové soubory balíčku

.. _comm_zpusob_content_download:

Stažení datových komponent balíčku
-------------------------------------

V uživatelském rozhraní je možné vyžádat vybranou (vybrané) :term:`komponenty <komponenta>`
pro daný :term:`balíček`, případně vyžádat sadu balíčků se všemi komponentami.

Pro nahlížení obsahu datových komponent je určeno samostatné API, 
viz :ref:`comm_zpusob_view`. Stažení je primárně určeno pro možnost 
přímého zkoumání komponent, nikoli jejich nahlížení.


.. plantuml::
    :caption: Stažení datových komponent balíčku
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++ : Žádost o vybrané komponenty k balíčku
    return Vrací číslo dávky
    note over elza, da: METS.xml + všechny metadatové soubory balíčku    

    group Čekání na připravení balíčku s metadaty
      elza -> da ++ : Zjisti stav dávky (předání čísla dávky)
      return Vrací stav dávky
    end

    elza -> da ++ : Vyžádání připravené dávky (předání čísla dávky)
    return Vrací složku s metadaty
    note over elza, da: METS.xml + všechny metadatové soubory balíčku


.. _comm_zpusob_view:

Zobrazení komponent balíčku
=============================

Za účelem :term:`zpracování` archiválií je nutné mít k dispozici možnost 
zobrazení vybrané :term:`komponenty <komponenta>` formou náhledu (např. PDF dokument).
:term:`Digitální archiv <digitální archiv>` může přímo poskytovat funkce
pro nahlížení obsahu vybraných komponent bez nutnosti jejich přenosu do aplikace. 
Jedná se o preferovanou variantu způsobu přístupu ke komponentám oproti 
:ref:`comm_zpusob_content_download`.

Tímto způsobem je řešeno nahlížení jen vybraných datových formátů 
a digitální archiv nemá možnost zprostředkovat náhled na všechny 
typy obsahu. Při zobrazení náhledu komponenty je nutné zjistit,
zda je náhled podporován a následně je možné zobrazení. Zobrazení 
některých komponent může trvat delší dobu, v určitých případech dochází
k zpřístupnění až po delší době (například z důvodu aktivace emulace).

.. plantuml::
    :caption: Zobrazení komponent balíčku
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++ : Dotaz, zda je formát možné zobrazit
    return Vrací informaci o možnosti zobrazení
    note over elza, da: Předá se identifikátor formátu dle PREMIS

    alt Zobrazení je možné v DA
      elza -> da : Požadavek na zobrazení
      da --> elza : Zpráva o úspěšném zobrazení
    else #LightBlue Nepodporovaný formát
      elza -> da ++ : Získání komponenty z DA
      return Přijetí komponenty

      elza -> elza : Zobrazení komponenty v aplikaci
    end


.. _comm_zpusob_update:

Ukládání změn v balíčcích
===========================

Při :term:`zpracování` archiválií dochází k tvorbě :term:`archivního popisu <archivní popis>`
a také v některých případech k přidávání komponent (souborů) 
do :term:`balíčku <balíček>`. Výsledek zpracování (:term:`kontextuální archivní popis`,
případně i přidané :term:`komponenty <komponenta>`) lze zaslat zpět do 
:term:`digitálního archivu <digitální archiv>`.

Z pohledu digitálního archivu je příjem změn do balíčku 
poměrně komplexní proces, kdy změna má obvykle charakter 
změnového balíčku. Tento musí být řádně zkontrolován a v případě 
akceptace budou změnové informace zapsány do datového úložiště a 
do příslušného modulu správy dat.

Balíčky jsou do digitálního archivu předány formou dávky, avšak 
jejich zápis do dalších procesů obvykle probíhá po jednom balíčku.
Předání dávky balíčků do digitálního archivu není obvykle atomickou transakcí,
ale jedná se o sadu dílčích požadavků, kdy některé 
mohou být provedeny a jiné odmítnuty. Důvody odmítnutí je nutné 
předat zpět do aplikace pro zpracování.


.. plantuml::
    :caption: Ukládání změn v balíčcích
    :scale: 70%
    :align: center 

    skinparam style strictuml
    actor "Software pro zpracování / ELZA" as elza
    participant "Digitální archiv" as da

    elza -> da ++ : Předání změnových balíčků
    return Vrací číslo dávky
    note over elza, da: Dávka je tvořena jedním nebo více balíčky

    group Čekání na zpracování změnových balíčků
      elza -> da ++ : Zjisti stav dávky (předání čísla dávky)
      return Vrací stav dávky
    end

    elza -> da ++ : Vyžádání výsledku zpracování (předání čísla dávky)
    return Vrací výsledek změny
    note over elza, da: Pro každý balíček je uveden výsledek\n - přijat nebo případná chyba s uvedením podrobnosti