Požadavek transform

Důležité upozornění – rozpor mezi názvem složky a názvem uzlu

Složka této stránky (requests/other/tranform) je pojmenována tranform, ale funkční kořenový element požadavku je transform. Uzel <tranform> (bez druhého „s“) server nezpracuje jako tento požadavek – spadne do obecného zpracování neznámého uzlu a vrátí <unknown-request-response name="tranform"/>. Tato stránka proto dále popisuje uzel transform; název složky zůstal beze změny podle zadání revize.

Účel a dopady

Provede posloupnost kroků (XSLT transformace a/nebo vnořené serverové požadavky) nad vstupním XML/JSON obsahem a vrátí výsledek poslední transformace. Konkrétní vedlejší účinky závisí na tom, co jednotlivé kroky perform-request uvnitř sekvence dělají – požadavek sám o sobě nic nemění, deleguje zpracování na solveQuery (stejný dispatcher, který zpracovává i běžné požadavky nejvyšší úrovně) a na XSLT procesor.

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

• Dostupné každému přihlášenému uživateli; požadavek sám nevyžaduje žádné zvláštní oprávnění. Konkrétní kroky perform-request podléhají stejným oprávněním, jako by byly odeslány přímo.
• 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>
   <transform
    stop-on-error="{bool}"
    stop-on-empty="{bool}"
    stop-on-param-error="{bool}"
    id="{string}"
    opt-roles="{string}"
    encode="{string}"
    >
    <input ... /> ?
    <steps ... /> ?
   </transform>
  </request>

Parametry a pravidla (atributy, potomci)

• stop-on-error - Zastavit při chybě - Výchozí hodnota pro <input> i pro každý krok v <steps>, které ji sami nepřepíšou vlastním atributem stejného jména. (typ: bool; nepovinný; výchozí: false)
• stop-on-empty - Zastavit při prázdném výstupu - Stejný princip dědění jako u stop-on-error, jen se týká kroků v <steps> (u <input> se nepoužívá). (typ: bool; nepovinný; výchozí: false)
• stop-on-param-error - Zastavit při chybě parametru šablony - Stejný princip dědění, uplatní se jen u parametrů perform-transform. (typ: bool; nepovinný; výchozí: false)
• id - Identifikátor transformace - Echoem přenesen do kořenového uzlu odpovědi, i do některých chybových odpovědí. (typ: string; nepovinný)
• opt-roles - Volitelná role - Přepíše roli použitou při zpracování vnořených požadavků perform-request; prázdný řetězec se chová jako neuvedeno. (typ: string; nepovinný; výchozí: role volajícího)
• encode - Kódování výsledného výstupu - Použije se až na finální obsah po dokončení všech kroků. (typ: enum; nepovinný; výchozí: syrový výstup beze změny; povolené rozpoznávané hodnoty: base64, hex, url, json; jakákoli jiná hodnota – včetně xml nebo plain – i chybějící atribut vedou ke stejnému výchozímu syrovému výstupu)

Potomci: input (nejvýše jednou) a steps (nejvýše jednou), oba nepovinné. Bez <steps> neproběhne žádný krok (výsledkem je prázdný výstup) a bez <input> je vstupem prázdný obsah.

Závislosti

• Atribut stop-on-error uvedený přímo na <input> přepisuje kořenovou hodnotu jen pro zpracování vstupu; obdobně stop-on-error/stop-on-empty/stop-on-param-error uvedené přímo na perform-transform/perform-request přepisují kořenovou hodnotu jen pro daný krok. Není-li atribut na <input>/kroku uveden, platí hodnota zděděná z kořenového transform.
• Atribut encode nemá tuto dědičnost. Na rozdíl od stop-on-* se encode na <input> (řídí dekódování vstupu) a encode na kořenovém transform (řídí kódování výstupu) vyhodnocují zcela nezávisle; žádný z nich se nedědí do jednotlivých kroků steps.

Uzel input

  <input
   encode="{string}"
   >
   <{element} ... > ... </{element}> ?
  </input>

• encode - Kódování vstupu - Určuje, jak se má přečíst obsah elementu input, než vstoupí do prvního kroku. (typ: enum; nepovinný; výchozí: syrový vnitřek elementu beze změny; povolené rozpoznávané hodnoty: hex, base64, url, json; jakákoli jiná hodnota – včetně xml – i chybějící atribut vedou k tomu, že se použije syrový vnitřní XML/textový obsah elementu input beze změny)

Potomek: nejvýše jeden libovolný element (nepovinný); je-li prvním krokem v steps perform-request, použije se tento potomek přímo jako tělo vnořeného požadavku (bez ohledu na encode="json" výše, které v tomto případě řídí jen převod z JSON, ne konečné zpracování).

Uzel steps

  <steps>
   <perform-transform ... /> *
   <perform-request ... /> *
  </steps>

Potomci se zpracovávají v pořadí, v jakém jsou uvedeny (nezávisle na typu), výstup každého kroku je vstupem kroku následujícího.

Důležité omezení: textové či whitespace uzly mezi elementy ve <steps> (typicky odsazení formátovaného XML) mohou přerušit návaznost kroků. Zadávejte proto kroky bez mezer mezi elementy, například na jediný řádek.

Uzel perform-transform

  <perform-transform
   xslt="{string}"
   stop-on-error="{bool}"
   stop-on-empty="{bool}"
   stop-on-param-error="{bool}"
   >
   <param
    name="{string}"
    value="{string}"
    /> *
  </perform-transform>

• xslt - Cesta k XSLT šabloně - Relativní cesta k šabloně (vůči webovému kořeni serveru, případně přes virtuální cestu). (typ: string; povinný – bez něj krok vždy skončí chybou, viz „Chyby a reakce“)
• stop-on-error, stop-on-empty, stop-on-param-error - Přepis kořenové hodnoty jen pro tento krok - viz „Závislosti“ výše. (typ: bool; nepovinný)

