Přejít na obsah
Flexideo
Skip to main content

Požadavek erase-document

Účel a dopady​

Nahradí ("promaže") obsah polí a oblastí označených v XDS jako mazatelné (erase-able) u vybraných dokumentů, ale samotný dokument a jeho vazby na ostatní dokumenty ponechá existovat – na rozdíl od remove-document, který dokument z databáze skutečně odstraní. Vedlejší účinky: zápis erase-log záznamu (uložené procedury p_ADDERASE/p_ADDERASEDOC/p_ADDERASEARRAY) a náhrada obsahu jednotlivých polí/oblastí v aktuální i archivní databázi v rámci jedné transakce nad oběma databázemi.

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.
  • Zpracování a odpověď mají společná pravidla se souběžným požadavkem remove-document; pro erase-document je vždy vynucen režim skutečného mazání obsahu ("erase"), atributy test/test-where (platné jen u remove-document) se u erase-document vůbec nečtou a nemají žádný vliv.

XML požadavek (syntax + popis)​

  <request>
   <erase-document
    note="{string}"
    >
    <pdk-list ... />
   </erase-document>
  </request>

Parametry a pravidla (atributy, potomci)​

  • note - Poznámka k erase-logu - Volný text uložený k vytvořenému erase-log záznamu (eid) jako poznámka autora akce. (typ: string; nepovinný)

Potomek: server zpracuje potomky pojmenované item uvnitř prvního přímého potomka uzlu erase-document, ať se tento obalový element jmenuje jakkoli. V praxi se používá pdk-list, jehož potomci item (atributy pdk, type) určují mazané dokumenty.

Příklady požadavku​

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

Zpracování a vedlejší účinky​

  • Server otevře jednu transakci nad aktuální i archivní databází a založí erase-log záznam (eid) přes addEraseLog; atribut note, je-li uveden, se uloží k tomuto záznamu.
  • Pro každý potomek item: dohledá dokumentovou třídu podle type a číslo pdk jako dkey. Nepodaří-li se to (neznámý typ nebo pdk nelze převést na číslo), vznikne pro danou položku chybová odpověď a zpracování zbylých položek v dávce pokračuje, ale každá další položka je jen označena jako přeskočená (viz „Chyby a reakce“) – na rozdíl od sql-query, kde jsou pozdější položky vynechány beze stopy.
  • Pro platnou položku server postupně ověří, že dokument povoluje mazání a existuje, zapíše záznam o smazání, zpracuje archivní data a projde všechny mazatelné oblasti dokumentu a jejich mazatelná pole. U polí s hashovaným obsahem navíc přepočítá a zaznamená hash. Kterýkoli dílčí krok může samostatně selhat s vlastním chybovým textem.
  • Po zpracování všech položek se transakce nad oběma databázemi buď potvrdí (úspěch), nebo vrátí zpět (neúspěch); selhání samotného potvrzení transakce má vlastní chybovou hlášku odlišnou od selhání v průběhu zpracování.
  • Nepodaří-li se transakci vůbec zahájit nebo se nepodaří připojit k databázi, žádná položka se nezpracuje.

XML odpověď (syntax + popis)​

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

Atribut eid (číslo erase-log záznamu) je přítomen, jen když se podařilo transakci zahájit a erase-log založit (tedy prakticky vždy, pokud request vůbec projde počátečním připojením k databázi) – viz „Chyby a reakce“.

Uzel document​

  <document
   type="{string}"
   dkey="{string}"
   status="ok|error"
   detail="{string}"
   >
   <error ... /> ?
  </document>
  • type - typ dokumentu - Echo hodnoty item/@type z požadavku. (typ: string)
  • dkey - klíč dokumentu - Echo hodnoty item/@pdk z požadavku (u chyby „Neplatne oznaceni dokumentu“ jde o doslovný, případně nečíselný text). (typ: string)
  • status - Výsledek zpracování položky - ok, jinak error. (typ: enum; povolené hodnoty: ok, error)
  • detail - Popis chyby - Přítomen jen při status="error". (typ: string)

Potomek error (0 a vícekrát, sdílený typ error) se objevuje jen u větví, které při chybě neuzavírají značku document rovnou (.../>), ale nechávají ji otevřenou a doplní diagnostiku – viz níž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 erase-document):

  • status="error" detail="K databazi se nepodarilo pripojit." – s možným vnořeným error (otevírací/uzavírací tvar) – připojení k aktuální nebo archivní databázi selhalo.
  • status="error" detail="Transakci se nepodarilo zahajit." – nepodařilo se zahájit transakci nebo založit erase-log záznam.
  • status="error" detail="Pri provadeni doslo k chybe, transakce byla vracena." – aspoň jedna položka v dávce selhala, transakce byla vrácena.
  • status="error" detail="Pri potvrzovani transakce doslo k chybe, transakce byla vracena." – všechny položky uspěly, ale selhalo samotné potvrzení (commit) transakce.

Chyby na úrovni jedné položky document (status="error", self-closing, bez vnořeného error, pokud není uvedeno jinak):

  • detail="Neplatne oznaceni dokumentu." – neznámý type nebo nečíselné pdk.
  • detail="Preskocen z duvodu predchozi chyby." – tato položka se vůbec nezpracovávala, protože dřívější položka ve stejné dávce už selhala.
  • detail="Dokument nepovoluje mazani." – dokument typu bez erase schopnosti (isEraseAble() == false).
  • detail="Dokument neexistuje.".
  • detail="Doslo k databazove chybe." – s vnořeným error – selhání ověření existence dokumentu.
  • Další interní chybové texty vázané na jednotlivé kroky mazání konkrétní oblasti/pole/hashe (např. „Pri zapisu do protokolu dokumentu doslo k chybe.“, „Spusteni procedury se nezdarilo.“, „Pri cteni hashovaneho polo doslo k chybe.“ – doslovný překlep v serverovém textu, „Pri nahrazovani obsahu doslo k chybe.“) – všechny stejného tvaru <document type dkey status="error" detail="…"> s vnořeným error.

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

Související požadavky​