Požadavek get-scan-files

Účel a dopady

Zjistí stav a výsledky poslední úlohy do-scan-files naplánované na serveru – souhrnné počty souborů podle kategorie, volitelně i jejich jmenný výpis. Požadavek nic v databázi ani na serveru nemění, jen čte.

Dostupnost, kontext, oprávnění apod.

• Smí použít uživatel s r_admin nebo r_manage – na rozdíl od dosavadní dokumentace, která požadovala vlastnost uživatele p_admin; server tuto vlastnost nekontroluje.
• Podléhá standardnímu transakčnímu zpracování obálky <request> v rámci celého požadavku, samotný uzel ale žádnou vlastní transakční podmínku netestuje.

XML požadavek (syntax + popis)

  <request>
   <get-scan-files
    verbose="{bool}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• verbose - Detailní odpověď - Je-li "true", odpověď obsahuje kromě souhrnných počtů i jmenný výpis souborů v jednotlivých kategoriích (potomky ...-files); jinak jsou vráceny jen souhrnné počty. (typ: bool; nepovinný; výchozí: false)

Požadavek nemá žádné další potomky.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Chování se řídí tím, zda v plánovači serveru aktuálně běží úloha typu do-scan-files. Neběží-li žádná taková úloha právě teď, server bez dalšího zjišťování rovnou vrátí <get-scan-files type="in-progress"/> – tento název stavu navzdory významu „probíhá“ tedy paradoxně označuje situaci, kdy zrovna žádná úloha neběží; přesný důvod tohoto pojmenování není dále určen.
• Běží-li naopak úloha do-scan-files právě teď, server zavolá čtecí funkci getScanFiles, která zjistí uložený stav poslední analýzy z archivní databáze:
  • žádný záznam analýzy neexistuje → type="none";
  • záznam existuje, ale analýza nebyla dokončena (např. přerušení serveru v jejím průběhu) → type="not-complete";
  • selhání na úrovni databáze při zjišťování stavu → generická chyba (viz „Chyby a reakce“);
  • jinak je vrácen dokončený výsledek se stavem podle poslední provedené fáze: "scanned" (proběhla základní analýza), "placeholdered" (proběhlo rozšíření place-holder), "cross scanned" (proběhlo rozšíření cross), nebo "deleted" (proběhl výmaz). Na rozdíl od dosavadní dokumentace existují i stavy "placeholdered" a "cross scanned", ne jen "scanned"/"deleted".
• Při dokončeném výsledku volá databázovou proceduru pro počty souborů v jednotlivých kategoriích a při verbose="true" i proceduru pro jmenný výpis souborů dané kategorie.

XML odpověď (syntax + popis)

  <response>
   <get-scan-files
    type="{string}"
    descr="{string}"
    normal="{number}"
    lost="{number}"
    to-del="{number}"
    deleted="{number}"
    temp-to-del="{number}"
    temp-deleted="{number}"
    placeholdered-files="{number}"
    duplicated-files="{number}"
    >
    <lost-files ... /> ?
    <to-del-files ... /> ?
    <deleted-files ... /> ?
    <temp-to-del-files ... /> ?
    <temp-deleted-files ... /> ?
    <placeholdered-files ... /> ?
    <duplicated-files ... /> ?
   </get-scan-files>
  </response>

Na rozdíl od dosavadní dokumentace je jméno výsledkového atributu type, ne status.

Parametry a pravidla (atributy, potomci) – odpověď

• type - Stav - Viz výčet v sekci „Zpracování“ výše. (typ: enum; povolené hodnoty: in-progress, none, not-complete, error, scanned, placeholdered, cross scanned, deleted)
• descr - Popis chyby - Přítomen jen při type="error". (typ: string; nepovinný)
• normal, lost, to-del, deleted, temp-to-del, temp-deleted - Souhrnné počty - Přítomny jen u dokončeného výsledku (type = scanned/placeholdered/cross scanned/deleted); normal je počet souborů v pořádku (nalezených na obou stranách), lost počet souborů odkazovaných v databázi, ale chybějících ve file-systému, to-del/deleted počet souborů určených k výmazu / smazaných, temp-to-del/temp-deleted totéž pro dočasné soubory. (typ: number)
• placeholdered-files, duplicated-files - Rozšířené počty - Počet souborů nahrazených „place-holderem“, resp. počet zjištěných duplicit; přítomny jen u dokončeného výsledku. Tyto dva atributy dosavadní dokumentace vůbec nezmiňovala. (typ: number)

Potomci lost-files, to-del-files, deleted-files, temp-to-del-files, temp-deleted-files, placeholdered-files, duplicated-files (každý 0 nebo 1×) jsou přítomny jen při verbose="true" a jen pro kategorie, jejichž počet je nenulový; každý obsahuje odpovídající počet potomků file (viz sdílený typ scan-file-info).

Uzel file má oproti sdílenému typu scan-file-info dva další, podmíněné atributy: je-li soubor svázán s konkrétním dokumentem, obsahuje navíc doc (jméno tabulky/dokumentu) a key (číselný klíč záznamu) – sdílený typ v současné podobě tyto dva atributy nepopisuje.

Poznámka: dva potomky téhož jména placeholdered-files – jeden je atribut horního uzlu je číselný (placeholdered-files="{number}"), druhý je element-kontejner se stejným jménem obsahující <file> potomky; server je odlišuje pozicí (atribut vs. element), ne jménem.

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

• <get-scan-files type="in-progress"/> – v plánovači momentálně neběží žádná úloha typu do-scan-files (viz vysvětlení v „Zpracování“).
• <get-scan-files type="none"> … </get-scan-files> – úloha do-scan-files běží, ale žádný výsledek analýzy dosud neexistuje.
• <get-scan-files type="not-complete"> … </get-scan-files> – existující výsledek analýzy je nedokončený.
• <get-scan-files type="error" descr="Pri provadeni doslo k chybe"> + vnořené error + </get-scan-files> – selhání na úrovni databáze při zjišťování stavu nebo počtů. Jde o otevírací/uzavírací dvojici s možností 0 a více vnořených uzlů error.
• <get-scan-files status="error" detail="Nemate patricna opravneni"/> – volající nemá r_admin ani r_manage. Pozor, tato jediná chybová větev používá atributy status/detail, ne type/descr.
• Výraz pro identifikaci chyb v odpovědi serveru: get-scan-files[@type='error'] | get-scan-files[@status='error'].

Související požadavky

• do-scan-files – naplánování úlohy, jejíž výsledky tento požadavek čte.