Požadavek remove-document

Účel a dopady

Fyzicky odstraní vybrané dokumenty z databáze (aktuální i archivní), případně jen otestuje, zda by odstranění bylo možné (bez skutečného smazání). Vedlejší účinky: při skutečném odstranění zápis erase-log záznamu (eid) a smazání záznamů z obou databází v rámci jedné transakce. Zpracování sdílí se souběžným požadavkem erase-document stejnou vnitřní funkci.

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

• Smí použít jen uživatel s r_admin; jinak je požadavek zamítnut.
• Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <remove-document
    test="{string}"
    test-where="{string}"
    note="{string}"
    >
    <pdk-list ... />
   </remove-document>
  </request>

Parametry a pravidla (atributy, potomci)

• test - Režim testu - Porovnává se (bez ohledu na velikost písmen) jen s hodnotami "true" a "only"; jakákoli jiná hodnota (včetně "false") i chybějící atribut se chová stejně jako výchozí režim skutečného mazání bez testu. (typ: string; nepovinný; výchozí: chování jako "false"; povolené hodnoty s vlastním významem: true, only)
  • Bez atributu nebo s jinou hodnotou než true/only: dokumenty se rovnou mažou.
  • "true": před samotným mazáním proběhne ověření (existence dokumentu, případně u typů vyžadujících kontrolu referencí i test na reference) – pokud test projde, dokument je i tak skutečně smazán, test="true" tedy nezabraňuje mazání, jen před ním ověří přípustnost.
  • "only": neprovede se žádné mazání, jen se otestuje proveditelnost (viz test-where).
• test-where - Druh testu proveditelnosti - Má význam, jen když test="only". Hodnoty (case-insensitive): "history" (test proti historické databázi), "actual" (test proti aktuální databázi); jiná hodnota vede k chybě celého požadavku. Chybí-li test-where u test="only", server sám zvolí druh testu podle mazací schopnosti dokumentového typu. (typ: string; nepovinný)
• note - Poznámka k erase-logu - Volný text uložený k vytvořenému erase-log záznamu (eid); má efekt, jen když se skutečně maže (test je nepřítomné/jiné než only, nebo true) – v čistém testovacím režimu (only) se erase-log nezakládá, a note tak nemá žádný efekt. (typ: string; nepovinný)

Potomek: server zpracuje jen potomky pojmenované item uvnitř prvního přímého potomka uzlu remove-document. V praxi se používá pdk-list, jehož potomci item (atributy pdk, type) určují dotčené dokumenty.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Je-li test="only" a test-where má jinou hodnotu než history/actual, požadavek skončí okamžitě chybou ještě před zpracováním jakékoli položky (viz „Chyby a reakce“).
• V režimu skutečného mazání (test nepřítomné/false/true) server nejprve otevře jednu transakci nad aktuální i archivní databází a založí erase-log záznam (eid); v čistém testovacím režimu (only) se transakce ani erase-log nezakládají.
• Pro každý potomek item: dohledá dokumentovou třídu podle type a číslo pdk jako dkey. Nepodaří-li se to, vznikne pro danou položku chybová odpověď a každá další položka v dávce je jen označena jako přeskočená, ne vynechána beze stopy – stejný vzor jako u erase-document.
• Pro platnou položku v režimu skutečného mazání server u dokumentových typů bez potřeby kontroly referencí rovnou ověří existenci a smaže je. Pro typy vyžadující kontrolu referencí ji provede jen pokud byl uveden test="true" a mazání odmítne, pokud je dokument odjinud odkazován.
• Pro platnou položku v čistě testovacím režimu (test="only") se nic nemaže; server jen zjistí existenci nebo smazanost dokumentu a vypíše seznam dokumentů, které na něj odkazují. Tvar odpovědi položky je v tomto režimu jiný, viz „XML odpověď“.
• Po zpracování všech položek se transakce (byla-li otevřena) potvrdí, nebo vrátí zpět; selhání samotného potvrzení transakce má vlastní chybovou hlášku odlišnou od selhání v průběhu zpracování.

