Požadavek save-pseudo-document

Účel a dopady

Uloží jeden nebo více pseudo-dokumentů – sestav dat definovaných v XDS – tak, že je nejprve pomocí XSLT šablony daného pseudo-typu převede na běžné <save-document> XML, a to pak uloží úplně stejným mechanismem jako požadavek save-document. Vedlejší účinky jsou tedy shodné se save-document (zápis historie, zámky dokumentů, transakce).

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

• Požadavek neprovádí žádnou explicitní kontrolu role – přístup je fakticky řízen tím, zda pro dvojici (pseudo-typ, efektivní role) existuje na serveru nahraná XSLT šablona pro uložení, a následně privilegii, která uplatní vlastní mechanismus save-document nad výsledným dokumentem (viz save-document – Dostupnost).
• Podléhá standardnímu transakčnímu zpracování obálky <request> – přeskočení se zde ale řeší jinak než self-closing chybou: přeskočené položky se i tak objeví jako <save-result type="error" detail="Transakce byla preskocena"/> (viz „Zpracování“).

XML požadavek (syntax + popis)

  <request>
   <save-pseudo-document
    opt-roles="{string}"
    transactional="{bool}"
    >
    <{pseudo-typ} ...>...</{pseudo-typ}> *
   </save-pseudo-document>
  </request>

Parametry a pravidla (atributy, potomci)

• opt-roles - Volitelná role - Jediná role pro celý požadavek (na rozdíl od get-pseudo-document zde není podpora přepsání role u jednotlivých potomků). (typ: string; nepovinný)
• transactional - Atomicita dávky - "true" vynutí uložení všech potomků jako jedné atomické transakce; jinak platí výchozí hodnota daná konfigurací serveru. (typ: bool; nepovinný; výchozí: dle konfigurace serveru)

Potomek: libovolný počet kořenových elementů pseudo-dokumentů – jméno každého potomka je název pseudo-typu (type atribut se u tohoto uzlu nečte, na rozdíl od get-pseudo-document; typ se odvozuje přímo ze jména elementu). Přesný tvar vnitřního obsahu každého pseudo-dokumentu (atributy, potomci) určuje výhradně XSLT šablona pro uložení daného pseudo-typu na serveru.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklad uložení pseudo-dokumentu.)

Zpracování a vedlejší účinky

1. Pro každý potomek se nejprve natáhne (a mezipaměťuje) XSLT šablona pro uložení daného pseudo-typu a role a potomek se jí transformuje na fragment <save-document>...</save-document>. Selže-li kterákoli z těchto transformací, zpracování jako celek přechází do „přeskočeného“ režimu (viz níže) – další potomky se už netransformují ani neukládají.
2. Jednotlivé vzniklé fragmenty </save-document><save-document> na styku se odstraní, takže vznikne jediné souvislé XML se všemi transformovanými dokumenty jako přímými potomky.
3. Toto XML se zpracuje podle stejných pravidel uložení jako požadavek save-document: buď pro každý dokument zvlášť, nebo jednou pro celou dávku najednou, podle konfigurace serveru a atributu transactional.
4. Odpověď na tomto požadavku je záměrně zjednodušená oproti přímému save-document: úspěch generuje jen <save-result type="ok"/> bez doc-type/dkey/orig-dkey/hist-id; neúspěch generuje <save-result type="error" detail="Pri ukladani doslo k chybe"> s vnořeným <error> obsahujícím diagnostiku.
5. Pokud selže transformace (krok 1), připojení k databázi, nebo požadavek byl vyřazen transakčním přeskočením obálky, generuje se <save-result> pro KAŽDÝ potomek požadavku (ne jen pro ten, který selhal) – buď type="error" detail="Transakce byla preskocena" (self-closing), nebo type="error" detail="Transakce byla vracena" se stejným vnořeným <error> obsahem opakovaným pro všechny položky – jednotlivé položky dávky tak v tomto degradovaném režimu nejsou od sebe rozlišitelné.

XML odpověď (syntax + popis)

  <response>
   <save-pseudo-document>
    <save-result
     type="ok|error"
     detail="{string}"
     >
     <error ... /> ?
    </save-result> *
   </save-pseudo-document>
  </response>

Kořenový element odpovědi je vždy <save-pseudo-document> (stejné jméno jako požadavek) – ne <save-pseudo-document-result>, jak uváděla starší dokumentace. Potomek save-result má stejné jméno jako u save-document, ale podstatně chudší sadu atributů (viz „Zpracování“).

Příklady odpovědi

(Zatím bez ověřeného příkladu; viz příklad uložení pseudo-dokumentu.)

Chyby a reakce

• <save-result type="ok"/> – dokument (po transformaci a uložení mechanismem save-document) uspěl.
• <save-result type="error" detail="Pri ukladani doslo k chybe"><error>…</error></save-result> – uložení mechanismem save-document selhalo; vnořený <error> nese syrový diagnostický výstup tohoto vnitřního volání, ne standardní sdílený typ error.
• <save-result type="error" detail="Transakce byla preskocena"/> – celá dávka byla vyřazena přeskočením kvůli dřívější odvolané transakci v témže požadavku.
• <save-result type="error" detail="Transakce byla vracena"><error>…</error></save-result> – transformace, připojení k databázi nebo uložení selhalo dřív, než mohlo dojít k dokončení.

Výraz pro identifikaci chyb v odpovědi serveru: save-pseudo-document[save-result[@type='error']].

Související požadavky

• save-document – vnitřní mechanismus ukládání, který tento požadavek po transformaci XSLT šablonou používá.
• get-pseudo-document – čtení pseudo-dokumentu.