Požadavek get-key

Účel a dopady

Vyhradí a vrátí hodnotu identity (auto-increment pole) daného dokumentového typu, kterou lze později použít při ukládání nové instance dokumentu, aniž by ji server mezitím přidělil jinému požadavku. Požadavek sám o sobě nic neukládá do databáze – jde jen o rezervaci hodnoty generátoru identity v paměti serveru.

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

• Dostupné každému přihlášenému uživateli, který má k dokumentu právo zápisu, případně r_admin (ten ale obchází jen kontrolu práva k dokumentu jako celku, ne kontrolu konkrétního pole níže).
• Podléhá standardnímu transakčnímu zpracování obálky <request> – je-li požadavek součástí transakčního bloku a předchozí požadavek v dávce selhal (a avoid-transaction není použit), get-key se přeskočí. Toto omezení se týká jen get-key, ne max-key – viz tamní stránka.

XML požadavek (syntax + popis)

  <request>
   <get-key
    doc="{string}"
    xdsid="{number}"
    field="{string}"
    opt-roles="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• doc - Typ dokumentu - Typový název dokumentu definovaného v XDS, ve kterém se identita rezervuje. Chybí-li, požadavek vždy skončí chybou. (typ: string; nepovinný – fakticky ale nutný pro úspěch)
• xdsid - XDSID pole - Jedinečný identifikátor cílového pole (identity) v definici struktury dokumentu. Je-li uveden, má přednost před field. (typ: number; nepovinný)
• field - Název pole - Zamýšlená alternativa k xdsid. Při hledání pole podle jména server porovnává s názvy polí hodnotu atributu xdsid (nikoli field). Je-li uveden jen field bez xdsid, porovnávaná hodnota je prázdná a pole se prakticky nikdy nenajde, což vede k chybě „Nemate patricna opravneni“ i tam, kde by uživatel jinak právo měl. (typ: string; nepovinný; chování viz poznámka)
• opt-roles - Volitelná role - Přepíše efektivní roli použitou pro ověření práva k dokumentu i poli. Prázdný řetězec se chová jako neuvedeno. (typ: string; nepovinný; výchozí: role volajícího)

Požadavek nemá potomky.

Závislosti

• Cílové pole musí být nalezeno přes xdsid (nebo fakticky nefunkční field, viz výše), nesmí jít o primární klíč, musí jít o identitu a efektivní role musí mít k poli právo zápisu – jinak požadavek skončí chybou „Nemate patricna opravneni“, i má-li volající r_admin.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Server dohledá dokument podle doc v interním registru definic. Neexistuje-li, vrací se chyba „Neznamy dokument“.
• Existuje-li dokument, ověří se právo zápisu k dokumentu jako celku; tuto kontrolu může obejít r_admin.
• Poté se dohledá konkrétní pole (xdsid/field, viz omezení výše) a ověří se, že jde o platné, nikoli primární, identitní pole s právem zápisu pro efektivní roli.
• Je-li vše v pořádku, server vrátí aktuální hodnotu generátoru identity daného pole a posune interní čítač – vrácená hodnota je tím „spotřebována“ a nebude znovu přidělena. Nepoužije-li ji klient, v poli může vzniknout mezera (u nespojitých polí trvale, u spojitých se časem zaplní).
• value v odpovědi je vždy celé číslo (interní long long) – na rozdíl od staré dokumentace nikdy nejde o řetězec se znakem #.

XML odpověď (syntax + popis)

  <response>
   <get-key
    doc="{string}"
    status="ok|error"
    value="{number}"
    detail="{string}"
    />
  </response>

Odpověď je vždy jediná sebeuzavírající značka; nikdy neobsahuje vnořený uzel error.

• doc - Echo dokumentu - Přítomen vždy, když byl doc v požadavku uveden (i při chybě); chybí jen tehdy, nebyl-li uveden vůbec. (typ: string)
• status - Výsledek - "ok" při úspěchu, "error" při libovolné chybě. (typ: enum; povolené hodnoty: ok, error)
• value - Rezervovaná hodnota - Celočíselná hodnota identity. Přítomen jen při status="ok". (typ: number)
• detail - Popis chyby - Přítomen jen při status="error". (typ: string)

Příklady odpovědi

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

Chyby a reakce

• <get-key status="error" detail="Nespravna identifikace klice"/> – atribut doc nebyl v požadavku vůbec uveden.
• <get-key doc="…" status="error" detail="Neznamy dokument"/> – hodnota doc neodpovídá žádnému známému dokumentovému typu.
• <get-key doc="…" status="error" detail="Nemate patricna opravneni"/> – volající nemá právo zápisu k dokumentu (bez r_admin), nebo cílové pole nebylo nalezeno, je primárním klíčem, není identitou nebo efektivní role nemá k poli právo zápisu.
• <get-key status="error" detail="Transakce byla odvolana"/> / <get-key status="skip" detail="Transakce byla preskocena"/> – požadavek byl vyřazen standardním transakčním zpracováním obálky.
• Výraz pro identifikaci chyb v odpovědi serveru: get-key[@status='error'].

Související požadavky

• max-key – sdílí stejný blok zpracování, vrací nejvyšší již přidělenou hodnotu identity bez rezervace.