Potomek param (0 a vícekrát): předává hodnotu proměnné do XSLT šablony.

• name - Název parametru šablony - Musí odpovídat některému z parametrů, které šablona deklaruje; jinak se předání buď potichu přeskočí, nebo vygeneruje chybu podle stop-on-param-error (viz „Chyby a reakce“). (typ: string; povinný)
• value - Hodnota parametru - (typ: string; povinný)

Uzel perform-request

  <perform-request
   stop-on-error="{bool}"
   stop-on-empty="{bool}"
   />

Bez potomků a bez dalšího obsahu. Použije aktuální mezivýsledek pipeline (výstup předchozího kroku, nebo přímo <input> je-li prvním krokem) jako tělo vnořeného požadavku a vrátí jeho odpověď (zabalenou v <response>) jako výstup tohoto kroku.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklad transform požadavku a příklad spouštění akcí pomocí zpráv/transformací.)

Zpracování a vedlejší účinky

• Server nejprve načte a případně dekóduje <input> podle jeho vlastního encode (viz výše), poté prochází <steps> v pořadí výskytu a mezivýsledek předává z kroku na krok.
• Viditelný type v odpovědi se nemusí shodovat s výsledkem každého kroku. Selže-li jednotlivý krok (perform-transform i perform-request) a příslušný stop-on-error/stop-on-empty/stop-on-param-error je pro tento krok false (výchozí), zpracování pokračuje dál a finální odpověď se přesto uzavře jako <transform type="ok">...</transform>. Klient tedy nemůže spoléhat jen na type="ok" jako důkaz, že proběhly všechny kroky bez chyby.
• Ověřené specifikum k chybě „Sablona neobsahuje zadany parametr“: na rozdíl od všech ostatních „stop“ větví (return false; hned po zápisu chyby) tato konkrétní větev (neznámý název parametru v <param>) return false nevolá, i když stop-on-param-error platí. Chybová značka <transform type="error" ...>...</transform> se sice zapíše do bufferu, ale zpracování dál pokračuje a na konci se za ni ještě připojí řádná uzavírající obálka <transform type="ok">...</transform> – odpověď pak obsahuje dva po sobě jdoucí uzly transform v jednom <response>.
• <input> s encode="json" jako prvním krokem perform-request: obsah <input> se z JSON převede na XML a přímo (bez re-serializace do textu) použije jako tělo vnořeného požadavku.

XML odpověď (syntax + popis)

  <response>
   <transform
    type="ok|error"
    id="{string}"
    >
    {string}
   </transform>
  </response>

• type - Výsledek - "ok" po dokončení všech kroků (viz výhrada v sekci Zpracování výše), "error" u větví, které se ukončují okamžitě (return false). (typ: enum; povolené hodnoty: ok, error)
• id - Identifikátor - Echem vrácená hodnota id z požadavku, byla-li uvedena. (typ: string)

Tělo úspěšné odpovědi je konečný mezivýsledek pipeline, případně zakódovaný podle kořenového atributu encode (viz výše).

Příklady odpovědi

(Zatím bez ověřeného příkladu; viz příklad transform požadavku.)

Chyby a reakce

Všechny níže uvedené chyby (kromě „Sablona neobsahuje zadany parametr“, viz výhrada výše) ukončují zpracování okamžitě a vrací type="error":

• detail="Pri nacitani vstupu doslo k chybe" – chyba při dekódování <input> (neplatný hex/base64, nebo neplatný JSON) a platí stop-on-error.
• detail="Sablona neni pristupna." – perform-transform/@xslt odkazuje na šablonu, kterou se nepodařilo zpřístupnit.
• detail="Definice kroku neobsahuje atribut s nazvem sablony" – perform-transform bez atributu xslt.
• detail="Pri vkladani parametru sablony doslo k chybe">{detail}:{reason}({name}:{value})</transform> – hodnotu parametru se nepodařilo do šablony vložit.
• detail="Sablona neobsahuje zadany parametr">{name}:{value}</transform> – param/@name neodpovídá žádnému parametru deklarovanému v šabloně; nezastavuje zpracování, viz výhrada výše.
• detail="Pri provadeni transformace doslo k chybe">{detail}:{reason}</transform> – samotná XSLT transformace selhala.
• detail="Transformace vratila prazdne XML">{detail}</transform> – transformace uspěla, ale výsledek je prázdné XML, a platí stop-on-empty.
• detail="Pri nacitani sablony doslo k chybe">{detail}:{reason}</transform> – šablonu se nepodařilo připravit k použití.
• detail="Pri provadeni pozadavku doslo k chybe">{syrový nezpracovaný vstup}</transform> – u perform-request se mezivýsledek nepodařilo naparsovat jako platné XML.
• detail="Pri provadeni pozadavku doslo k chybe"> + vnořené diagnostické uzly error + {dosud zapsaný výstup}</response></transform> – vnořený požadavek (solveQuery) v kroku perform-request selhal.
• detail="Pozadavek vratil prazdne XML">{vstup před krokem}</transform> – perform-request vrátil prázdné XML a platí stop-on-empty.

Všechny výše uvedené chyby (s výjimkou vnořeného diagnostického error u „Pri provadeni pozadavku doslo k chybe“ z perform-request) jsou otevírací/uzavírací značka s prostým textovým obsahem, ne vnořený typový uzel error.

Výraz pro identifikaci chyb v odpovědi serveru: transform[@type='error'].

Související požadavky

• action – další způsob spuštění definovaného zpracování v rámci požadavku.