XML odpověď (syntax + popis)

  <response>
   <remove-document
    eid="{number}"
    status="ok|error"
    detail="{string}"
    >
    <document ... /> *
   </remove-document>
  </response>

Atribut eid je přítomen, jen když se jednalo o skutečné mazání (ne čistý test) a podařilo se zahájit transakci a založit erase-log.

Uzel document – režim skutečného mazání

  <document
   type="{string}"
   dkey="{string}"
   status="ok|error"
   detail="{string}"
   />

• type - typ dokumentu - Echo hodnoty item/@type z požadavku. (typ: string)
• dkey - klíč dokumentu - Echo hodnoty item/@pdk z požadavku. (typ: string)
• status - Výsledek - ok/error. (typ: enum; povolené hodnoty: ok, error)
• detail - Popis chyby - Přítomen jen při status="error". (typ: string)

Uzel document – čistě testovací režim (test="only")

  <document
   type="{string}"
   dkey="{number}"
   exists="{bool}"
   deleted="{bool}"
   status="ok|error"
   detail="{string}"
   >
   <referenced
    document="{string}"
    array="{string}"
    key="{string}"
    dkey="{number}"
    pkey="{number}"
    /> *
  </document>

• exists - Existuje - Zda dokument s daným dkey v databázi existuje. (typ: bool)
• deleted - Je smazán - Zda je záznam již označen jako smazaný (papírkový koš). (typ: bool)
• status - Výsledek testu - "ok" (bez referencí, resp. dokument neexistuje), "error" s prázdným detail="", pokud test nalezl aspoň jednu referenci (<referenced> potomky následují), nebo "error" s vyplněným detail, pokud test samotný selhal na databázové chybě. (typ: enum; povolené hodnoty: ok, error)
• Potomek referenced (0 a vícekrát) – jeden záznam za každý nalezený odkaz na testovaný dokument; document/array/key popisují odkazující dokument/oblast/pole, dkey/pkey jeho klíče.

Příklady odpovědi

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

Chyby a reakce

Chyby na úrovni celého požadavku (atribut status/detail uzlu remove-document):

• status="error" detail="Atribut test nema spravnou hodnotu." – test="only" a test-where má jinou hodnotu než history/actual.
• status="error" detail="K databazi se nepodarilo pripojit." – s možným vnořeným error.
• status="error" detail="Transakci se nepodarilo zahajit." – jen v režimu skutečného mazání.
• status="error" detail="Pri provadeni doslo k chybe, transakce byla vracena." – aspoň jedna položka selhala.
• status="error" detail="Pri potvrzovani transakce doslo k chybe, transakce byla vracena." – selhal commit.

Chyby na úrovni jedné položky document v režimu skutečného mazání:

• detail="Neplatne oznaceni dokumentu." – neznámý type nebo nečíselné pdk.
• detail="Preskocen z duvodu predchozi chyby." – nezpracováno kvůli dřívější chybě v dávce.
• detail="Dokument nepovoluje mazani." – daný dokumentový typ nepovoluje mazání.
• detail="Doslo k databazove chybe." – selhalo ověření existence.
• detail="Dokument neni oznacen jako smazany, ale mel byt." – interní nekonzistence stavu smazání.
• detail="Pri vymazu doslo k chybe, provedte test." – samotné smazání z databáze selhalo.

Chyby na úrovni jedné položky document v čistě testovacím režimu:

• status="error" detail="Doslo k databazove chybe" – databázová chyba při testu existence nebo referencí.
• status="error" detail="" (prázdné) – nalezena aspoň jedna reference, viz vnořené referenced.

Výraz pro identifikaci chyb v odpovědi serveru: remove-document[@status='error'], resp. remove-document/document[@status='error'] pro jednotlivé položky.

Související požadavky

• erase-document – promazání obsahu dokumentu při zachování dokumentu samotného (sdílí zpracovávací mechanismus).
• get-document – čtení dokumentu.